Percona Monitoring and Management (PMM) es una plataforma de monitorización de código abierto específica para bases de datos. Además de métricas del sistema, muestra el detalle interno de MySQL, PostgreSQL y MongoDB y, sobre todo, incluye Query Analytics (QAN), que agrupa las consultas y te dice cuáles consumen más tiempo. En esta guía desplegarás PMM Server 3 con Docker en Ubuntu 24.04, instalarás el cliente en los servidores de bases de datos y registrarás una instancia de MySQL y otra de PostgreSQL.

Requisitos previos

  • Un servidor para PMM Server con Ubuntu 24.04 LTS, al menos 2 vCPU, 4 GB de RAM y 100 GB de disco, por ejemplo un VPS de CubePath. El disco necesario crece con el número de instancias y el periodo de retención.
  • Docker Engine instalado en ese servidor desde el repositorio oficial de Docker.
  • Uno o más servidores de bases de datos con Ubuntu 24.04 y MySQL 8.0 o PostgreSQL 16, con un usuario no root con privilegios sudo.
  • Conectividad desde los servidores de bases de datos al puerto 443 del servidor PMM.

Arquitectura de PMM

PMM tiene dos piezas:

  • PMM Server: un contenedor con la interfaz web (basada en Grafana), la base de datos de métricas y la de consultas. Se instala una vez.
  • PMM Client: el paquete pmm-client, que se instala en cada servidor de bases de datos. Incluye pmm-agent, que recoge métricas y consultas y las envía al servidor, y la herramienta pmm-admin para configurarlo.

Paso 1: Desplegar PMM Server

Crea un volumen para que los datos sobrevivan a las actualizaciones del contenedor:

docker volume create pmm-data

Arranca PMM Server 3. En esta versión el contenedor escucha en el puerto 8443 internamente, así que se publica en el 443 del host:

docker run -d \
  --name pmm-server \
  --restart always \
  -p 443:8443 \
  -v pmm-data:/srv \
  percona/pmm-server:3

El primer arranque tarda uno o dos minutos. Comprueba que el contenedor está sano:

docker ps --filter name=pmm-server --format '{{.Names}}: {{.Status}}'

pmm-server: Up 2 minutes (healthy)

Paso 2: Cambiar la contraseña de administrador

El usuario inicial es admin con contraseña admin. Cámbiala antes de nada, sustituyendo your_strong_password:

docker exec -t pmm-server change-admin-password your_strong_password

Abre https://your_server_ip en el navegador. PMM usa un certificado autofirmado, así que el navegador mostrará un aviso que puedes aceptar. Inicia sesión con admin y la nueva contraseña; verás el dashboard Home con el propio servidor PMM ya monitorizado.

Paso 3: Crear un token para registrar clientes

En PMM 3 los clientes se registran con el token de una cuenta de servicio, en lugar de con la contraseña de administrador. En la interfaz web ve a Administration > Users and access > Service accounts, crea una cuenta de servicio llamada pmm-clients con rol Admin y pulsa Add service account token. Copia el token generado; lo usarás como your_service_token.

Paso 4: Instalar PMM Client en el servidor de bases de datos

En cada servidor de bases de datos, instala el paquete que configura los repositorios de Percona:

sudo apt update
sudo apt install -y curl gnupg2 lsb-release
curl -fsSLO https://repo.percona.com/apt/percona-release_latest.generic_all.deb
sudo apt install -y ./percona-release_latest.generic_all.deb

Activa el repositorio de PMM 3 e instala el cliente:

sudo percona-release enable pmm3-client
sudo apt update
sudo apt install -y pmm-client

Comprueba la versión:

pmm-admin --version

La versión mayor del cliente debe ser 3, igual que la del servidor.

Paso 5: Registrar el cliente en PMM Server

Registra el nodo contra el servidor. --server-insecure-tls es necesario mientras PMM use el certificado autofirmado:

sudo pmm-admin config \
  --server-insecure-tls \
  --server-url=https://service_token:your_service_token@your_server_ip:443

Checking local pmm-agent status...
pmm-agent is running.
Registering pmm-agent on PMM Server...
Registered.
Configuration file /usr/local/percona/pmm/config/pmm-agent.yaml updated.
Reloading pmm-agent configuration...
Configuration reloaded.

Verifica que el agente está conectado:

sudo pmm-admin status

La salida debe mostrar Connected : true en la sección de PMM Server y el agente node_exporter en estado Running. A partir de aquí ya ves las métricas del sistema del nodo en el dashboard Node Overview.

Paso 6: Monitorizar MySQL

Crea en MySQL un usuario para PMM con los permisos que necesita para leer métricas y el Performance Schema. Entra en la consola:

sudo mysql

Ejecuta estas sentencias, sustituyendo your_pmm_password:

CREATE USER 'pmm'@'localhost' IDENTIFIED BY 'your_pmm_password' WITH MAX_USER_CONNECTIONS 10;
GRANT SELECT, PROCESS, REPLICATION CLIENT, RELOAD, BACKUP_ADMIN ON *.* TO 'pmm'@'localhost';
EXIT;

