Setting up PMM Client¶

PMM Client is a collection of agents and exporters that run on the host being monitored.

These sections cover the different ways to install PMM Client on a Linux node and register it with PMM Server. The options are:

• Option 1 – For Debian- or Red Hat-based distributions, install percona-release and use a Linux package manager (apt/dnf) to install PMM Client.
• Option 2 – For Debian- or Red Hat-based distributions, download .deb/.rpm PMM Client packages and install them
• Option 3 – For other Linux distributions, download and unpack generic PMM Client Linux binaries
• Option 4 – run PMM Client as a Docker container
• Option 5 – run PMM Client with Docker compose

When you have installed PMM Client, you must:

• Register the node with PMM Server
• Configure and add services according to type

Here is an overview of the steps involved for each option.

Before you start¶

• PMM Server is installed and running with a known IP address accessible from the client node.
• You have superuser (root) access on the client host.
• You have superuser access to any database servers that you want to monitor.
• These Linux packages are installed: curl, gnupg, sudo, wget.
• If using Docker, install it.
• System requirements
  • Operating system – PMM Client runs on any modern 64-bit Linux distribution. It is tested on supported versions of Debian, Ubuntu, CentOS, and Red Hat Enterprise Linux.
  • Disk – A minimum of 100 MB of storage is required for installing the PMM Client package. With a good connection to PMM Server, additional storage is not required. However, the client needs to store any collected data that it cannot dispatch immediately, so additional storage may be required if the connection is unstable or the throughput is low. (Caching only applies to Query Analytics data; VictoriaMetrics data is never cached on the client side.)

Install PMM Client with a package manager¶

Install on Debian-based distributions¶

1. Configure repositories.

   wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
   sudo dpkg -i percona-release_latest.generic_all.deb
   

2. Install the PMM Client package.

   sudo apt update
   sudo apt install -y pmm2-client
   

Install on Red Hat-based distributions¶

1. Configure repositories.

   sudo yum install -y https://repo.percona.com/yum/percona-release-latest.noarch.rpm
   

2. Install the PMM Client package.

   sudo yum install -y pmm2-client
   

Tip If you have used percona-release before, disable and re-enable the repository:

sudo percona-release disable all
sudo percona-release enable original release

Download and install PMM Client packages manually¶

1. Visit the Percona Monitoring and Management 2 download page.
2. Under Version:, select the one you want (usually the latest).
3. Under Software:, select the item matching your software platform.

4. Click to download the package file:

   • For Debian, Ubuntu: .deb
   • For Red Hat, CentOS, Oracle Linux: .rpm

(Alternatively, copy the link and use wget to download it.)

Here are the download page links for each supported platform.

• Debian 9 (“Stretch”)
• Debian 10 (“Buster”)
• Red Hat/CentOS/Oracle 7
• Red Hat/CentOS/Oracle 8
• Ubuntu 16.04 (“Xenial Xerus”)
• Ubuntu 18.04 (“Bionic Beaver”)
• Ubuntu 20.04 (“Focal Fossa”)

Install on Debian-based distributions¶

sudo dpkg -i *.deb

Install on Red Hat-based distributions¶

sudo dnf localinstall *.rpm

Download and unpack generic Linux binary package¶

1. Download the PMM Client package:

   sudo wget https://downloads.percona.com/downloads/pmm2/2.16.0/binary/tarball/pmm2-client-2.16.0.tar.gz
   

2. Download the PMM Client package checksum file:

   sudo wget https://downloads.percona.com/downloads/pmm2/2.16.0/binary/tarball/pmm2-client-2.16.0.tar.gz.sha256sum
   

3. Verify the download.

   sha256sum -c pmm2-client-2.16.0.tar.gz.sha256sum
   

4. Unpack the package and move into the directory.

   sudo tar xfz pmm2-client-2.16.0.tar.gz && cd pmm2-client-2.16.0
   

5. Run the installer.

   sudo ./install_tarball
   

6. Change the path.

   PATH=$PATH:/usr/local/percona/pmm2/bin
   

7. Set up the agent

   sudo pmm-agent setup --config-file=/usr/local/percona/pmm2/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin
   

8. Open a new terminal and run the agent.

   PATH=$PATH:/usr/local/percona/pmm2/bin pmm-agent --config-file=/usr/local/percona/pmm2/config/pmm-agent.yaml
   

9. In the first terminal, check.

   pmm-admin status
   

Remove PMM Client with a package manager¶

Remove on Debian-based distributions¶

1. Uninstall the PMM Client package.

   sudo apt remove -y pmm2-client
   

2. Remove the Percona repository

   sudo dpkg -r percona-release
   

Remove on Red Hat-based distributions¶

1. Uninstall the PMM Client package.

   sudo yum remove -y pmm2-client
   

