Deploying Percona Monitoring and Management

PMM is designed to be scalable for various environments. If you have just one MySQL or MongoDB server, you can install and run both PMM server and PMM clients on one database host.

It is more typical to have several MySQL and MongoDB server instances distributed over different hosts. In this case, you need to install the PMM client package on each database host that you want to monitor. In this scenario, the PMM server is set up on a dedicated monitoring host.

In this chapter

Installing PMM Server

To install and set up the PMM Server, use one of the following options:


On each computer where PMM Client is installed, the following ports must be open. These are default ports that you can change when adding the respective monitoring service with the pmm-admin add command.

Verifying PMM Server

In your browser, go to the server by its IP address. If you run your server as a virtual appliance or by using an Amazon machine image, you will need to setup the user name, password and your public key if you intend to connect to the server by using ssh. This step is not needed if you run PMM Server using Docker.

In the given example, you would need to direct your browser to Since you have not added any monitoring services yet, the site will not show any data.

You can also check if PMM Server is available requesting the /ping URL as in the following example:

$ curl
{'version': '1.8.0'}

Installing Clients

PMM Client is a package of agents and exporters installed on a database host that you want to monitor. Before installing the PMM Client package on each database host that you intend to monitor, make sure that your PMM Server host is accessible.

For example, you can run the ping command passing the IP address of the computer that PMM Server is running on. For example:

$ ping

You will need to have root access on the database host where you will be installing PMM Client (either logged in as a user with root privileges or be able to run commands with sudo).

Supported platforms

PMM Client should run on any modern Linux 64-bit distribution, however Percona provides PMM Client packages for automatic installation from software repositories only on the most popular Linux distributions:

It is recommended that you install your PMM client by using the software repository for your system. If this option does not work for you, Percona provides downloadable PMM Client packages from the Download Percona Monitoring and Management page.

In addition to DEB and RPM packages, this site also offers:

  • Generic tarballs that you can extract and run the included install script.
  • Source code tarball to build your PMM client from source.


You should not install agents on database servers that have the same host name, because host names are used by PMM Server to identify collected data.

Storage requirements

Minimum 100 MB of storage is required for installing the PMM Client package. With a good constant connection to PMM Server, additional storage is not required. However, the client needs to store any collected data that it is not able to send over immediately, so additional storage may be required if connection is unstable or throughput is too low.

Connecting PMM Clients to the PMM Server

With your server and clients set up, you must configure each PMM Client and specify which PMM Server it should send its data to.

To connect a PMM Client, enter the IP address of the PMM Server as the value of the --server parameter to the pmm-admin config command.

Run this command as root or by using the sudo command

$ pmm-admin config --server

For example, if your PMM Server is running on, and you have installed PMM Client on a machine with IP, run the following in the terminal of your client. Run the following commands as root or by using the sudo command:

$ pmm-admin config --server
OK, PMM server is alive.

PMM Server      |
Client Name     | ubuntu-amd641
Client Address  |

If you change the default port 80 when running PMM Server, specify the new port number after the IP address of PMM Server. For example:

$ pmm-admin config --server


On each computer where PMM Client is installed, the following ports must be open. These are default ports that you can change when adding the respective monitoring service with the pmm-admin add command.

See also

What other options can I pass to pmm-admin config?
Run pmm-admin config --help

Collecting Data from PMM Clients on PMM Server

To start collecting data on each PMM Client connected to a PMM server, run the pmm-admin add command along with the name of the selected monitoring service.

Run the following commands as root or by using the sudo command.

Enable general system metrics, MySQL metrics, MySQL query analytics:
$ pmm-admin add mysql
Enable general system metrics, MongoDB metrics, and MongoDB query analytics:
$ pmm-admin add mongodb
Enable ProxySQL performance metrics:
$ pmm-admin add proxysql:metrics [NAME] [OPTIONS]

