Monitor database with Percona Monitoring and Management (PMM)¶

In this section you will learn how to monitor the health of Percona Server for MongoDB with Percona Monitoring and Management (PMM) .

The Operator supports both PMM version 2 and PMM version 3.

It determines which PMM server version you are using based on the authentication method you provide. For PMM 2, the Operator uses API keys for authentication. For PMM 3, it uses service account tokens.

We recommend using the latest PMM 3.

PMM is a client/server application. It includes the PMM Server and the number of PMM Clients running on each node with the database you wish to monitor.

A PMM Client collects needed metrics and sends gathered data to the PMM Server. As a user, you connect to the PMM Server to see database metrics on a number of dashboards.

PMM Server and PMM Client are installed separately.

Considerations¶

If you are using PMM server version 2, use a PMM client image compatible with PMM 2. If you are using PMM server version 3, use a PMM client image compatible with PMM 3. Check Percona certified images for the right one.
If you specified both authentication methods for PMM server configuration and they have non-empty values, priority goes to PMM 3.
For migration from PMM2 to PMM3, see PMM upgrade documentation . Also check the Automatic migration of API keys page.

Install PMM Server¶

You must have PMM server up and running. You can run PMM Server as a Docker image, a virtual appliance, or in Kubernetes. Please refer to the official PMM documentation for the installation instructions.

Install PMM Client¶

PMM Client is installed as a side-car container in the database Pods in your Kubernetes-based environment. To install PMM Client, do the following:

Configure authentication¶

PMM3PMM2

PMM3 uses service accounts to control access to PMM server components and resources. To authenticate in PMM server, you need a service account token. Generate a service account and token . Specify the Admin role for the service account.

Warning

When you create a service account token, you can select its lifetime: it can be either a permanent token that never expires or the one with the expiration date. PMM server cannot rotate service account tokens after they expire. So you must take care of reconfiguring PMM Client in this case.

Get the PMM API key from PMM Server . The API key must have the role “Admin”. You need this key to authorize PMM Client within PMM Server.

From PMM UI From command line

Generate the PMM API key

You can query your PMM Server installation for the API Key using curl and jq utilities. Replace <login>:<password>@<server_host> placeholders with your real PMM Server login, password, and hostname in the following command:

PMM_SERVER_API_KEY=$(curl --insecure -X POST -H "Content-Type: application/json" -d '{"name":"operator", "role": "Admin"}' "https://<login>:<password>@<server_host>/graph/api/auth/keys" | jq .key)

Warning

The API key is not rotated automatically when it expires. You must manually recreate it and reconfigure the PMM Client.

Create a secret¶

Now you must pass the credentials to the Operator. To do so, create a Secret object.

Create a Secret configuration file. You can use the deploy/secrets.yaml secrets file.

PMM 3PMM 2

Specify the service account token as the PMM_SERVER_TOKEN value in the secrets file:

apiVersion: v1
kind: Secret
metadata:
  name: my-cluster-name-secrets
type: Opaque
stringData:
  ....
  PMM_SERVER_TOKEN: ""

Specify the API key as the PMM_SERVER_API_KEY value in the secrets file:

apiVersion: v1
kind: Secret
metadata:
  name: my-cluster-name-secrets
type: Opaque
stringData:
  ....
  PMM_SERVER_API_KEY: ""

Create the Secrets object using the deploy/secrets.yaml file.

kubectl apply -f deploy/secrets.yaml -n <namespace>

Expected output

secret/my-cluster-name-secrets created

Deploy the PMM Client¶

Update the pmm section in the deploy/cr.yaml file:
- Set pmm.enabled=true.
- Specify your PMM Server hostname / an IP address for the pmm.serverHost option. The PMM Server IP address should be resolvable and reachable from within your cluster.
- Check that the name of the Secret object that you created earlier is specified in the secrets.users field.
```
secrets:
  users: my-cluster-name-secrets
pmm:
  enabled: true
  image: percona/pmm-client:2.44.1-1
  serverHost: monitoring-service
```

Apply the changes:

kubectl apply -f deploy/cr.yaml -n <namespace>

