Configure environment variables for PMM Server¶

Configure PMM Server behavior by setting environment variables when running the Docker container. This allows you to customize performance, storage, features, and other settings without modifying configuration files.

Use environment variables¶

Configure PMM Server by setting Docker container environment variables using the -e var=value syntax:

docker run \
  --detach \
  --restart always \
  --publish 443:8443 \
  --volume pmm-data:/srv \
  -e PMM_DATA_RETENTION=720h \
  -e PMM_METRICS_RESOLUTION_HR=10s \
  --name pmm-server \
  percona/pmm-server:3

Run the examples on an existing installation¶

The examples on this page create a container named pmm-server that stores its data in the pmm-data volume. If PMM Server already runs under that name, remove the existing container first so the new one can use the name:

docker stop pmm-server
docker rm pmm-server

Removing the container doesn’t delete your data. If the existing container uses the pmm-data volume, the new container reuses it, so you keep your monitoring data and your current admin password.

If the existing container uses a host directory or a different volume, replace --volume pmm-data:/srv in the examples with the --volume option of the existing container. Without that change, the new container starts with empty storage and the default admin password. If the existing container uses a --network option, add the same option to the examples.

Core configuration variables¶

Performance & storage¶

Fine-tune data retention and how often PMM collects metrics to balance monitoring detail with resource usage:

Variable	Default	Description	Example
`PMM_DATA_RETENTION`	`720h`	How long to keep metrics data, in hours. Must be a multiple of `24h`. The default is 30 days.	`2160h` for 90 days
`PMM_METRICS_RESOLUTION_HR`	`5s`	High-resolution metrics interval. `PMM_METRICS_RESOLUTION` sets the same value, so use only one of them.	`10s`
`PMM_METRICS_RESOLUTION_MR`	`10s`	Medium-resolution metrics interval	`30s`
`PMM_METRICS_RESOLUTION_LR`	`60s`	Low-resolution metrics interval	`300s`

Set PMM_DATA_RETENTION in hours, as a multiple of 24h, such as 720h for 30 days. The minimum is 24h. If you use days, such as 30d, PMM Server won’t start.

Performance impact

Higher resolution (lower values) provides more detailed metrics but increases storage requirements and system load. For high-traffic production environments, consider increasing these values.

Built-in ClickHouse configuration¶

Select the configuration profile for the built-in ClickHouse instance

Variable	Default	Description	Example
`PMM_CLICKHOUSE_CONFIG`	`default`	Use `low-memory` for PMM Server environments with less than 16 GB RAM.	`low-memory`

low-memory config

While this configuration attempts to optimize ClickHouse for low-memory environments, we highly recommend users to follow our configuration guide. For details, see ClickHouse memory issues.

Feature controls¶

Enable or disable specific PMM features:

Variable	Default	Effect when enabled
`PMM_ENABLE_UPDATES`	`true`	Allows version checks
`PMM_ENABLE_TELEMETRY`	`true`	Enables usage data collection
`PMM_ENABLE_ALERTING`	`true`	Enables Percona Alerting system
`PMM_ENABLE_BACKUP_MANAGEMENT`	`true`	Enables backup features
`PMM_ENABLE_COMPONENT_ALERTS`	`true`	Creates the built-in alert rules for PMM’s own components (VictoriaMetrics, ClickHouse, Grafana, and the Query Analytics API). Set to `false` to remove them.
`PMM_ENABLE_HA_ALERTS`	`true`	Creates the built-in alert rules for a PMM HA Cluster. Set to `false` to remove them. Has no effect on a standalone PMM Server.
`PMM_ENABLE_AZURE_DISCOVER`	`false`	Enables Azure database discovery
`PMM_ENABLE_INTERNAL_PG_QAN`	Not set (disabled)	Enables Query Analytics (QAN) for PMM Server’s internal PostgreSQL. Useful for troubleshooting or HA scenarios. Set to `1` or `true` to enable, or `0` or `false` to explicitly disable. When set to either value, neither Configuration > Settings > Advanced settings nor `pmm-admin inventory change agent` can override it. Leave it unset to control QAN for PMM Server’s internal PostgreSQL from the UI.

Debugging and troubleshooting¶

Use these variables when diagnosing issues with PMM Server:

Variable	Default	Purpose
`PMM_DEBUG`	`false`	Enables verbose logging
`PMM_TRACE`	`false`	Enables detailed trace logging

Production use