Como fuente de consultas se usa el Performance Schema, que MySQL 8.0 tiene activado por defecto y no requiere escribir un slow log en disco. Compruébalo:

sudo mysql -e "SHOW VARIABLES LIKE 'performance_schema';"

+--------------------+-------+
| Variable_name      | Value |
+--------------------+-------+
| performance_schema | ON    |
+--------------------+-------+

Añade la instancia a PMM:

sudo pmm-admin add mysql \
  --username=pmm \
  --password=your_pmm_password \
  --host=127.0.0.1 \
  --port=3306 \
  --query-source=perfschema \
  --service-name=mysql-prod-01

MySQL Service added.
Service ID  : ...
Service name: mysql-prod-01

Paso 7: Monitorizar PostgreSQL

Query Analytics para PostgreSQL necesita la extensión pg_stat_statements, que se carga al arrancar el servidor. Actívala y habilita también la medición de tiempos de E/S:

sudo -u postgres psql -c "ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements';"
sudo -u postgres psql -c "ALTER SYSTEM SET track_io_timing = on;"
sudo systemctl restart postgresql

Crea la extensión en la base de datos postgres, que es a la que se conecta PMM, y un usuario con el rol predefinido pg_monitor:

sudo -u postgres psql -c "CREATE EXTENSION IF NOT EXISTS pg_stat_statements;"
sudo -u postgres psql -c "CREATE USER pmm WITH PASSWORD 'your_pmm_password';"
sudo -u postgres psql -c "GRANT pg_monitor TO pmm;"

Comprueba que el usuario puede conectarse por TCP, que es como lo hará PMM:

psql "host=127.0.0.1 dbname=postgres user=pmm" -c "SELECT count(*) FROM pg_stat_statements;"

Añade la instancia a PMM:

sudo pmm-admin add postgresql \
  --username=pmm \
  --password=your_pmm_password \
  --host=127.0.0.1 \
  --port=5432 \
  --query-source=pgstatements \
  --service-name=postgresql-prod-01

Lista los servicios registrados en el nodo:

sudo pmm-admin list

Cada servicio debe aparecer con sus agentes (mysqld_exporter o postgres_exporter y el agente de QAN correspondiente) en estado Running.

Paso 8: Analizar consultas con Query Analytics

Tras unos minutos de actividad, abre en la interfaz web el apartado Query Analytics en el menú lateral. Verás una tabla con las consultas normalizadas (con los valores sustituidos por ?) ordenadas por la carga que generan.

Para encontrar las consultas que más conviene optimizar:

  1. Filtra por servicio, por ejemplo mysql-prod-01, en el panel de filtros.
  2. Ordena por Load o Query Time. Una consulta que tarda poco pero se ejecuta miles de veces por segundo puede pesar más que una lenta y ocasional.
  3. Pulsa una consulta para ver su detalle: ejemplos reales, tiempo medio y percentiles, filas examinadas frente a filas devueltas y, en la pestaña Explain, su plan de ejecución.

Una consulta que examina muchas más filas de las que devuelve suele indicar un índice que falta. Crea el índice, espera unos minutos y compara la misma consulta en QAN.

Los dashboards más útiles para empezar, accesibles desde el menú lateral, son MySQL Instance Summary, PostgreSQL Instance Summary y Node Overview.

Paso 9: Actualizar PMM Server

Como los datos están en el volumen pmm-data, actualizar consiste en descargar la nueva imagen y recrear el contenedor con los mismos parámetros:

docker pull percona/pmm-server:3
docker stop pmm-server
docker rm pmm-server
docker run -d --name pmm-server --restart always -p 443:8443 -v pmm-data:/srv percona/pmm-server:3

Actualiza también los clientes con sudo apt update && sudo apt install --only-upgrade pmm-client.

Solución de problemas

pmm-admin config falla con errores de conexión. Comprueba que el servidor responde desde el cliente:

curl -k -o /dev/null -w "%{http_code}\n" https://your_server_ip/

Si no devuelve un código HTTP, revisa firewalls entre ambos servidores. Si responde pero el registro falla con un error de autenticación, el token no es válido o la cuenta de servicio no tiene rol Admin.

Un servicio aparece como Waiting o sin datos. Revisa los logs del agente en el servidor de bases de datos:

sudo journalctl -u pmm-agent -n 50 --no-pager

Los errores habituales son una contraseña incorrecta del usuario pmm o falta de permisos en la base de datos.

Query Analytics de PostgreSQL está vacío. Confirma que la extensión existe en la base de datos postgres y que la biblioteca está cargada:

sudo -u postgres psql -c "SHOW shared_preload_libraries;"
sudo -u postgres psql -c "\dx pg_stat_statements"

Conclusión

Has desplegado PMM Server 3 con Docker, registrado un nodo con pmm-client mediante un token de cuenta de servicio y añadido instancias de MySQL y PostgreSQL con Query Analytics. Como siguientes pasos, sustituye el certificado autofirmado por uno válido, ajusta la retención de datos en PMM Configuration > Settings según el disco disponible y configura reglas de alerta con las plantillas incluidas en el apartado Alerting.