As a DBA, you're expected to know what's happening inside your databases at all times.
But here's the reality — most monitoring setups are either too generic (CPU is high!) or too custom (someone's 3-year-old Grafana dashboard nobody understands).
What if there was a tool built specifically for database engineers — one that understands query performance, replication lag, vacuum bloat, and connection saturation right out of the box?
That tool is Percona Monitoring and Management (PMM).
In this post, I'll walk you through everything you need to know about PMM 3 — what it is, how it works internally, how to install it, what features it brings, and which databases it supports.
Let's get into it.
What is PMM?
PMM (Percona Monitoring and Management) is a 100% free, open-source database observability and monitoring platform built by Percona.
It is NOT a generic infrastructure monitoring tool like Nagios or Zabbix.
PMM was purpose-built for DBAs who need to answer questions like:
- Which query is consuming the most database time?
- How far behind is my replica?
- Is my autovacuum keeping up with dead tuples?
- Are connections about to hit the limit?
- Which tables are approaching transaction ID wraparound?
Generic monitoring tools can't answer these. PMM can — and it does it with zero application-side instrumentation.
Think of PMM as a pre-assembled, database-aware monitoring stack that combines Grafana + VictoriaMetrics + ClickHouse + Prometheus + AlertManager into a single deployable unit, with 20+ pre-built dashboards per database engine.
The latest version is PMM 3.8.0, released on May 28, 2026.
Architecture Overview:
PMM uses a client-server architecture. The PMM Server collects, stores, and visualizes metrics from PMM Clients installed on database hosts. Communication happens over HTTPS (port 443) using gRPC streams.
This is the actual architecture I set up for my lab environment — PMM 3 Server running as a Docker container on an AWS EC2 instance (Ubuntu 26.04 LTS), monitoring both a PostgreSQL 18.4 server and a MySQL 8.4.9 server within the same AWS VPC (ap-south-1).
All communication flows over a single gRPC/HTTPS port 443 — no inbound ports needed on the database servers.
PMM Server
The PMM Server is a self-contained unit — deployed as a Docker container, Podman container, Helm chart on Kubernetes, Virtual Appliance (OVA), or AWS AMI.
It contains the following internal components:
PMM Client
The PMM Client is installed on the same machine as your database server. It runs a lightweight agent process.
How They Communicate
This is the part that surprises most people:
PMM uses a single port (443) for ALL communication.
The pmm-agent on the database server opens a persistent outbound gRPC tunnel to the PMM Server. All metrics, QAN data, and control plane messages travel through this single encrypted channel.
What this means practically:
- ✅ Your database server needs NO inbound firewall rules
- ✅ The exporters listen on localhost only — they are not exposed on the network
- ✅ PMM Server cannot execute queries against your database — it only receives data
Here's the high-level data flow:
Component Summary
Prerequisites & Dependencies:
PMM server Dependencies
Hardware Requirements (PMM Server):
Minimum: 2 vCPUs, 4 GB RAM, 20 GB disk
Recommended: 4+ vCPUs, 8+ GB RAM, 100+ GB disk (depends on number of monitored nodes)
PMM Client Dependencies :
Key Point: PMM Client 3.x is installed from a binary tarball — no package manager required. This makes it compatible with any Linux distribution without needing a specific repo.
Version Compatibility: PMM Client 3.x is required for PMM Server 3.x. The older pmm2-client package is NOT compatible with PMM Server 3 due to breaking API changes (endpoint changed from /v1/management/Node/Register to /v1/management/nodes).
Database-Specific Prerequisites
For PostgreSQL Monitoring:
- A dedicated monitoring user (e.g., pmm_user) with SUPERUSER or appropriate privileges
- pg_stat_statements extension loaded (shared_preload_libraries)
- pg_hba.conf configured for password authentication from 127.0.0.1
For MySQL Monitoring:
- A dedicated monitoring user (e.g., pmm) with appropriate grants
- performance_schema = ON (enabled by default in MySQL 8.x)
- Grants: SELECT, PROCESS, REPLICATION CLIENT, RELOAD, BACKUP_ADMIN
Network & Firewall Requirements
PMM Server Installation (On PMM Server Instance):
Install Docker Engine
1. Install prerequisites and add Docker's GPG key:
apt update && apt install -y ca-certificates curl gnupg lsb-release
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc2. Add Docker repository:
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "${VERSION_CODENAME}") stable" \
> /etc/apt/sources.list.d/docker.list3. Install Docker packages:
apt-get update && apt-get install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin4. Verify Docker installation:
docker --version Deploy PMM Server Container
Pull the PMM Server 3 image:
docker pull percona/pmm-server:3Create a Docker volume for persistent data:
docker volume create pmm-dataRun the PMM Server container:
docker run --detach --restart always \
--publish 443:8443 \
--volume pmm-data:/srv \
--name pmm-server \
percona/pmm-server:3Port Mapping Note: PMM Server 3 uses internal port 8443 (not 443 as in PMM 2). The --publish 443:8443 maps external port 443 to the container's 8443.
Wait ~60 seconds for services to start, then set the admin password:
docker exec -t pmm-server change-admin-password 'Testing123#'Verify PMM Server Health
Check the readiness endpoint:
curl -k https://localhost/v1/readyz
# Expected: {}Verify all internal services are running:
docker exec pmm-server supervisorctl status
Expected output (all RUNNING):
clickhouse RUNNING pid 69, uptime 0:01:12
grafana RUNNING pid 1016, uptime 0:01:06
nginx RUNNING pid 70, uptime 0:01:12
pmm-agent RUNNING pid 864, uptime 0:01:09
pmm-managed RUNNING pid 71, uptime 0:01:12
postgresql RUNNING pid 68, uptime 0:01:12
qan-api2 RUNNING pid 985, uptime 0:01:07
victoriametrics RUNNING pid 1061, uptime 0:01:06
vmalert RUNNING pid 931, uptime 0:01:07
vmproxy RUNNING pid 960, uptime 0:01:07PMM Client on PostgreSQL Server ( PostgreSQL instance)
Install PMM Client (Binary Tarball)
Download the PMM Client 3.8.0 tarball:
wget https://downloads.percona.com/downloads/pmm3/3.8.0/binary/tarball/pmm-client-3.8.0-x86_64.tar.gz
Extract and install:
tar xfz pmm-client-3.8.0-x86_64.tar.gz && cd pmm-client-3.8.0
export PMM_DIR=/usr/local/percona/pmm
sudo ./install_tarballAdd to PATH and create symlinks:
PATH=$PATH:$PMM_DIR/bin
sudo ln -s /usr/local/percona/pmm/bin/pmm-agent /usr/local/bin/pmm-agent
sudo ln -s /usr/local/percona/pmm/bin/pmm-admin /usr/local/bin/pmm-adminRegister with PMM Server
Run the agent setup to register with PMM Server:
sudo pmm-agent setup --config-file=/usr/local/percona/pmm/config/pmm-agent.yaml \
--server-address=172.31.11.183:443 \
--server-insecure-tls \
--server-username=admin \
--server-password='Testing123#'Expected: "Registered. Configuration file /usr/local/percona/pmm/config/pmm-agent.yaml updated."
Start the pmm-agent in the background:
sudo pmm-agent --config-file=/usr/local/percona/pmm/config/pmm-agent.yaml &
Production Tip: For production, create a systemd service file for pmm-agent so it starts automatically on boot. See the Troubleshooting section for an example.
Add PostgreSQL Service
Ensure the PostgreSQL monitoring user exists with the correct password:
sudo -u postgres psql -c "ALTER USER pmm_user WITH PASSWORD 'Badminton23@';"
Verify password authentication works via TCP:
PGPASSWORD='Badminton23@' psql -h 127.0.0.1 -U pmm_user -d postgres -c "SELECT 1;"
Add the PostgreSQL service to PMM:
pmm-admin add postgresql \
--username=pmm_user \
--password='Badminton23@' \
--service-name=postgres-server \
--host=127.0.0.1 \
--port=5432 \
--query-source=pgstatstatementsExpected output:
PostgreSQL Service added.
Service ID : f00995c3-aec6-41d0-9c0d-b50f7f27dfa0
Service name: postgres-serverAfter adding the service, the agent automatically starts postgres_exporter (port 42002) and reconfigures vmagent to scrape it.
PMM Client on MySQL Server ( MYSQL Instance )
Install PMM Client (Binary Tarball)
Download, extract, and install (same steps as PostgreSQL):
wget https://downloads.percona.com/downloads/pmm3/3.8.0/binary/tarball/pmm-client-3.8.0-x86_64.tar.gz
tar xfz pmm-client-3.8.0-x86_64.tar.gz && cd pmm-client-3.8.0
export PMM_DIR=/usr/local/percona/pmm
sudo ./install_tarball
sudo ln -s /usr/local/percona/pmm/bin/pmm-agent /usr/local/bin/pmm-agent
sudo ln -s /usr/local/percona/pmm/bin/pmm-admin /usr/local/bin/pmm-adminRegister with PMM Server
Register the agent:
sudo pmm-agent setup --config-file=/usr/local/percona/pmm/config/pmm-agent.yaml \
--server-address=172.31.11.183:443 \
--server-insecure-tls \
--server-username=admin \
--server-password='Testing123#'Start the agent:
sudo pmm-agent --config-file=/usr/local/percona/pmm/config/pmm-agent.yaml &
Add MySQL Service
Add the MySQL service with performance_schema as query source:
pmm-admin add mysql \
--username=pmm \
--password='Badminton23@' \
--service-name=mysql-server \
--host=127.0.0.1 \
--port=3306 \
--query-source=perfschemaExpected output:
MySQL Service added.
Service ID : ada91424-6168-4063-9a1b-33c5f9414a81
Service name: mysql-server
Table statistics collection enabled (the limit is 1000, the actual table count is 337).After adding the service:
- mysqld_exporter starts on port 42002 (AGENT_STATUS_RUNNING)
- qan_mysql_perfschema_agent starts collecting query analytics
- vmagent is restarted to include the new scrape target (7 total targets)
Verification & Dashboard Access
Check Agent Status
On any client node, verify the agent is properly connected:
pmm-admin status
Access PMM Web UI
Open your browser and navigate to:
https://<PMM_SERVER_PUBLIC_IP>:443Login credentials: admin / Testing123#
Key Dashboards to Check
Verify Metrics Collection
After 2-3 minutes, you should see:
- 3 nodes in the inventory (PMM internal + PostgreSQL host + MySQL host)
- Node metrics (CPU, memory) appearing on Node dashboards
- PostgreSQL metrics on PostgreSQL Instance Summary
- MySQL metrics on MySQL Instance Summary
- Query data in QAN (Query Analytics)
Database Flavors Supported (Open Source Edition)
The following screenshots provide a visual overview of the PMM dashboards and monitoring capabilities. They demonstrate how PMM delivers real-time insights into database performance, system health, query analytics, replication status, and infrastructure metrics through a unified interface.
Final Thoughts
PMM 3 is one of the most underrated tools in the DBA toolbox. It's free, it's open-source, and it gives you production-grade observability without writing a single line of monitoring code.
What makes it stand out:
- Zero application-side instrumentation — just point it at your database
- Query Analytics (QAN) that actually tells you which queries are hurting performance
- Pre-built dashboards that a DBA can use on day one
- Single port (443) outbound — no complex firewall rules
- Works across MySQL, PostgreSQL, and MongoDB in one unified view
If you're running databases in production without something like PMM, you're flying blind. Set it up once, and you'll wonder how you ever managed without it.
Have questions or ran into issues? Drop a comment below — happy to help troubleshoot.
Comments
Post a Comment