Skip to content

docs: Complete pmm-agent environment variables documentation #4543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: v3
Choose a base branch
from
Draft

docs: Complete pmm-agent environment variables documentation #4543

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
691f51c
Initial plan
Copilot Sep 19, 2025
b9b19f4
Update pmm-agent documentation with comprehensive environment variabl…
Copilot Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 83 additions & 38 deletions documentation/docs/use/commands/pmm-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,44 +27,89 @@

Most options can be set via environment variables (shown in parentheses).

| Option | Environment variable | Description
| -------------------------------------- | ----------------------------------- | -----------------------------
| `--server-password=SERVER-PASSWORD` | `PMM_AGENT_SERVER_PASSWORD` | Password to connect to PMM Server.
| `--server-username=SERVER-USERNAME` | `PMM_AGENT_SERVER_USERNAME` | Username to connect to PMM Server.
| `--server-address=host:port` | `PMM_AGENT_SERVER_ADDRESS` | PMM Server address and port number.
| `--server-insecure-tls` | `PMM_AGENT_SERVER_INSECURE_TLS` | Skip PMM Server TLS certificate validation.
| `--az=AZ` | `PMM_AGENT_SETUP_AZ` | Node availability zone.
| `--config-file=path_to/pmm-agent.yaml` | `PMM_AGENT_CONFIG_FILE` | Configuration file path and name.
| `--container-id=CONTAINER-ID` | `PMM_AGENT_SETUP_CONTAINER_ID` | Container ID.
| `--container-name=CONTAINER-NAME` | `PMM_AGENT_SETUP_CONTAINER_NAME` | Container name.
| `--debug` | `PMM_AGENT_DEBUG` | Enable debug output.
| `--distro=distro` | `PMM_AGENT_SETUP_DISTRO` | Node OS distribution (default is auto-detected).
| `--force` | `PMM_AGENT_SETUP_FORCE` | Remove Node with that name and all dependent Services and Agents (if existing).
| `--id=...` | `PMM_AGENT_ID` | ID of this pmm-agent.
| `--listen-address=LISTEN-ADDRESS` | `PMM_AGENT_LISTEN_ADDRESS` | Agent local API address.
| `--listen-port=LISTEN-PORT` | `PMM_AGENT_LISTEN_PORT` | Agent local API port.
| `--machine-id=machine-id` | `PMM_AGENT_SETUP_MACHINE_ID` | Node machine ID (default is auto-detected).
| `--metrics-mode=auto` | `PMM_AGENT_SETUP_METRICS_MODE` | Metrics flow mode for agents node-exporter. Can be `push` (agent will push metrics), `pull` (server scrapes metrics from agent) or `auto` (chosen by server).
| `--node-model=NODE-MODEL` | `PMM_AGENT_SETUP_NODE_MODEL` | Node model.
| `--paths-base=PATH` | `PMM_AGENT_PATHS_BASE` | Base path for PMM client, where all binaries, tools and collectors are located. If not set, default is `/usr/local/percona/pmm`.
| `--paths-exporters_base=PATH` | `PMM_AGENT_PATHS_EXPORTERS_BASE` | Base path for exporters to use. If not set, or set to a relative path, uses value of `--paths-base` prepended to it.
| `--paths-mongodb_exporter=PATH` | `PMM_AGENT_PATHS_MONGODB_EXPORTER` | Path to `mongodb_exporter`.
| `--paths-mysqld_exporter=PATH` | `PMM_AGENT_PATHS_MYSQLD_EXPORTER` | Path to `mysqld_exporter`.
| `--paths-node_exporter=PATH` | `PMM_AGENT_PATHS_NODE_EXPORTER` | Path to `node_exporter`.
| `--paths-postgres_exporter=PATH` | `PMM_AGENT_PATHS_POSTGRES_EXPORTER` | Path to `postgres_exporter`.
| `--paths-proxysql_exporter=PATH` | `PMM_AGENT_PATHS_PROXYSQL_EXPORTER` | Path to `proxysql_exporter`.
| `--paths-pt-summary=PATH` | `PMM_AGENT_PATHS_PT_SUMMARY` | Path to `pt-summary`.
| `--paths-pt-mysql-summary=PATH` | `PMM_AGENT_PATHS_PT_MYSQL_SUMMARY` | Path to `pt-mysql-summary`.
| `--paths-pt-pg-summary=PATH` | `PMM_AGENT_PATHS_PT_PG_SUMMARY` | Path to `pt-pg-summary`.
| `--paths-tempdir=PATH` | `PMM_AGENT_PATHS_TEMPDIR` | Temporary directory for exporters.
| `--ports-max=PORTS-MAX` | `PMM_AGENT_PORTS_MAX` | Highest allowed port number for listening sockets.
| `--ports-min=PORTS-MIN` | `PMM_AGENT_PORTS_MIN` | Lowest allowed port number for listening sockets.
| `--region=REGION` | `PMM_AGENT_SETUP_REGION` | Node region.
| `--skip-registration` | `PMM_AGENT_SETUP_SKIP_REGISTRATION` | Skip registration on PMM Server.
| `--trace` | `PMM_AGENT_TRACE` | Enable trace output (implies `--debug`).
| `-h`, `--help` | | Show help (synonym for `pmm-agent help`).
| `--version` | | Show application version, PMM version, time-stamp, git commit hash and branch.
| `--expose-exporter` | | If you enable this flag, any IP address on the local network and anywhere on the internet can access node exporter endpoints. If the flag is disabled, node exporter endpoints can be accessed only locally.
| Option | Environment variable | Description |
| ------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------- |
| `--agent-password=AGENT-PASSWORD` | `PMM_AGENT_SETUP_NODE_PASSWORD` | Custom password for /metrics endpoint. |
| `--az=AZ` | `PMM_AGENT_SETUP_AZ` | Node availability zone. |
| `--config-file=path_to/pmm-agent.yaml` | `PMM_AGENT_CONFIG_FILE` | Configuration file path and name. |
| `--container-id=CONTAINER-ID` | `PMM_AGENT_SETUP_CONTAINER_ID` | Container ID. |
| `--container-name=CONTAINER-NAME` | `PMM_AGENT_SETUP_CONTAINER_NAME` | Container name. |
| `--custom-labels=CUSTOM-LABELS` | `PMM_AGENT_SETUP_CUSTOM_LABELS` | Custom labels for the node. |
| `--debug` | `PMM_AGENT_DEBUG` | Enable debug output. |
| `--disable-collectors=COLLECTOR1,COLLECTOR2` | `PMM_AGENT_SETUP_DISABLE_COLLECTORS` | Comma-separated list of collector names to exclude from exporter. |
| `--distro=distro` | `PMM_AGENT_SETUP_DISTRO` | Node OS distribution (default is auto-detected). |
| `--expose-exporter` | `PMM_AGENT_EXPOSE_EXPORTER` | Expose the address of the agent's node-exporter publicly on 0.0.0.0. |
| `--force` | `PMM_AGENT_SETUP_FORCE` | Remove Node with that name and all dependent Services and Agents (if existing). |
| `--id=ID` | `PMM_AGENT_ID` | ID of this pmm-agent. |
| `--listen-address=LISTEN-ADDRESS` | `PMM_AGENT_LISTEN_ADDRESS` | Agent local API address. |
| `--listen-port=LISTEN-PORT` | `PMM_AGENT_LISTEN_PORT` | Agent local API port. |
| `--log-level=LEVEL` | `PMM_AGENT_LOG_LEVEL` | Set logging level (debug, info, warn, error, fatal). |
| `--log-lines-count=COUNT` | `PMM_AGENT_LOG_LINES_COUNT` | Number of most recent log lines to include in logs.zip for each component. |
| `--machine-id=machine-id` | `PMM_AGENT_SETUP_MACHINE_ID` | Node machine ID (default is auto-detected). |
| `--metrics-mode=auto` | `PMM_AGENT_SETUP_METRICS_MODE` | Metrics flow mode for agents node-exporter. Can be `push` (agent will push metrics), `pull` (server scrapes metrics from agent) or `auto` (chosen by server). |
| `--node-model=NODE-MODEL` | `PMM_AGENT_SETUP_NODE_MODEL` | Node model. |
| `--paths-azure_exporter=PATH` | `PMM_AGENT_PATHS_AZURE_EXPORTER` | Path to `azure_exporter`. |
| `--paths-base=PATH` | `PMM_AGENT_PATHS_BASE` | Base path for PMM client, where all binaries, tools and collectors are located. If not set, default is `/usr/local/percona/pmm`. |
| `--paths-exporters_base=PATH` | `PMM_AGENT_PATHS_EXPORTERS_BASE` | Base path for exporters to use. If not set, or set to a relative path, uses value of `--paths-base` prepended to it. |
| `--paths-mongodb_exporter=PATH` | `PMM_AGENT_PATHS_MONGODB_EXPORTER` | Path to `mongodb_exporter`. |
| `--paths-mysqld_exporter=PATH` | `PMM_AGENT_PATHS_MYSQLD_EXPORTER` | Path to `mysqld_exporter`. |
| `--paths-node_exporter=PATH` | `PMM_AGENT_PATHS_NODE_EXPORTER` | Path to `node_exporter`. |
| `--paths-nomad=PATH` | `PMM_AGENT_PATHS_NOMAD` | Path to `nomad` binary. |
| `--paths-nomad-data-dir=PATH` | `PMM_AGENT_PATHS_NOMAD_DATA_DIR` | Nomad data directory. |
| `--paths-postgres_exporter=PATH` | `PMM_AGENT_PATHS_POSTGRES_EXPORTER` | Path to `postgres_exporter`. |
| `--paths-proxysql_exporter=PATH` | `PMM_AGENT_PATHS_PROXYSQL_EXPORTER` | Path to `proxysql_exporter`. |
| `--paths-pt-mongodb-summary=PATH` | `PMM_AGENT_PATHS_PT_MONGODB_SUMMARY` | Path to `pt-mongodb-summary`. |
| `--paths-pt-mysql-summary=PATH` | `PMM_AGENT_PATHS_PT_MYSQL_SUMMARY` | Path to `pt-mysql-summary`. |
| `--paths-pt-pg-summary=PATH` | `PMM_AGENT_PATHS_PT_PG_SUMMARY` | Path to `pt-pg-summary`. |
| `--paths-pt-summary=PATH` | `PMM_AGENT_PATHS_PT_SUMMARY` | Path to `pt-summary`. |
| `--paths-tempdir=PATH` | `PMM_AGENT_PATHS_TEMPDIR` | Temporary directory for exporters. |
| `--paths-valkey-exporter=PATH` | `PMM_AGENT_PATHS_VALKEY_EXPORTER` | Path to `valkey_exporter`. |
| `--perfschema-refresh-rate=RATE` | `PMM_AGENT_PERFSCHEMA_REFRESH_RATE` | How often PMM scrapes data from Performance Schema (in seconds). |
| `--ports-max=PORTS-MAX` | `PMM_AGENT_PORTS_MAX` | Highest allowed port number for listening sockets. |
| `--ports-min=PORTS-MIN` | `PMM_AGENT_PORTS_MIN` | Lowest allowed port number for listening sockets. |
| `--region=REGION` | `PMM_AGENT_SETUP_REGION` | Node region. |
| `--runner-capacity=CAPACITY` | `PMM_AGENT_RUNNER_CAPACITY` | Agent internal actions/jobs runner capacity. |
| `--runner-max-connections-per-service=COUNT` | `PMM_AGENT_RUNNER_MAX_CONNECTIONS_PER_SERVICE` | Agent internal action/job runner connection limit per DB instance. |
| `--server-address=host:port` | `PMM_AGENT_SERVER_ADDRESS` | PMM Server address and port number. |
| `--server-insecure-tls` | `PMM_AGENT_SERVER_INSECURE_TLS` | Skip PMM Server TLS certificate validation. |
| `--server-password=SERVER-PASSWORD` | `PMM_AGENT_SERVER_PASSWORD` | Password to connect to PMM Server. |
| `--server-username=SERVER-USERNAME` | `PMM_AGENT_SERVER_USERNAME` | Username to connect to PMM Server. |
| `--skip-registration` | `PMM_AGENT_SETUP_SKIP_REGISTRATION` | Skip registration on PMM Server. |
| `--trace` | `PMM_AGENT_TRACE` | Enable trace output (implies `--debug`). |
| `--window-connected-time=DURATION` | `PMM_AGENT_WINDOW_CONNECTED_TIME` | Window time for tracking the status of connection between agent and server. |
| `-h`, `--help` | | Show help (synonym for `pmm-agent help`). |
| `--version` | | Show application version, PMM version, time-stamp, git commit hash and branch. |

