Skip to content
PERCONA MONITORING AND MANAGEMENT DOCUMENTATION

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

Get free database assistance or contact our experts for personalized support.

Get help from Percona

Configure PMM Client with pmm-admin

Use these pmm-admin commands from the command line to configure PMM Client, register nodes with PMM Server, remove services from monitoring, and add event annotations.

config and register are CLI-only operations. To perform some of these tasks from the UI, go to PMM Inventory to add or remove services, or see Annotate dashboards to add event markers. For programmatic access, see the PMM API.

Commands

Use these commands to set up and maintain your PMM Client connection, control which services are monitored, and mark events on your dashboards:

pmm-admin config

Set the PMM Server URL and credentials that pmm-agent uses to communicate with the server.

Run this after installing PMM Client or when changing server connection details.

Syntax

pmm-admin config [<node-address> [<node-type> [<node-name>]]] [FLAGS]

Flags

  • --server-url=URL: PMM Server URL in https://username:password@pmm-server-host/ format

  • --server-insecure-tls: Skip PMM Server TLS certificate validation

  • --node-id=node-id: Node ID (default is auto-detected)

  • --node-model=node-model: Node model

  • --region=region: Node region

  • --az=availability-zone: Node availability zone

  • --metrics-mode=mode: Metrics flow mode for node-exporter: auto (default), push, pull

  • --paths-base=dir: Base path for PMM client binaries, tools, and collectors

  • --agent-password=password: Custom agent password

Examples

  • Configure PMM Client to connect to PMM Server:

    pmm-admin config --server-url=https://admin:[email protected]:443

  • Configure with self-signed certificate:

    pmm-admin config \
  --server-url=https://admin:[email protected]:443 \
  --server-insecure-tls

pmm-admin register

Register this node with PMM Server. Use this when setting up PMM Client for the first time or re-registering after server changes.

Syntax

pmm-admin register [<node-address> [<node-type> [<node-name>]]] [FLAGS]

Flags

  • --server-url=URL: PMM Server URL in https://username:password@pmm-server-host/ format

  • --machine-id=ID: Node machine-id (default is auto-detected)

  • --distro=NAME: Node OS distribution (default is auto-detected)

  • --container-id=ID: Container ID

  • --container-name=NAME: Container name

  • --node-model=MODEL: Node model

  • --region=REGION: Node region

  • --az=AZ: Node availability zone

  • --custom-labels=LABELS: Custom user-assigned labels in key=value,key=value format

  • --agent-password=password: Custom agent password

Examples

  • Register node with PMM Server:

    pmm-admin register \
  --server-url=https://admin:[email protected]:443

  • Register with a custom node name:

    pmm-admin register \
  db-server-01 \
  --server-url=https://admin:[email protected]:443

  • Register a container node:

    pmm-admin register \
  --server-url=https://admin:[email protected]:443 \
  --container-name=mysql-prod

  • Register with environment labels:

    pmm-admin register \
  --server-url=https://admin:[email protected]:443 \
  --custom-labels="env=production,team=backend"

pmm-admin remove

Stop monitoring a service and remove it from PMM. This removes the service and its agents from PMM Server but does not delete any collected data.

Data remains on PMM Server for the configured retention period.

Syntax

pmm-admin remove <SERVICE_TYPE> <SERVICE_NAME> [FLAGS]

Where SERVICE_TYPE is one of: mysql, postgresql, mongodb, valkey, proxysql, haproxy, external, external-serverless.

Flags

  • --service-id=ID: Remove by service ID instead of name

  • --force: Remove service with that name or ID and all dependent services and agents

Examples

  • Remove a MySQL service by name:
pmm-admin remove mysql mysql-prod
  • Remove a MongoDB service:
pmm-admin remove mongodb mongodb-prod
  • Remove a service by ID:
pmm-admin remove mysql --service-id=abc123
  • Force removal when service is unreachable:
pmm-admin remove mysql mysql-prod --force

Verify removal

After removing a service, verify it’s gone:

pmm-admin list

pmm-admin annotate

Add event annotations to PMM dashboards. Use annotations to mark deployments, maintenance windows, incidents, or other events that might affect database performance.

Annotations appear as vertical lines on Grafana dashboards, helping you correlate performance changes with events.

For more details, see Annotate dashboards.

Syntax

pmm-admin annotate <TEXT> [FLAGS]

Flags

  • --tags=TAGS: A quoted string of comma-separated tags (e.g., "tag 1,tag 2")

  • --node: Apply to current node

  • --node-name=NAME: Apply to specific node

  • --service: Apply to all services on the current node

  • --service-name=NAME: Apply to specific service

Combining flags

You can combine --node, --service, --node-name, and --service-name to annotate multiple targets at once.

If a node or service name is specified, it takes precedence over the auto-detected current node or service.

  • --node: Current node

  • --node-name=NAME: Named node

  • --service: All services on the current node

  • --service-name=NAME: Named service

  • --node --service: Current node and all its services

--node-name=NAME --service-name=NAME: Named node and named service

Examples

  • Add a deployment annotation:

    pmm-admin annotate "Deployed v2.1.0"

  • Add an annotation with tags:

    pmm-admin annotate "Database maintenance" --tags="maintenance,scheduled"

  • Add an annotation for a specific service:

    pmm-admin annotate "Schema migration completed" --service-name=mysql-prod

  • Add an annotation for a specific node:

    pmm-admin annotate "Kernel upgrade" --node-name=db-server-01

  • Add an annotation for the current node only:

    pmm-admin annotate "Memory upgrade to 64GB" --node

  • Combine tags and service:

    pmm-admin annotate "Deployed hotfix v2.1.1" \
  --tags="deployment,hotfix" \
  --service-name=mysql-prod

See also