2. Remove the Percona repository

   sudo yum remove -y percona-release
   

Run PMM Client as a Docker container¶

The PMM Client Docker image is a convenient way to run PMM Client as a preconfigured Docker container.

1. Pull the PMM Client docker image.

   docker pull \
   percona/pmm-client:2
   

2. Use the image as a template to create a persistent data store that preserves local data when the image is updated.

   docker create \
   --volume /srv \
   --name pmm-client-data \
   percona/pmm-client:2 /bin/true
   

3. Run the container to start PMM Agent in setup mode. Set X.X.X.X to the IP address of your PMM Server. (Do not use the docker --detach option as PMM agent only logs to the console.)

   PMM_SERVER=X.X.X.X:443
   docker run \
   --rm \
   --name pmm-client \
   -e PMM_AGENT_SERVER_ADDRESS=${PMM_SERVER} \
   -e PMM_AGENT_SERVER_USERNAME=admin \
   -e PMM_AGENT_SERVER_PASSWORD=admin \
   -e PMM_AGENT_SERVER_INSECURE_TLS=1 \
   -e PMM_AGENT_SETUP=1 \
   -e PMM_AGENT_CONFIG_FILE=pmm-agent.yml \
   --volumes-from pmm-client-data \
   percona/pmm-client:2
   

4. Check status.

   docker exec pmm-client \
   pmm-admin status
   

   In the PMM user interface you will also see an increase in the number of monitored nodes.

You can now add services with pmm-admin by prefixing commands with docker exec pmm-client.

Tip

• Adjust host firewall and routing rules to allow Docker communications. (Read more in the FAQ.)
• For help:

  docker run --rm percona/pmm-client:2 --help
  

Remove PMM Client as a Docker container¶

1. Stop pmm-client container.

   docker stop pmm-client
   

2. Remove containers.

   docker rm pmm-client
   

3. Remove the image.

   docker rmi $(docker images | grep "percona/pmm-client" | awk {'print $3'})
   

Run PMM Client with Docker compose¶

1. Copy and paste this text into a file called docker-compose.yml.

   version: '2'
   services:
     pmm-client:
       image: percona/pmm-client:2
       hostname: pmm-client-myhost
       container_name: pmm-client
       restart: always
       ports:
         - "42000:42000"
         - "42001:42001"
       logging:
         driver: json-file
         options:
           max-size: "10m"
           max-file: "5"
       volumes:
         - ./pmm-agent.yaml:/etc/pmm-agent.yaml
       environment:
         - PMM_AGENT_CONFIG_FILE=/etc/pmm-agent.yaml
         - PMM_AGENT_SERVER_USERNAME=admin
         - PMM_AGENT_SERVER_PASSWORD=admin
         - PMM_AGENT_SERVER_ADDRESS=X.X.X.X:443
         - PMM_AGENT_SERVER_INSECURE_TLS=true
       entrypoint: pmm-agent setup
   

   • Check the values in the environment section match those for your PMM Server. (X.X.X.X is the IP address of your PMM Server.)

   • Use unique hostnames across all PMM Clients (value for services.pmm-client.hostname).

2. Ensure a writable agent configuration file.

   touch pmm-agent.yaml && chmod 0666 pmm-agent.yaml
   

3. Run the PMM Agent setup. This will run and stop.

   sudo docker-compose up
   

4. Edit docker-compose.yml, comment out the entrypoint line (insert a #) and save.

   ...
   #        entrypoint: pmm-agent setup
   

5. Run again.

   sudo docker-compose up
   

Caution pmm-agent.yaml contains sensitive credentials and should not be shared.

Register node with PMM Server¶

Register your node (X.X.X.X is the IP address of your PMM Server).

pmm-admin config --server-insecure-tls --server-url=https://admin:admin@X.X.X.X:443

• X.X.X.X is the address of your PMM Server.
• 443 is the default port number.
• admin/admin is the default PMM username and password. This is the same account you use to log into the PMM user interface, which you had the option to change when first logging in.

Configure and add services¶

You should continue by adding services according to the service type.

• MySQL and variants (Percona Server for MySQL, Percona XtraDB Cluster, MariaDB)
• MongoDB
• PostgreSQL
• ProxySQL
• Amazon RDS
• Microsoft Azure
• Google Cloud Platform (MySQL and PostgreSQL)
• Linux
• External services
• HAProxy

Note To change the parameters of a previously-added service, remove the service and re-add it with new parameters.

Remove services from monitoring¶

You should specify service type and service name for removing from monitoring One of next types has to be set: mysql, mongodb, postgresql, proxysql, haproxy, external

pmm-admin remove <service-type> <service-name>

See also

• Percona release

• PMM Client architecture

• Thanks to https://gist.github.com/paskal for Docker compose files