## Setup command arguments

The following arguments are available for the `pmm-agent setup` command:

| Argument | Environment variable | Description |
| ------------------------------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------- |
| `node-address` | `PMM_AGENT_SETUP_NODE_ADDRESS` | Node address (required if not auto-detected). |
| `node-type` | `PMM_AGENT_SETUP_NODE_TYPE` | Node type: `generic` or `container` (default: `generic`). |
| `node-name` | `PMM_AGENT_SETUP_NODE_NAME` | Node name (default: hostname). |

## Docker entrypoint variables

The following environment variables are recognized specifically by the PMM Client Docker container entrypoint:

| Environment variable | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `PMM_AGENT_SETUP` | If `true`, `pmm-agent setup` is called before `pmm-agent run`. |
| `PMM_AGENT_PRERUN_FILE` | If non-empty, runs the specified file with `pmm-agent run` running in the background. |
| `PMM_AGENT_PRERUN_SCRIPT` | If non-empty, runs the specified shell script content with `pmm-agent run` running in the background. |
| `PMM_AGENT_SIDECAR` | If `true`, `pmm-agent` will be restarted if it fails. |
| `PMM_AGENT_SIDECAR_SLEEP` | Time (in seconds) to wait before restarting pmm-agent if `PMM_AGENT_SIDECAR` is `true`. Default is 1 second. |

## Cross-component variables

The following environment variables affect multiple PMM components:

| Environment variable | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `PMM_DEBUG` | Enable debug logging across all PMM components (overrides `PMM_AGENT_DEBUG`). |
| `PMM_TRACE` | Enable trace logging across all PMM components (overrides `PMM_AGENT_TRACE`). |

## CONFIG FILE

Expand Down
Loading