Inventory Management
Relevant source files
The following files were used as context for generating this wiki page:
Inventory Management is a core system within Percona Monitoring and Management (PMM) responsible for tracking and managing the lifecycle of entities involved in database monitoring. This includes Nodes (physical or virtual hosts), Services (database instances like MySQL or MongoDB), and Agents (software components that collect metrics or perform maintenance tasks).
The system provides a central registry and API to register, update, and remove these entities. It ensures that monitoring components are correctly associated with the infrastructure they monitor, enabling PMM Server to orchestrate metric collection across complex, distributed environments.
Sources: README.md, managed/models/database.go:94-150
Core Entities and Data Model
The inventory is built upon three primary relational entities stored in the PMM Server database.
Nodes
Nodes represent the physical or virtual infrastructure. There are several types of nodes supported:
- Generic: Bare metal servers or virtual machines.
- Container: Docker containers.
- Remote: Infrastructure where PMM-agent does not run (e.g., cloud databases).
- Remote RDS/Azure: Managed database services from AWS and Azure.
Sources: api/inventory/v1/nodes.pb.go:26-40, managed/models/database.go:103-125
Services
Services represent the actual database engines or proxy services being monitored. A service is always associated with a specific node_id. Supported service types include MySQL, MongoDB, PostgreSQL, ProxySQL, Valkey, and ClickHouse.
Sources: api/inventory/v1/agents.proto:20-43, managed/models/database.go:137-156
Agents
Agents are the functional units of monitoring. They generally fall into two categories:
- Exporters: Collect metrics (e.g.,
node_exporter,mysqld_exporter). - QAN Agents: Collect Query Analytics data (e.g.,
qan_mysql_slowlog_agent).
Agents are either managed by a pmm-agent (running on a host) or act as external collectors.
Sources: api/inventory/v1/agents.proto:20-43, managed/models/database.go:158-185
Entity Relationships
The following diagram illustrates the relationship between core inventory entities.
The diagram shows that a Node can host multiple Services and run multiple Agents. An Agent can monitor a specific Service, and some Agents (sub-agents) are managed by a primary pmm-agent.
Sources: managed/models/database.go:103-185
Architecture and Data Flow
Inventory Management follows a client-server architecture where pmm-managed on the PMM Server acts as the central authority.
Registration Flow
When a new node or service is added, the request flows through the management service to the inventory service, which persists the data and triggers state updates for related agents.
The flow demonstrates how an API request is processed by the management layer, persisted in the database, and then propagated to the actual monitoring agents to begin data collection.
Sources: managed/services/inventory/nodes.go:50-84, managed/services/management/management.go:34-66
Node Management Logic
The NodesService handles the business logic for node operations. It supports adding various node types through specific parameter structures.
| Operation | Function | Description |
|---|---|---|
| Add | AddNode | Dispatches to type-specific adders (Generic, Container, Remote, etc.). |
| Get | Get | Retrieves a single node by its unique ID. |
| List | List | Returns a filtered list of nodes. |
| Remove | Remove | Deletes a node. Supports force mode for cascading deletion of services and agents. |
Sources: managed/services/inventory/nodes.go:50-252
Database Schema and Migrations
The inventory uses a PostgreSQL database with a versioned schema. Migrations are handled automatically during PMM Server startup.
Key Tables Summary
| Table Name | Purpose | Primary Key |
|---|---|---|
nodes | Infrastructure registry | node_id |
services | Database engine registry | service_id |
agents | Monitoring components registry | agent_id |
schema_migrations | Tracks applied database updates | id |
Sources: managed/models/database.go:101-185
Schema Definition Snippet
CREATE TABLE nodes (
node_id VARCHAR NOT NULL,
node_type VARCHAR NOT NULL CHECK (node_type <> ''),
node_name VARCHAR NOT NULL CHECK (node_name <> ''),
address VARCHAR NOT NULL,
created_at TIMESTAMP NOT NULL,
updated_at TIMESTAMP NOT NULL,
PRIMARY KEY (node_id),
UNIQUE (node_name)
);
Sources: managed/models/database.go:103-125
Agent Types and Configuration
The system supports a wide array of agents, each with specific configuration requirements defined in Protobuf messages.
Agent Types Overview
- PMM Agent: The main orchestrator on a monitored host.
- Node Exporter: Collects host-level OS metrics.
- DB Exporters: Specialized collectors for MySQL, MongoDB, PostgreSQL, etc.
- QAN Agents: Profile queries for performance analysis.
- VM Agent: Handles metric pushing to VictoriaMetrics.
Sources: api/inventory/v1/agents.proto:17-43
Common Agent Parameters
Most agents share a set of common parameters used for lifecycle management and connection settings:
disabled: Boolean to enable/disable collection.custom_labels: Key-value pairs for metadata.push_metrics_enabled: Defines if the agent pushes metrics or waits to be scraped.tls/tls_skip_verify: Security settings for database connections.
Sources: api/inventory/v1/agents.proto:137-160, managed/models/database.go:193-210
Conclusion
Inventory Management provides the structural foundation for Percona Monitoring and Management. By maintaining a strict hierarchy of Nodes, Services, and Agents, it allows PMM to scale monitoring across diverse infrastructures ranging from bare-metal servers to cloud-native managed databases. The system ensures that monitoring is consistent, secure, and easily manageable through a unified API.