To see what is being monitored, run pmm-admin list. For example, if you enable general OS and MongoDB metrics monitoring, the output should be similar to the following:

$ pmm-admin list


PMM Server      |
Client Name     | ubuntu-amd64
Client Address  |
Service manager | linux-systemd

---------------- ----------- ----------- -------- ---------------- --------
---------------- ----------- ----------- -------- ---------------- --------
linux:metrics    mongo-main  42000       YES      -
mongodb:metrics  mongo-main  42003       YES      localhost:27017

See also

What other monitoring services can I add using the pmm-admin add command?
Run pmm-admin add --help in your terminal

Obtaining Diagnostics Data for Support

PMM Server is able to generate a set of files for enhanced diagnostics, which can be examined and/or shared with Percona Support to solve an issue faster.

Collected data are provided by the service, and cover the following subjects:

  • Prometheus targets
  • Consul nodes, QAN API instances
  • Amazon RDS and Aurora instances
  • Version
  • Server configuration
  • Percona Toolkit commands

You can retrieve collected data from your PMM Server in a single zip archive using this URL:



When changing to a new version of PMM, you update the PMM Server and each PMM Client separately.

Updating the PMM Server


Currently PMM Server doesn’t support updates from 1.x to 2.0. Just install the new PMM 2 following its official installation instructions.

The updating procedure of your PMM Server depends on the option that you selected for installing it.

If you are running PMM Server as a virtual appliance or using an Amazon Machine Image, use the Update button on the Home dashboard (see PMM Home Page) in case of available updates.


Updating the PMM Server from the PMM home page.

See also

How to update PMM Server installed using Docker?
Updating PMM Server Using Docker

Updating a PMM Client


Currently PMM Client has no compatibility between 1.x to 2.0. Coexistence of 1.x and 2.x clients is not supported as well. If you need PMM 2.x, remove the old pmm-client package and install the new pmm2-client one following its installation instructions.

When a newer version of PMM Client becomes available, you can update to it from the Percona software repositories:

Debian or Ubuntu
$ sudo apt-get update && sudo apt-get install pmm-client
Red Hat or CentOS
$ yum update pmm-client

If you installed your PMM client manually, remove it and then download and install a newer version.

Uninstalling PMM Components

Each PMM Client and the PMM Server are removed separately. First, remove all monitored services by using the pmm-admin remove command (see Removing monitoring services). Then you can remove each PMM Client and the PMM Server.

Removing the PMM Client

Remove all monitored instances as described in Removing monitoring services. Then, uninstall the pmm-admin package. The exact procedure of removing the PMM Client depends on the method of installation.

Run the following commands as root or by using the sudo command

Using YUM
$ yum remove pmm-client
Using APT
$ apt-get remove pmm-client
Manually installed RPM package
$ rpm -e pmm-client
Manually installed DEB package
$ dpkg -r pmm-client
Using the generic PMM Client tarball.

cd into the directory where you extracted the tarball contents. Then, run the unistall script:

$ ./uninstall

Removing the PMM Server

If you run your PMM Server using Docker, stop the container as follows:

$ docker stop pmm-server && docker rm pmm-server

To discard all collected data (if you do not plan to use PMM Server in the future), remove the pmm-data container:

$ docker rm pmm-data

If you run your PMM Server using a virtual appliance, just stop and remove it.

To terminate the PMM Server running from an Amazon machine image, run the following command in your terminal:

$ aws ec2 terminate-instances --instance-ids -i-XXXX-INSTANCE-ID-XXXX

See also

PMM Building Blocks
Overview of Percona Monitoring and Management Architecture
About using the pmm-admin add command
Adding monitoring services

Table Of Contents

Previous topic

Overview of Percona Monitoring and Management Architecture

Next topic

Running PMM Server via Docker

Contact Us

For free technical help, visit the Percona Community Forum.
To report bugs or submit feature requests, open a JIRA ticket.
For paid support and managed or professional services, contact Percona Sales.