Debug and trace logging can significantly impact performance and generate large log volumes. Use only temporarily when troubleshooting issues.

Configure vmagent on PMM Client¶

Instead of configuring each client individually, set environment variables once on the PMM Server to automatically apply settings across your entire monitoring infrastructure.

This centralized approach lets you manage disk usage limits, logging levels, and resource constraints from a single location.

For instance, PMM Clients can consume up to 1GB of disk space by default, which can quickly exhaust shared volumes in containerized environments like Kubernetes. To avoid storage issues and maintain consistency, configure disk usage limits on the PMM Server that apply to all clients automatically. For most deployments, consider reducing disk usage to 50–100MB per client.

Configure `vmagent` variables¶

Control vmagent behavior on all PMM Clients by setting VMAGENT_* environment variables on PMM Server.

This gives you centralized control over resource usage, logging, and storage settings without touching individual client deployments.

Essential variables¶

These environment variables prevent the most common deployment challenges. For all available configuration options, see Victoria metrics command-line flags.

Variable	Purpose	Example	Default	Notes
`VMAGENT_remoteWrite_maxDiskUsagePerURL`	Disk space limit per client during network outages	`52428800` (50MB)	`1073741824` (1GB)	Critical for Kubernetes
`VMAGENT_remoteWrite_tmpDataPath`	Temporary data storage path	`/tmp/custom-vmagent`	`/tmp/vmagent-temp-dir`
`VMAGENT_loggerLevel`	Logging verbosity level	`DEBUG`, `WARN`, `ERROR`	`INFO`
`VMAGENT_promscrape_maxScrapeSize`	Maximum scrape size per target	`128MiB`, `32MiB`	`64MiB`	Controls memory usage
`VMAGENT_remoteWrite_basicAuth_username`	Basic auth username for external VictoriaMetrics	`admin`	Template-based	Auto-extracted from URL
`VMAGENT_remoteWrite_basicAuth_password`	Basic auth password for external VictoriaMetrics	`secret`	Template-based	Auto-extracted from URL
`VMAGENT_remoteWrite_tlsInsecureSkipVerify`	Skip TLS certificate verification	`true`, `false`	`false`	Security setting

Convert flags to environment variables¶

Vmagent uses command-line flags for configuration.

To manage these settings centrally through PMM Server, convert the flags to environment variables using this pattern:

add VMAGENT_ prefix
replace hyphens (-)with underscores (_)
replace dots (.) with underscores (_)

Examples¶

remoteWrite.maxDiskUsagePerURL > VMAGENT_remoteWrite_maxDiskUsagePerURL
loggerLevel > VMAGENT_loggerLevel
httpListenAddr > VMAGENT_httpListenAddr

Common deployment scenarios¶

Here are some examples for typical production configurations for different environments.

Set these variables on PMM Server startup to automatically configure all connected clients.

Kubernetes with shared storage¶

Optimize for disk space constraints:

docker run \
  --detach \
  --restart always \
  --publish 443:8443 \
  --volume pmm-data:/srv \
  -e VMAGENT_remoteWrite_maxDiskUsagePerURL=52428800 \
  -e VMAGENT_promscrape_maxScrapeSize=32MiB \
  -e VMAGENT_loggerLevel=WARN \
  --name pmm-server \
  percona/pmm-server:3

High-traffic environments¶

Balance resource usage with monitoring detail:

docker run \
  --detach \
  --restart always \
  --publish 443:8443 \
  --volume pmm-data:/srv \
  -e VMAGENT_remoteWrite_maxDiskUsagePerURL=104857600 \
  -e VMAGENT_promscrape_maxScrapeSize=128MiB \
  -e VMAGENT_loggerLevel=ERROR \
  --name pmm-server \
  percona/pmm-server:3

Development and debugging¶

Enable detailed logging for troubleshooting:

docker run \
  --detach \
  --restart always \
  --publish 443:8443 \
  --volume pmm-data:/srv \
  -e VMAGENT_loggerLevel=DEBUG \
  -e VMAGENT_remoteWrite_maxDiskUsagePerURL=26214400 \
  -e VMAGENT_promscrape_maxScrapeSize=64MiB \
  --name pmm-server \
  percona/pmm-server:3

Configuration changes apply to all connected PMM Clients automatically without requiring restarts.

Verify configuration¶

To confirm that centralized configuration is working, check that vmagent is running and using the expected settings:

# Check vmagent process exists
pidof vmagent

