Agent Configuration

The agent is configured via a single YAML file installed at /etc/pmp4pg/agent.conf. This file is created automatically when the RPM or DEB package is installed, pre-populated with default values.

Configuration File Location

Installation method	Config file path
RPM / DEB package	`/etc/pmp4pg/agent.conf`
Manual binary	Same directory as the binary (default)

You can specify a custom path at startup:

/usr/bin/pmp4pg-agent --config /etc/pmp4pg/agent.conf

Full Configuration Reference

# ============================================================
# PMP4PG Agent - Configuration File
# ============================================================
# Copy this file and fill in the values before starting the agent.
# Fields marked as "filled after registration" must be left empty
# on first start — the agent will populate them automatically.
# ============================================================

# =============================================================
# AGENT
# =============================================================
agent:
  # Agent UUID — leave empty on first start, filled after registration
  id: ""

  # API key — leave empty on first start, filled after registration
  api_key: ""

  # One-time registration token — provided by the PMP4PG admin
  # IMPORTANT: clear this field after successful registration
  registration_token: ""

  # Agent version — auto-detected if left empty
  version: "1.0.0"

# =============================================================
# POSTGRESQL CONNECTION
# =============================================================
postgresql:
  host: "localhost"
  port: 5432

  # Monitoring user created during server preparation
  # Must match the OS user if using PEER authentication
  user: "pmp4pg"

  # Leave empty to use PEER authentication (local socket, no password)
  # Set a value to use password authentication (TCP connection)
  password: "your_secure_password"

  # Initial connection database
  database: "postgres"

  # SSL mode: disable | require | verify-ca | verify-full
  ssl_mode: "disable"

  # Connection pool
  connect_timeout: 10     # seconds
  max_connections: 5      # maximum connections in pool
  idle_timeout: 300       # seconds before idle connection is closed

# =============================================================
# BACKEND API
# =============================================================
backend:
  # PMP4PG backend URL
  # Use https:// if TLS is enabled on the backend
  url: "http://<backend-host>:8080/pmp"

  # HTTP timeout for API calls (seconds)
  timeout_seconds: 30

  # Retry configuration for failed requests
  retry_attempts: 3       # number of retry attempts
  retry_delay: 5          # seconds between retries

  # Compress payload data
  compression: "gzip"     # "gzip" or ""

  # TLS configuration for agent → backend communication
  tls:
    enabled: false                          # set to true when backend uses HTTPS
    skip_verify: false                       # set to true only for self-signed certificates
    ca_cert: ""                              # path to a custom CA certificate (private PKI)
                                              # example: /etc/pmp4pg/certs/ca.pem

# =============================================================
# SITE
# =============================================================
site:
  # Site code — must match an existing site in the PMP4PG backend
  code: "PAR01"

  # The following fields are used only if the site does not exist yet
  name: "Paris Datacenter"
  location: "Paris, France"
  datacenter: "DC-PARIS-01"
  timezone: "Europe/Paris"
  description: ""

# =============================================================
# HOST
# =============================================================
host:
  # Deployment type: BARE_METAL | VM | CONTAINER | CLOUD
  deployment_type: "VM"

# =============================================================
# SERVER
# =============================================================
server:
  # Server UUID — leave empty on first start, filled after registration
  id: ""

  # Environment: RUN | DR | BUILD
  environment: "RUN"

  # Optional free-text tag for classification
  tag: ""

# =============================================================
# HEALTH CHECK SERVER
# =============================================================
health:
  # Enable the local health check HTTP server
  enabled: true

  # Listening port
  port: 8080

  # Heartbeat interval sent to the backend
  heartbeat_interval: 60s

# =============================================================
# COLLECTION — GENERAL
# =============================================================
collection:
  send_interval_seconds: 20
  max_active_sessions: 500
  server_snapshot_interval: 30s
  enable_server_snapshot: true

# =============================================================
# COLLECTORS
# =============================================================
collectors:

  # --- Active Session History (ASH) ---
  ash:
    enabled: true
    interval: 1s

  # --- Server snapshot (version, extensions, parameters) ---
  server_snapshot:
    enabled: true
    interval: 60s
    send_async: true
    worker_pool_size: 2
    send_queue_size: 10

  # --- pg_stat_statements ---
  pg_stat_statements:
    enabled: true
    interval: 60s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 3
    send_queue_size: 10
    detect_reset: true
    detect_pg_restart: true

  # --- pg_stat_database ---
  pg_stat_database:
    enabled: true
    interval: 60s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 3
    send_queue_size: 10
    detect_reset: true
    detect_pg_restart: true

  # --- Database sizes ---
  pg_database_size:
    enabled: true
    interval: 5m
    send_async: true
    worker_pool_size: 2
    send_queue_size: 10

  # --- Lock monitoring ---
  pg_locks:
    enabled: true
    interval: 10s            # collection interval
    send_interval: 30s       # batch send interval

  # --- pg_stat_bgwriter ---
  pg_stat_bgwriter:
    enabled: true
    interval: 60s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- pg_stat_wal ---
  pg_stat_wal:
    enabled: true
    interval: 60s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- pg_stat_user_tables ---
  pg_stat_user_tables:
    enabled: true
    interval: 600s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- pg_stat_user_indexes ---
  pg_stat_user_indexes:
    enabled: true
    interval: 600s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- pg_statio_user_tables ---
  pg_statio_user_tables:
    enabled: true
    interval: 600s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- pg_statio_user_indexes ---
  pg_statio_user_indexes:
    enabled: true
    interval: 600s
    send_async: true
    filter_zero_deltas: true
    recovery_on_startup: true
    worker_pool_size: 2
    send_queue_size: 10
    detect_reset: true

  # --- OS metrics (CPU, memory, disk, network) ---
  os_metrics:
    enabled: true
    interval: 30s
    send_async: true
    worker_pool_size: 2
    send_queue_size: 20

