Percona Monitoring and Management

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:

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

uml diagram

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.

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.15.1/binary/tarball/pmm2-client-2.15.1.tar.gz

  2. Download the PMM Client package checksum file:

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

  3. Verify the download.

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

  4. Unpack the package and move into the directory.

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

  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.

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

  • Page updated 2021-04-08
Download PDF Manual

Contents

Previous page

DBaaS (Alpha)

Next page

MySQL and variants

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.