PMM Admin CLI
Relevant source files
The following files were used as context for generating this wiki page:
The PMM Admin CLI (pmm-admin) is a command-line administration tool for Percona Monitoring and Management (PMM). Its primary purpose is to manage the services and database instances that should be monitored by PMM by communicating with the PMM Server's managed services. It acts as a bridge between the user's infrastructure and the PMM ecosystem, allowing for the registration of nodes, addition of database services, and diagnostics of the monitoring agent's status.
Sources: CONTRIBUTING.md:42, admin/README.md:1-5
Architecture and Command Structure
The CLI is structured around a set of commands that interact with the PMM Client (pmm-agent) and the PMM Server. It utilizes a common interface for all commands, ensuring consistent behavior across different administrative tasks. Commands are designed to return a structured Result object on success or an Error on failure, facilitating programmatic use and clear feedback.
Command Execution Flow
The following diagram illustrates how a command is processed within the CLI:
The CLI defines a standard execution pattern where RunCmd (or RunWithContext) handles the logic and returns a Result interface.
Sources: admin/commands/base.go:49-74, admin/README.md:15-30
Core Command Interfaces
| Interface | Description |
|---|---|
Command | Common interface requiring RunCmd() method; should not exit with Fatal/Exit codes. |
CommandWithContext | Modern interface requiring RunWithContext(ctx) for asynchronous operations. |
Result | Common interface for command outputs, compatible with json.Marshal and fmt.Stringer. |
Sources: admin/commands/base.go:49-74
Functional Capabilities
The CLI provides a wide range of administrative capabilities, categorized into service management, inventory management, and diagnostic tools.
Database Service Management
pmm-admin is used to add various database types to the monitoring system. This includes:
- MySQL: Adding instances with credentials and custom labels.
- PostgreSQL: Connecting PostgreSQL nodes for metric and query tracking.
- MongoDB: Registering MongoDB clusters or standalone instances.
Sources: managed/CONTRIBUTING.md:104-110, documentation/mkdocs-base.yml:236-241
Diagnostic and Status Tools
The status and summary commands are critical for troubleshooting. The status command provides real-time information about the connection between the local pmm-agent and the PMM Server, as well as the health of individual exporters.
The diagnostic output includes Agent IDs, Node IDs, Time Drift, and Latency measurements.
Sources: admin/README.md:15-30, managed/services/server/logs.go:284-300
Configuration and Credentials
The CLI supports advanced configuration through flags and external credential sources. This allows it to integrate with automation tools like Ansible or HashiCorp Vault.
External Credential Loading
The CLI can read credentials from JSON files, which is useful for avoiding plain-text passwords in command history. The Credentials struct handles:
UsernamePasswordAgentPassword
Sources: admin/commands/base.go:81-85
Key Global Flags and Helpers
The CLI uses several utility functions to process input before execution:
ParseKeyValuePair: Processes flags like--custom-labelsinto a map.ParseDisableCollectors: Handles the--disable-collectorsflag to prune metrics gathering.ValidateEnvironmentVariableNames: Ensures environment variables passed to the CLI meet standard naming conventions.
Sources: admin/commands/base.go:138-190
System Integration
pmm-admin interacts closely with other PMM components. It is often used within the PMM Server container itself to generate system summaries.
Logs and Summaries
The PMM Server's logging service invokes pmm-admin summary to gather a comprehensive diagnostic package. This package includes:
- Client-side logs (when
--skip-serveris not used). - Exporter status.
- System information.
Sources: managed/services/server/logs.go:284-335
Installation and Environment
In a typical development or production environment, the CLI is installed via make install or package managers. It requires a running pmm-agent to perform most actions that involve local exporters.
Sources: admin/README.md:8-13, CONTRIBUTING.md:42
Summary
The PMM Admin CLI serves as the primary interface for infrastructure administrators to interact with the PMM ecosystem. By providing a structured command set for service registration, credential management, and deep diagnostic reporting, it ensures that database monitoring can be configured efficiently and maintained effectively across complex hybrid environments.
Sources: admin/README.md, CONTRIBUTING.md