Agent Overview
The PMP4PG Agent is a lightweight binary written in Go, deployed directly on each PostgreSQL server you want to monitor. It is the data collection layer of the PMP4PG platform.
Role of the Agent
The agent runs as a background service on the monitored server. It:
- Connects locally to the PostgreSQL instance
- Collects metrics from PostgreSQL internal views at configured intervals
- Sends the collected data to the PMP4PG Backend via REST API
- Manages its own registration and authentication with the central platform
The agent requires no changes to your PostgreSQL configuration beyond creating a read-only monitoring user and enabling pg_stat_statements.
What the Agent Collects
The agent runs a set of independent collectors, each with its own collection interval. All intervals below are default recommended values and can be adjusted in config.yml.
| Collector | Source | Default Interval | Purpose |
|---|---|---|---|
| ASH Samples | pg_stat_activity | Every 1 second | Real-time session activity |
| Server Snapshot | Multiple sources | Every 60 seconds | AWR snapshot base data |
| pg_stat_statements | pg_stat_statements | Every 60 seconds | Query-level performance (delta) |
| pg_stat_database | pg_stat_database | Every 60 seconds | Database throughput (delta) |
| pg_stat_bgwriter | pg_stat_bgwriter | Every 60 seconds | Background writer & checkpoint stats (delta) |
| pg_stat_wal | pg_stat_wal | Every 60 seconds | WAL generation stats (delta) |
| OS Metrics | System | Every 30 seconds | CPU, memory, disk context |
| pg_locks | pg_locks | Every 10 seconds (batch every 30s) | Lock contention monitoring |
| pg_database_size | pg_database_size() | Every 5 minutes | Size tracking per database |
| pg_stat_user_tables | pg_stat_user_tables | Every 10 minutes | Table-level access & vacuum stats (delta) |
| pg_stat_user_indexes | pg_stat_user_indexes | Every 10 minutes | Index usage stats (delta) |
| pg_statio_user_tables | pg_statio_user_tables | Every 10 minutes | Table-level I/O stats (delta) |
| pg_statio_user_indexes | pg_statio_user_indexes | Every 10 minutes | Index-level I/O stats (delta) |
Most collectors compute deltas between two consecutive readings — sending only the difference since the last collection. This ensures AWR reports reflect activity during the measured period, not cumulative totals since PostgreSQL was last started.
Delta collectors also handle edge cases automatically: pg_stat_reset() detection, PostgreSQL restart detection and snapshot recovery on agent startup.
How It Works
Delta-Based Collection
For cumulative counters (like pg_stat_statements and pg_stat_database), the agent computes deltas between two consecutive readings — sending only the difference, not the absolute values. This ensures that AWR reports reflect activity during the measured period, not cumulative totals since PostgreSQL was last started.
Gzip Compression
All payloads sent to the backend are compressed with gzip, minimizing network traffic even on high-frequency ASH sampling.
Retry with Exponential Backoff
If the backend is temporarily unreachable, the agent retries automatically with exponential backoff — ensuring no data loss during short network interruptions.
Worker Pool Architecture
The agent uses a concurrent worker pool to handle metric collection and sending in parallel, without blocking the ASH sampling loop.
Agent Lifecycle
┌─────────────────────────────────────────────────────────┐
│ Agent Startup │
│ │
│ 1. Load config.yml │
│ 2. Check registration (agent_id + api_key present?) │
│ ├─ No → Enter REGISTRATION mode → exit │
│ └─ Yes → Enter NORMAL operation mode │
│ │
│ NORMAL mode: │
│ 3. Connect to PostgreSQL │
│ 4. Start all collectors (goroutines) │
│ 5. Start heartbeat sender │
│ 6. Run until stopped │
└─────────────────────────────────────────────────────────┘
Agent vs. Platform
The agent is intentionally stateless and simple. It does not store any metrics locally — all data is forwarded to the central platform. If the backend is temporarily unavailable, the agent buffers recent data in memory and retries.
The agent does not perform any analysis, aggregation or alerting — that is the responsibility of the backend.
Resource Usage
The agent is designed to be minimal:
| Resource | Usage |
|---|---|
| Memory | ~50–100 MB |
| CPU | < 0.5% average |
| Disk | ~50 MB (binary + logs) |
| Network | ~1–5 MB/hour per server (with gzip) |