Check that corresponding Pods are not in a cycle of stopping and restarting. This cycle occurs if there are errors on the previous steps:
```
kubectl get pods -n <namespace>
kubectl logs <cluster-name>-rs0-0 -c pmm-client -n <namespace>
```

Check the metrics¶

Let’s see how the collected data is visualized in PMM.

Log in to PMM server.
Click MongoDB from the left-hand navigation menu. You land on the Instances Overview page.
Select your cluster from the Clusters drop-down menu and the desired time range on the top of the page. You should see the metrics.
Click MongoDB → Other dashboards to see the list of available dashboards that allow you to drill down to the metrics you are interested in.

Configure Query Analytics¶

To analyze query execution on the PMM Query Analytics (QAN) dashboard, you must configure how PMM collects query data. Starting with Operator version 1.23.0, use the pmm.querySource option to choose the collection method:

profiler (default) — PMM reads query performance data from each database’s system.profile collection. This method requires you to enable profiling explicitly.
mongolog — PMM reads slow-query data directly from mongod log files. This method has minimal impact on the database and scales better in clusters with many databases. It requires PMM 3.3.0 or newer and the log collector enabled so that logs are written to /data/db/logs/.

See the PMM documentation on query source methods for a detailed comparison.

Configure the profiler query source¶

To use the default profiler query source, do the following:

enable profiling in PMM
Configure the Operator:
set the pmm.querySource option to profiler
enable profiling in the Percona Server for MongoDB, so PMM can collect query data. You can pass MongoDB options in several ways: edit the Custom Resource, via the ConfigMap or a Secret. Read more about changing MongoDB options.

This example shows how to configure profiler and pass the configuration via the configuration subsection of the deploy/cr.yaml manifest:

spec:
  pmm:
    enabled: true
    querySource: profiler
  replsets:
    - name: rs0
      size: 3
      configuration: |
        operationProfiling:
          slowOpThresholdMs: 200
          mode: slowOp
          rateLimit: 100

Apply the configuration:

kubectl apply -f deploy/cr.yaml -n <namespace>

Configure the mongolog query source¶

Version added: 1.23.0

To use mongolog, do the following:

Enable log collector so that mongod logs are available at /data/db/logs/ for the PMM Client

When using mongolog, configure log rotation carefully. Avoid moving or renaming active log files during rotation, as this can interrupt mongolog collection.

Set pmm.querySource to mongolog
Configure MongoDB to write slow operations to the mongod log.

Here’s the example configuration:

spec:
  pmm:
    enabled: true
    querySource: mongolog
  logcollector:
    enabled: true
  replsets:
    - name: rs0
      size: 3
      configuration: |
        operationProfiling:
          mode: off
          slowOpThresholdMs: 200

Apply the configuration:

kubectl apply -f deploy/cr.yaml -n <namespace>

Additional PMM Client parameters¶

Optionally, you can specify additional parameters for the pmm-admin add mongodb command in the pmm.mongodParams and pmm.mongosParams keys for mongod and mongos Pods respectively.

Warning

Do not pass username, password, service name, host, or query source in pmm.mongodParams or pmm.mongosParams. The Operator automatically manages these settings for you. Overriding them can break PMM monitoring.

When done, apply the edited deploy/cr.yaml file:

kubectl apply -f deploy/cr.yaml

Update the secrets file¶

The deploy/secrets.yaml file contains all values for each key/value pair in a convenient plain text format. But the resulting Secrets Objects contains passwords stored as base64-encoded strings. If you want to update the password field, you need to encode the new password into the base64 format and pass it to the Secrets Object.

To encode a password or any other parameter, run the following command:

on Linux on macOS

echo -n "password" | base64 --wrap=0

echo -n "password" | base64

For example, to set the new PMM Server token in the my-cluster-name-secrets object, do the following:

on Linux on macOS

kubectl patch secret/my-cluster-name-secrets -p '{"data":{"PMM_SERVER_TOKEN": '$(echo -n <new-token> | base64 --wrap=0)'}}'

kubectl patch secret/my-cluster-name-secrets -p '{"data":{"PMM_SERVER_TOKEN": '$(echo -n <new-token> | base64)'}}'

Last update: July 20, 2026
Created: July 20, 2026