# Verify environment variables are applied
cat /proc/$(pidof vmagent)/environ | tr '\0' '\n' | grep VMAGENT

Advanced configuration¶

Network configuration¶

Control how PMM Server presents itself on the network:

Variable	Description
`PMM_PUBLIC_ADDRESS`	External DNS/IP for PMM Server. Also required for Nomad to start. Setting `PMM_ENABLE_NOMAD=1` without this variable has no effect.
`PMM_INTERFACE_TO_BIND`	Network interface binding

Database connections¶

Configure connections to external database services:

HA variables¶

These variables run PMM Server nodes as a PMM HA Cluster. The PMM HA Helm chart sets them for you. Leave them unchanged in pmmEnv, because changing them can break the cluster.

Variable	Description
`PMM_HA_ENABLE`	Runs PMM Server in HA mode
`PMM_HA_NODE_ID`	ID of this node in the cluster
`PMM_HA_ADVERTISE_ADDRESS`	Address this node advertises to the other nodes
`PMM_HA_GOSSIP_PORT`	Port for the gossip protocol. The Helm chart uses `9096`
`PMM_HA_RAFT_PORT`	Port for Raft consensus. The Helm chart uses `9097`
`PMM_HA_GRAFANA_GOSSIP_PORT`	Port for Grafana gossip. The Helm chart uses `9094`
`PMM_HA_PEERS`	The nodes in the cluster. The Helm chart generates this list from the replica count

All HA nodes must share one encryption key

Every node must use the same encryption key, or PMM stops monitoring the services whose credentials it can’t decrypt. The Helm chart manages the shared key for you. If you set up HA nodes yourself, see HA clusters: use the same key on every node.

Nomad Garbage Collection (GC) settings¶

Note

To enable Nomad, you must set both PMM_ENABLE_NOMAD=1 and PMM_PUBLIC_ADDRESS=<your-pmm-server-address>. Setting PMM_ENABLE_NOMAD=1 alone is not sufficient — without a public address, Nomad does not start. See Configure Nomad for details.

Control Nomad client-side garbage collection (GC) directly from PMM using environment variables.

These settings help you manage disk and inode usage, cleanup intervals, and allocation thresholds. Use these settings to control resource cleanup and usage, and keep your production environment stable.

Variable	Default	Description
`PMM_NOMAD_GC_INTERVAL`	`1m`	How often Nomad runs garbage collection.
`PMM_NOMAD_GC_DISK_USAGE_THRESHOLD`	`90`	Disk usage percentage that triggers garbage collection.
`PMM_NOMAD_GC_INODE_USAGE_THRESHOLD`	`90`	Inode usage percentage that triggers garbage collection.
`PMM_NOMAD_GC_MAX_ALLOCS`	`5000`	Maximum number of allocations Nomad keeps before triggering GC.
`PMM_NOMAD_GC_PARALLEL_DESTROYS`	`2`	Number of allocations Nomad destroys in parallel during GC.

For example:

  docker run \
    --detach \
    --restart always \
    --publish 443:8443 \
    --volume pmm-data:/srv \
    -e PMM_NOMAD_GC_INTERVAL=5m \
    -e PMM_NOMAD_GC_DISK_USAGE_THRESHOLD=85 \
    -e PMM_NOMAD_GC_INODE_USAGE_THRESHOLD=80 \
    -e PMM_NOMAD_GC_MAX_ALLOCS=3000 \
    -e PMM_NOMAD_GC_PARALLEL_DESTROYS=4 \
    --name pmm-server \
    percona/pmm-server:3

For parameter details, see Nomad client garbage collection documentation.

Supported external variables¶

PMM Server passes these variables to integrated components:

Grafana: All GF_* variables (e.g., GF_SECURITY_ADMIN_PASSWOR)
VictoriaMetrics: All VM_* variables (e.g., VM_retentionPeriod)
Kubernetes: All KUBERNETES_* variables
System variables: Standard variables like HOME, PATH, etc.

Preview variables¶

PMM also includes preview variables, for example to connect to an external ClickHouse instance. They’re still in development and can change. For the full list, see Preview environment variables.

For testing only

Preview variables aren’t supported in production. Use them for testing only.

Variables for migrating from PMM v2 to PMM v3¶

PMM v3 introduces several important changes to improve consistency and clarity. When migrating from PMM v2 to PMM v3, you’ll need to update your environment variables to match the new naming convention: