# percona/pmm architecture

> Architecture diagram of the GitHub repository percona/pmm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/percona/pmm
- Repository: https://github.com/percona/pmm

## Overview

##### Major components
- PMM Server: The heart of the system. It provides the web interface (dashboards, administration), aggregates metrics, manages alerts, and communicates with agents. In the file tree you see directories like “admin”, “api”, “managed”, and “vmproxy” that indicate components for administration, API endpoints, and proxying.
- PMM Client / Agent: The code in directories “agent” and “qan-api2” include functionalities for metric collection, log analysis, query reporting, and interacting with various exporters. The agents are deployed on monitored database hosts to collect performance data and send it to the server.
- Exporters and Integration Modules: Inside the “agent” directory and in subfolders (such as “agents”, “runner”, and “queryparser”), there are specialized modules that interface with MySQL, MongoDB, PostgreSQL, etc. They translate database-specific metrics into a common format.
- Data Stores and Time-Series Databases: Although not directly visible as a specific directory in code, the architecture relies on external time-series databases (like Prometheus and/or VictoriaMetrics) to store collected metrics. The readme and documentation images show integration with Grafana and Prometheus.
- Web UI / Dashboard: The PMM Server provides a dashboard (as shown in the readme login screenshot) that offers in-depth performance visualization. This layer ties to the API components (files under “api” directory) that support both REST and gRPC interfaces.

##### Breakdown architectural interactions
- Agents on monitored nodes (PMM Client) collect metrics and perform local analysis. They communicate via gRPC or REST to push data to the PMM Server.
- The PMM Server (including “admin”, “api”, “managed” services) receives metric data and aggregates it. The server then pushes data to and queries time-series storage as needed.
- The system supports external integrations like Grafana for dashboards, Alertmanager for notifications, and possibly additional integration to cloud services.
- The “qan-api2” component indicates a specialized analytics layer that handles advanced query analytics and reporting.
- VMProxy, managed modules, and update modules indicate additional microservices that assist in proxying client connections, managing configuration, performing upgrades, and handling high-availability requirements.

##### Architectural patterns and design principles
- Microservices: The use of several distinct directories (admin, agent, api, managed, qan-api2, vmproxy) shows a modular, service-oriented approach where each component has a specialized responsibility.
- Client/Server separation: The PMM server offers a centralized control and visualization layer while agents deployed in individual instances handle collection and real-time monitoring.
- Use of both REST and gRPC: The presence of protobuf definitions and .pb.go files across api and agent directories illustrate that multiple communication protocols are used for inter-service communication.
- Containerization and orchestration: The numerous Dockerfiles, docker-compose files, and build scripts indicate deployment and orchestration best practices. (This helps to ensure that each service can be deployed independently.)

##### Additional notes
- Annotations or notes on each connection if any specific protocol or technology (e.g., Prometheus for time-series data, gRPC for low-latency inter-service communication) is used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Monitored Databases
    subgraph "External Monitored Databases"
        MySQL["MySQL"]:::external
        MongoDB["MongoDB"]:::external
        PostgreSQL["PostgreSQL"]:::external
        MariaDB["MariaDB"]:::external
    end

    %% External Integrations
    subgraph "External Integrations"
        Prometheus["Prometheus_TSDB"]:::external
        Grafana["Grafana_Dashboard"]:::external
        Alertmanager["Alertmanager"]:::external
    end

    %% PMM Client/Agent Components
    subgraph "PMM Client/Agent"
        Agent["PMM Agent (Agent Functionality)"]:::client
        Exporters["Exporters & Integration Modules"]:::client
        Agent2["Query Analytics (qan-api2)"]:::client
    end

    %% PMM Server Components
    subgraph "PMM Server"
        WebUI["Web UI / Dashboard"]:::server
        APIGateway["API Endpoints (REST/gRPC)"]:::server
        AdminMgmt["Administration & Management Services"]:::server
        ManagedServer["Managed Server Services"]:::server
        VMProxy["Connection Proxy Service"]:::server
    end

    %% Data Collection from Databases to Agent Components
    MySQL -->|"metrics_collection"| Agent
    MongoDB -->|"metrics_collection"| Agent
    PostgreSQL -->|"metrics_collection"| Agent
    MariaDB -->|"metrics_collection"| Agent

    %% Internal interactions within PMM Client/Agent
    Agent -->|"integrates_with"| Exporters
    Agent2 -->|"advanced_query"| Agent

    %% Communication from Client/Agent to PMM Server
    Agent -->|"metric_push_(gRPC/REST)"| APIGateway
    Agent2 -->|"query_analytics_(gRPC)"| APIGateway

    %% Internal PMM Server interactions
    APIGateway -->|"serves_data_to"| WebUI
    AdminMgmt -->|"manages_alerts_config"| APIGateway
    ManagedServer -->|"processes_internal_tasks"| APIGateway
    VMProxy -->|"handles_connection"| APIGateway

    %% PMM Server interactions with External Integrations
    APIGateway -->|"stores_metrics"| Prometheus
    APIGateway -->|"renders_dashboards"| Grafana
    AdminMgmt -->|"sends_alerts"| Alertmanager

    %% Click Events
    click AdminMgmt "https://github.com/percona/pmm/tree/main/admin"
    click APIGateway "https://github.com/percona/pmm/tree/main/api"
    click ManagedServer "https://github.com/percona/pmm/tree/main/managed"
    click VMProxy "https://github.com/percona/pmm/tree/main/vmproxy"
    click Agent "https://github.com/percona/pmm/tree/main/agent"
    click Agent2 "https://github.com/percona/pmm/tree/main/qan-api2"
    click Exporters "https://github.com/percona/pmm/tree/main/agent/agents"

    %% Styles
    classDef client fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef server fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef external fill:#f9d5bb,stroke:#333,stroke-width:2px;
```
