CLI Reference

Relevant source files

The following files were used as context for generating this wiki page:

• cmd/pmm-dump/main.go
• cmd/pmm-dump/util.go
• README.md
• pkg/victoriametrics/source.go
• pkg/clickhouse/source.go
• pkg/util/util.go

The pmm-dump CLI tool provides a command-line interface for exporting and importing metrics and Query Analytics (QAN) data between Percona Monitoring and Management (PMM) Server instances. It facilitates troubleshooting by allowing Percona engineers to extract specific time-series and query data into a portable compressed format.

The tool is built using the kingpin library and supports global configuration via flags or environment variables, alongside specific commands for data transfer and metadata inspection. Data flow typically involves connecting to VictoriaMetrics for core metrics and ClickHouse for QAN data.

Sources: README.md:1-5, cmd/pmm-dump/main.go:50-130

Command Structure and Data Flow

The CLI follows a standard command-pattern architecture where global options configure the connection to PMM components, and subcommands define the specific action (Export, Import, Show-Meta, or Version).

Execution Flow

The following diagram illustrates the high-level logic when executing an export or import command:

Global Options

Global options can be provided as flags or environment variables. These parameters establish the connection strings and authentication for the PMM Server and its underlying databases.

Flag	Envar	Description
--pmm-url	PMM_URL	Full PMM connection string (e.g., http://admin:admin@host).
--pmm-host	PMM_HOST	PMM server host with scheme.
--pmm-user	PMM_USER	PMM credentials username.
--pmm-pass	PMM_PASS	PMM credentials password.
--pmm-token	PMM_TOKEN	PMM API token for authentication.
--dump-core	-	Export/Import core metrics (VictoriaMetrics). Default: true.
--dump-qan	-	Export/Import QAN metrics (ClickHouse).
--workers	-	Number of reading/writing workers.
--verbose, -v	-	Enable debug logging including goroutine IDs.

Sources: cmd/pmm-dump/main.go:53-78, README.md:32-55

Subcommands

export

Exports PMM Server metrics to a dump file. By default, it exports the last 4 hours of data.

Key Flags:

• --start-ts: Start date-time in RFC3339 format.
• --end-ts: End date-time in RFC3339 format.
• --instance: Service name filter. Can be used multiple times.
• --dashboard: Dashboard name to derive selectors from VictoriaMetrics.
• --ts-selector: Custom VictoriaMetrics series selector.
• --where: Custom ClickHouse WHERE statement.
• --stdout: Redirects the archive output to STDOUT for piping.
• --ignore-load: Disables checking for CPU/RAM thresholds on the PMM server.

Sources: cmd/pmm-dump/main.go:85-112, README.md:88-100

import

Imports PMM Server metrics from a dump file created by the export command.

Key Flags:

• --dump-path, -d: Path to the .tar.gz dump file.
• --vm-content-limit: Limits the chunk size in bytes when importing to VictoriaMetrics (JSON format only).

Sources: cmd/pmm-dump/main.go:119-122, README.md:52-53

show-meta

Displays metadata stored within a dump file, such as the PMM version, build information, and monitoring services.

Key Flags:

• --prettify: Human-readable output. Default: true.

Sources: cmd/pmm-dump/main.go:125-127, cmd/pmm-dump/main.go:331-360

Resource Load Protection

The export command implements a LoadChecker to prevent overloading the PMM server during data extraction. It compares current metrics against defined thresholds.

Threshold	Description	Default Max	Default Critical
CPU	PMM instance CPU load (0-100%)	70%	90%
RAM	PMM instance RAM load (0-100%)	80%	90%
MYRAM	pmm-dump process RAM load	10%	30%

Sources: cmd/pmm-dump/main.go:107-110, README.md:133-136

Data Sources and Formats

The tool interacts with three primary data sources:

1. VictoriaMetrics: Stores core time-series metrics. Supports JSON and native formats. The native format is smaller but may be incompatible between major PMM versions.
   • Path in dump: vm/
   • Source Code: pkg/victoriametrics/source.go
2. ClickHouse: Stores QAN data. Data is exported/imported in Tab-Separated Values (TSV) format.
   • Path in dump: ch/
   • Source Code: pkg/clickhouse/source.go
3. PostgreSQL: (Optional) Used for metadata like dashboard structures.
   • Source Code: pkg/postgres/source.go (referenced in cmd/pmm-dump/main.go:217)

Sources: cmd/pmm-dump/main.go:210-220, README.md:143-147, pkg/victoriametrics/source.go:65-75, pkg/clickhouse/source.go:117-125

Version Support

The tool requires a minimum PMM Server version of 2.12.0. It performs a version check at startup using the /v1/server/version API endpoint.

Sources: cmd/pmm-dump/util.go:37, cmd/pmm-dump/util.go:275-290