Agent Configuration

The agent is configured via a single YAML file: config.yml. This page describes every configuration section and parameter.

Configuration File Location

By default, the agent looks for config.yml in the same directory as the binary. You can specify a custom path with the --config flag:

./pmp4pg-agent --config /etc/pmp4pg/agent/config.yml

Full Configuration Reference

# ============================================================
# PostgreSQL Connection
# The PostgreSQL instance to monitor
# ============================================================
postgresql:
  host: localhost
  port: 5432
  database: postgres
  user: pmp_monitor
  password: "your_monitoring_password"
  sslmode: disable             # disable | require | verify-full

# ============================================================
# Agent Identity
# Filled automatically after registration
# ============================================================
agent:
  id: ""                       # UUID assigned by the platform after registration
  id_file: /var/lib/pmp4pg-agent/agent.uuid

# ============================================================
# Server Identity
# Used during registration to describe this server
# ============================================================
server:
  hostname: ""                 # Auto-detected if left empty
  environment: RUN             # RUN (production) | BUILD (dev/staging)
  datacenter: "eu-west-1"      # Free-text label
  tags:
    - postgresql-16
    - app-backend

# ============================================================
# Backend API
# ============================================================
central:
  api_url: "http://pmp-backend.example.com:8080/pmp"
  api_key: ""                  # Assigned by the platform after registration
  timeout: 30s
  retry_attempts: 3
  retry_initial_delay: 5s
  retry_max_delay: 60s
  compression: gzip

  endpoints:
    register:             "/api/v1/register"
    heartbeat:            "/api/v1/agents/{agentId}/heartbeat"
    ash_samples:          "/api/v1/metrics/ash"
    server_snapshot:      "/api/v1/metrics/server-snapshot"
    statements_delta:     "/api/v1/metrics/statements-delta"
    database_delta:       "/api/v1/metrics/database-delta"
    database_size:        "/api/v1/metrics/database-size"
    os_metrics:           "/api/v1/metrics/os"

# ============================================================
# Registration
# Used only on first startup (before agent_id and api_key exist)
# ============================================================
registration:
  token: ""                    # One-time registration token provided by admin

# ============================================================
# Collectors — enable/disable and configure each collector
# ============================================================
collectors:

  ash:
    enabled: true
    interval: 2s               # Sampling interval (recommended: 2s)
    batch_size: 50             # Number of samples per API call

  heartbeat:
    enabled: true
    interval: 30s

  server_snapshot:
    enabled: true
    interval: 30m              # Must match the backend AWR snapshot interval

  pg_stat_statements:
    enabled: true
    interval: 60s
    min_calls: 1               # Minimum call count to include a statement

  pg_stat_database:
    enabled: true
    interval: 60s

  database_size:
    enabled: true
    interval: 10m

  os_metrics:
    enabled: true
    interval: 60s

# ============================================================
# Logging
# ============================================================
logging:
  level: info                  # debug | info | warn | error
  file: /var/log/pmp4pg-agent/agent.log
  max_size_mb: 100
  max_backups: 5
  max_age_days: 30

Key Parameters Explained

`postgresql` section

Parameter	Description
`host`	Hostname or IP of the PostgreSQL instance to monitor. Use `localhost` for a local agent.
`port`	PostgreSQL port. Default: `5432`.
`database`	Database to connect to for reading system views. `postgres` is standard.
`user`	Monitoring user created in PostgreSQL. Needs `pg_monitor` role.
`sslmode`	SSL connection mode. Use `disable` for local connections, `require` or `verify-full` for remote.

`server` section

Parameter	Description
`hostname`	Display name for this server in the platform. Auto-detected from OS if empty.
`environment`	`RUN` for production, `BUILD` for development or staging environments.
`datacenter`	Free-text label for grouping (datacenter name, cloud region, etc.).
`tags`	Optional list of tags for filtering in the dashboard.

`central` section

Parameter	Description
`api_url`	Full base URL of the PMP4PG backend, including context path (`/pmp`).
`api_key`	API key assigned after registration. Leave empty before first registration.
`timeout`	HTTP request timeout for API calls.
`retry_attempts`	Number of retry attempts on network failure.
`compression`	Payload compression. Always use `gzip`.

`collectors` section

Each collector can be individually enabled or disabled. Intervals use Go duration format: 2s, 60s, 10m, 1h.

warning

Do not set the ash.interval below 2s — this would increase repository load significantly with minimal analytical benefit.

Configuration After Registration

After the first registration, the platform assigns two values that must be written back into config.yml:

agent:
  id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"   # ← assigned by platform

central:
  api_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   # ← assigned by platform

registration:
  token: ""   # ← clear the token after registration

See Registration → for the full registration process.

Configuration File Location​

Full Configuration Reference​

Key Parameters Explained​

postgresql section​

server section​

central section​

collectors section​

Configuration After Registration​

Next Steps​