Percona Monitoring and Management (PMM) 3 combines database and host metrics, dashboards, alerting, and Query Analytics for MySQL-family databases, PostgreSQL, MongoDB, and other supported services. A production setup has two parts: PMM Server stores and presents telemetry, while PMM Clients run agents and exporters close to monitored systems. The important work is not just starting containers. It is protecting credentials and query data, granting only reviewed access, preserving server state, and proving that dashboards and alerts continue through upgrades and failures.
Plan the architecture before installation
Place PMM Server on infrastructure with persistent storage, monitored capacity, backups, and a documented recovery owner. PMM Clients need outbound connectivity to the server, normally over HTTPS, and network access to the databases they collect from. Users need access to the web interface, but database ports and exporter endpoints do not need broad exposure. Decide whether local clients can collect node CPU, memory, and disk metrics or whether a remote-only service will expose database metrics without host visibility.
| Component | Responsibility | Failure to plan for |
|---|---|---|
| PMM Server | Inventory, telemetry storage, dashboards, QAN, alert rules, and users | Lost persistent volume, full disk, certificate expiry, or failed upgrade |
| PMM Client | Runs pmm-agent, exporters, and local collectors | Agent outage, network partition, stale token, or host resource pressure |
| Database account | Reads the engine sources required by selected collectors | Excess privilege, missing metrics, lockout, or secret leakage |
| Query source | Provides normalized query activity and optional examples | Sensitive literals, storage overhead, or misleading sampling gaps |
| Alert path | Evaluates rules and routes notifications | Copied thresholds, label explosion, bad routing, or silent contact-point failure |
Estimate storage and compute from the number of services, enabled collectors, scrape resolution, cardinality, and retention. Percona publishes sizing guidance, but those figures are planning inputs rather than guarantees. Canary a representative fleet, inspect ingestion and disk growth, and leave headroom for maintenance and temporary client buffering. PMM monitoring is itself a production service and needs its own availability and capacity alerts outside PMM.
Deploy PMM Server 3 with persistent storage
The current container line is percona/pmm-server:3. Pin an approved immutable image digest in production even if the example uses the major tag for readability. Docker volumes are the documented recommended persistence method. A minimal evaluated deployment looks like this:
docker pull percona/pmm-server:3
docker volume create pmm-data
docker run --detach --restart always \
--publish 443:8443 \
--volume pmm-data:/srv \
--name pmm-server \
percona/pmm-server:3The volume contains monitoring data, dashboards, configuration, and the PMM encryption key, so protect and back up the complete supported state rather than copying a few dashboard files. Restrict the Docker socket and container administration. Set retention and resolution only after measuring cost, and keep the PMM data volume off ephemeral instance storage. A single restarted Docker container is not host-level high availability; choose Kubernetes or another supported topology when the monitoring service has a stronger availability requirement.
PMM ships with a self-signed certificate for initial use, but Percona does not present that default as a properly secured production connection. Install a certificate whose hostname clients use, include the required chain and key files, and configure clients to trust its CA. Do not make --server-insecure-tls a permanent workaround. Restrict inbound 443 to approved users and clients, change default administrative credentials immediately, use named users or service accounts, and integrate the supported authentication controls for the environment.
Register clients without publishing secrets
Install pmm-client from the current PMM 3 repository or a pinned, verified package. A local client normally adds host metrics along with database metrics; a remote registration omits some host context. Keep clocks synchronized and allow the documented client-to-server connection. Use pmm-admin status and pmm-admin list to verify the node, agents, and services after registration.
PMM's current one-step UI workflow can mint a short-lived token and prompt for database credentials on the node. Prefer that prompt or a secret-manager injection over embedding credentials in shell history, process arguments, CI output, an image, or a repository. The URL form accepted by pmm-admin config can contain a user and password or service token; treat the entire URL as a secret, redact it from diagnostics, and rotate it if it appears in a log. Install the trusted CA on the client or set the documented CA bundle for pmm-agent rather than disabling verification.
# Run only after a trusted CA and a protected token source are prepared.
pmm-admin config --server-url='https://service_token:<TOKEN>@pmm.example.com:443'
pmm-admin status --wait=30s
pmm-admin listThe placeholder is not a credential. Supply a short-lived or scoped token through the approved local secret workflow, clear transient environment or files, and verify their permissions. PMM 3 encrypts sensitive values stored by the server, but encryption at rest does not protect a token exposed in a command log, terminal recording, support archive, or configuration backup.
Add MySQL with a dedicated account
Use a separate MySQL account constrained to the client host or network. The exact grants depend on engine family, release, query source, and whether PMM rotates slow logs. Current PMM 3 guidance for MySQL 8.x shows SELECT, PROCESS, REPLICATION CLIENT, RELOAD, and BACKUP_ADMIN with a connection cap. It does not require the old article's dangerous SUPER, UPDATE, DELETE, or DROP grants. Review whether every documented grant is needed for the collectors you enable and retest after reducing it.
CREATE USER 'pmm'@'10.20.30.25'
IDENTIFIED BY '<secret-from-approved-store>'
WITH MAX_USER_CONNECTIONS 10;
GRANT SELECT, PROCESS, REPLICATION CLIENT, RELOAD, BACKUP_ADMIN
ON *.* TO 'pmm'@'10.20.30.25';Require TLS for a remote account and configure PMM with CA verification. Test that an unneeded write and administrative statement are denied. Record why each global privilege exists, because PROCESS and broad SELECT reveal operationally sensitive data even though they do not grant table writes.
Add the service from the PMM UI when that keeps the database password out of automation logs, or use pmm-admin add mysql with a protected credential source. Set a stable service name and environment labels. Confirm Inventory shows one intended service rather than duplicates created during retries.
Choose MySQL Query Analytics deliberately
PMM can use Performance Schema or the slow query log as a MySQL QAN source. For Oracle MySQL 5.6 and later, current Percona guidance generally favors Performance Schema. It avoids log-file management and can be used for remote monitoring, but enabled instruments and history buffers affect coverage and memory. A query digest can remain visible after an individual example has already been overwritten.
The slow query log can provide more detailed examples and is recommended by Percona for some Percona Server releases, but a local client needs file access and the log needs a measured threshold and rotation policy. Do not enable long_query_time=0 or log_queries_not_using_indexes indiscriminately. Those settings can produce high I/O and log volume, and query text can contain personal data, tokens, or literals. Start from a workload-based duration, sample where supported, monitor log growth, and set an explicit rollback.
Use only one QAN source unless a documented experiment requires overlap. Compare the QAN digest with native Performance Schema or log evidence and a known canary query. Decide whether query examples are allowed; PMM exposes controls for disabling examples in supported PostgreSQL query sources and source-specific MySQL behavior. Limit access to QAN, set retention, and search telemetry for canary secrets before declaring the privacy controls complete.
Add PostgreSQL without inventing a privilege recipe
Current PMM 3 documentation recommends a dedicated PostgreSQL account with SUPERUSER for comprehensive self-managed monitoring, and rds_superuser for the documented Amazon RDS path. Those are powerful roles. Do not relabel pg_monitor alone as a drop-in, fully supported least-privilege replacement unless the exact PMM collectors, QAN source, PostgreSQL release, and dashboards have been tested. A reduced role can create silent gaps in statements, locks, settings, or database discovery.
Apply least privilege as a controlled exception process: create a dedicated login, restrict its network and connection count, enable TLS verification, enumerate the collectors and views required, start from the current vendor-supported grant set, and document every reduction plus the resulting coverage. If policy cannot accept the documented superuser path, test a reduced role in staging and monitor exporter errors and missing panels, or use the supported managed-service integration. Never reuse an application owner or human administrator simply because it already works.
Choose pg_stat_statements, pg_stat_monitor, or no QAN according to the installed extension and privacy requirements. Extension installation and preload changes belong to the database change process. Add PostgreSQL with --tls, --tls-ca-file, and the correct host and database, then verify certificate identity, service inventory, query-source state, and expected dashboards. The generic database monitoring guide explains how to map exported metrics back to native database sources.
Turn dashboards into incident workflows
A useful dashboard moves from symptom to bounded evidence. Begin with user-visible database latency, errors, availability, and freshness. Then inspect concurrency and waits, query digests, lock activity, replication state, connections, disk, CPU, memory, and engine-specific cache or WAL behavior. Correlation does not prove cause: a high CPU chart and a slow query can share a time window without one causing the other.
For MySQL, verify digest load, rows examined, lock time, temporary work, InnoDB reads and redo pressure, connections, and replication health. For PostgreSQL, verify transaction rate, session state and waits, statement statistics, dead tuples and vacuum, WAL, locks, checkpoints, and replication slots. Node dashboards supply host context only for registered nodes with the relevant collector. Managed services need provider metrics for platform-level limits PMM cannot observe directly.
Save a repeatable incident view with the same service, node, environment, and time range. Add deployment annotations and link each page to a runbook. Avoid dashboard variables or labels that include raw SQL, user IDs, request IDs, or other unbounded values. Cardinality is a storage and query-performance problem as well as a privacy problem.
Configure actionable alerts
PMM 3 supports built-in and custom alert templates, rules with a duration, contact points, and notification policies. Treat template thresholds as starting material. A static connection count, lag duration, or CPU percentage has no universal severity. Establish an objective and capacity model, inspect the production baseline, then choose a threshold and for duration that identify sustained risk with enough response time.
- Define the symptom. Page for unavailable databases, exhausted capacity blocking work, sustained application errors, or freshness outside an agreed boundary.
- Scope labels. Confirm filters match the intended service and environment without producing one page per query or container.
- Attach an action. Include owner, dashboard, current runbook, and safe first checks.
- Test delivery. Create a controlled condition, let it pass through pending to firing, verify the correct contact point, and observe recovery.
- Test silence and failure. Verify maintenance routing, contact-point failure, and an external dead-man check for PMM itself.
Operate upgrades, backup, and recovery
PMM Server and Client are upgraded separately. Read the current PMM 3 release notes and compatibility guidance, inventory client versions, and canary an upgrade. Percona's current Docker process requires a backup first and warns that downgrade is not available as an ordinary reversal; restoring the pre-upgrade state is the rollback. Use the supported manual container or orchestration workflow rather than relying on a deprecated UI upgrade path.
Back up the persistent PMM Server volume using the documented procedure and test restore into an isolated instance. Preserve custom dashboards, alert templates, contact points, labels, users, certificates, and the encryption key as part of the supported state. After restore, verify login, inventory, recent and historical metrics, QAN access, alerts, and client reconnection. A copied volume that has never started successfully is not a recovery plan.
Acceptance checklist
- PMM Server uses persistent storage, a trusted certificate, changed admin credentials, restricted networking, and an independent health check.
- Client registration tokens and database secrets are absent from repositories, shell history, logs, images, and diagnostic archives.
- Each database has a dedicated, reviewed monitoring identity; MySQL has no broad write grants, and PostgreSQL privilege exceptions are documented honestly.
- QAN source, overhead, query-example policy, access, and retention have been tested with a privacy canary.
- Dashboards show expected current data, exporter errors are zero, and missing metrics are distinguished from healthy zeroes.
- Alert routing, backup, restore, manual upgrade, client buffering, and server outage behavior have been exercised.