System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
Percona Monitoring and Management (PMM) is an open-source database monitoring solution designed to provide a "single pane of glass" for monitoring the performance of MySQL, MongoDB, PostgreSQL, Valkey, and Redis databases. It enables users to reduce complexity, optimize performance, and improve security across hybrid environments, including cloud providers and bare-metal infrastructures.
Sources: README.md:27-33, CONTRIBUTING.md:3-8
The system follows a Client-Server architecture. The PMM Server centralizes data collection, visualization, and management, while the PMM Client runs on monitored nodes to export metrics and perform local orchestration.
Sources: README.md:43-52, CONTRIBUTING.md:21-49
Component Overview
The architecture is divided into three primary functional areas: PMM Server (Backend and Frontend), PMM Client, and data storage components.
High-Level Architecture Flow
The following diagram illustrates the relationship between the PMM Client, PMM Server, and the external databases being monitored.
Sources: README.md:43-52, CONTRIBUTING.md:21-49
PMM Server Components
PMM Server is the central hub that manages configurations, stores metrics, and provides the user interface.
| Component | Description |
|---|---|
| pmm-managed | Manages server component configurations (VictoriaMetrics, Grafana) and exposes the API used by pmm-admin. |
| qan-api | API dedicated to Query Analytics data. |
| VictoriaMetrics | Time-series database used for storing performance metrics. |
| ClickHouse | Columnar database used for storing Query Analytics data and logs. |
| Grafana | The primary engine for visualization and dashboards. |
| PMM UI | Custom frontend built specifically for PMM features. |
| Sources: CONTRIBUTING.md:25-36, README.md:47-49, dev/clickhouse-config.xml:134-140 |
PMM Server Management Logic
The pmm-managed service handles internal server operations, such as log collection and system updates. For instance, the Logs service in pmm-managed is responsible for generating a diagnostic .zip archive containing logs from various components (Nginx, Prometheus, VictoriaMetrics, Supervisord).
Sources: managed/services/server/logs.go:61-125
PMM Client Components
The PMM Client is a collection of tools installed on the database host or a dedicated monitoring node.
Sources: CONTRIBUTING.md:38-55, README.md:50-52
- pmm-agent: The core process that runs on every monitored node. It manages the lifecycle of exporters and the VMAgent. Sources: CONTRIBUTING.md:40-42
- pmm-admin: A command-line tool used by administrators to add or remove services and manage the local PMM inventory. Sources: CONTRIBUTING.md:43-44, admin/commands/base.go:65-80
- Exporters: Independent applications (e.g.,
mysqld_exporter,node_exporter) that extract metrics from the system or database and expose them via HTTP. Sources: CONTRIBUTING.md:45-53 - VMAgent: Collects data from exporters and transmits it to the VictoriaMetrics instance on the PMM Server. Sources: CONTRIBUTING.md:40-42
Data Storage and APIs
ClickHouse Configuration
ClickHouse serves as a backend for high-volume data like query analytics. Its configuration involves specific ports for various protocols:
- HTTP API: Port 8123 (used by Grafana and web interfaces).
- Native Protocol (TCP): Port 9000 (used by
clickhouse-client). - Prometheus Endpoint: Port 9363 (for internal monitoring).
Sources: dev/clickhouse-config.xml:138-150, dev/clickhouse-config.xml:710-717
API Architecture
PMM APIs are defined using Protocol Buffers (.proto) and generated into Go code and Swagger specifications. The API serves as the communication layer between pmm-admin, the PMM UI, and the PMM Server backends.
Sources: api/README.md:1-20, CONTRIBUTING.md:23-24
Command Execution Framework
The admin package provides a structured way to execute commands via the Command and Result interfaces.
type Command interface {
RunCmd() (Result, error)
}
type CommandWithContext interface {
RunWithContext(ctx context.Context) (Result, error)
}
Sources: admin/commands/base.go:65-80
This framework includes helper functions for handling credentials (e.g., reading from JSON sources) and parsing configuration flags like --custom-labels or --disable-collectors.
Sources: admin/commands/base.go:87-124, admin/commands/base.go:167-195
Conclusion
PMM's architecture leverages specialized open-source components (VictoriaMetrics, ClickHouse, Grafana) orchestrated by Percona-specific services (pmm-managed, pmm-agent). This modular approach allows PMM to scale from single-instance Docker deployments to complex Kubernetes clusters, providing deep visibility from node-level hardware metrics down to individual database queries.
Sources: README.md:27-52, CONTRIBUTING.md:3-55