# =============================================================
# BUFFER
# =============================================================
buffer:
  # Maximum buffer size in MB
  max_size_mb: 50

  # Maximum number of samples to store
  max_samples: 1250000

  # Overwrite oldest data when buffer is full
  overwrite_oldest: true

# =============================================================
# LOGGING
# =============================================================
logging:
  # Log level: debug | info | warn | error
  level: "info"

  # Log format: text | json
  format: "text"

  # Output: stdout | file
  # When installed as a systemd service, stdout is redirected to
  # /var/log/pmp4pg/agent.log automatically — keep output as stdout
  output: "stdout"

  # Log file path (only used when output = file)
  file_path: "/var/log/pmp4pg/agent.log"

  # Log rotation (only used when output = file)
  max_size_mb: 100    # max size before rotation
  max_backups: 3      # number of rotated files to keep
  max_age_days: 7     # days to retain old log files

Key Parameters Explained

`agent` section

Parameter	Description
`id`	UUID assigned by the platform at registration. Leave empty before first registration.
`api_key`	API key assigned at registration. Leave empty before first registration.
`registration_token`	One-time token provided by a platform administrator. Must be cleared after registration.

`postgresql` section

Parameter	Description
`host`	Hostname of the PostgreSQL instance to monitor. Use `localhost` for a local agent.
`port`	PostgreSQL port. Default: `5432`.
`user`	Monitoring user — requires `pg_monitor` role. Must match the OS user when using PEER authentication.
`password`	Leave empty to use PEER authentication over the local Unix socket (no password). Set a value to use password authentication over TCP.
`ssl_mode`	SSL connection mode for the PostgreSQL connection. Use `disable` for local connections.

PEER vs Password Authentication

If the agent runs on the same host as the monitored PostgreSQL instance and connects via local socket, leave postgresql.password empty and ensure the OS user running the agent matches postgresql.user for PEER authentication. For remote or password-based connections, set both user and password.

`backend` section

Parameter	Description
`url`	Full base URL of the PMP4PG backend including context path (`/pmp`). Use `http://` by default (port 8080), or `https://` if TLS is enabled on the backend (port 8443).
`retry_attempts`	Number of retry attempts on network failure.
`compression`	Compresses the payload sent to the backend. Set to `gzip` to reduce network bandwidth, or `""` to disable.
`tls.enabled`	Set to `true` only when the backend has HTTPS enabled. Must match the backend's `server.ssl.enabled` setting.
`tls.skip_verify`	Set to `true` to skip certificate validation — use only with self-signed certificates in trusted internal networks.
`tls.ca_cert`	Path to a custom CA certificate file, required when the backend uses a certificate issued by a private/internal CA.

warning

tls.skip_verify: true disables certificate validation entirely, exposing the agent-to-backend connection to man-in-the-middle attacks. Use only on trusted internal networks, and prefer providing tls.ca_cert instead whenever possible.

`site` section

The site code must match an existing site configured in the platform. If the site does not exist, the optional fields (name, location, etc.) will be used to create it during registration.

`server` section

Parameter	Description
`id`	Server UUID — assigned at registration. Leave empty before first registration.
`environment`	`RUN`, `DR` or `BUILD` — used for filtering and environment badges in the dashboard.
`tag`	Optional free-text label for additional classification.

`collection` section

General collection settings shared across the agent, independent of individual collectors.

Parameter	Description
`send_interval_seconds`	General interval used for sending buffered data to the backend.
`max_active_sessions`	Maximum number of concurrent sessions tracked per ASH sample.
`server_snapshot_interval`	Interval for capturing server-level snapshot metadata.
`enable_server_snapshot`	Enables or disables server snapshot collection entirely.

`collectors` section

Each collector can be individually enabled or disabled. Intervals use Go duration format: 1s, 30s, 5m, 600s.

Configuration After Registration

After successful registration, three values are assigned by the platform and must be written back into agent.conf:

agent:
  id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"     # ← assigned by platform
  api_key: "api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"   # ← assigned by platform
  registration_token: ""                           # ← clear after registration

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

danger

The registration_token must be cleared after registration. Leaving it set will cause the agent to attempt re-registration on every restart.

See Enroll a New Server → for the full registration process.

Configuration File Location​

Full Configuration Reference​

Key Parameters Explained​

agent section​

postgresql section​

backend section​

site section​

server section​

collection section​

collectors section​

Configuration After Registration​

Next Steps​