Collectors

Profiles

Collectors are selected per target with collectors.profile. Three profiles are available:

• default — the full default collector set.
• restricted — a reduced set for tightly constrained environments.
• custom — an explicit allow/deny list of collector IDs via include and exclude.

With custom, include names the collector IDs to run and exclude removes IDs from the resolved set. Collector IDs are versioned (for example pg_stat_activity_v1).

targets:
  - name: primary
    # ...connection fields...
    collectors:
      profile: custom
      include:
        - pg_stat_activity_v1
        - pg_stat_database_v1
        - pg_stat_user_tables_v1
      exclude:
        - pg_stat_statements_v1

The full, authoritative collector inventory — every ID, its PostgreSQL source, cadence, and notes — is maintained in the repository at docs/collectors.md.

Collector categories

Collectors are organised into categories by the diagnostic surface they cover. The categories and representative IDs are:

• Baseline — core built-in statistics: pg_version_v1, pg_settings_v1, pg_stat_activity_v1, pg_stat_database_v1, pg_stat_user_tables_v1, pg_statio_user_tables_v1.
• Wraparound risk — transaction-ID and multixact age: wraparound_db_level_v1, wraparound_rel_level_v1, wraparound_blockers_v1.
• Diagnostic Pack 1 — operational health, security, and planner diagnostics: bgwriter_stats_v1, blocking_locks_v1, connection_utilization_v1, planner_stats_staleness_v1.
• Server Survival Pack — conditions that can degrade or down a server: replication_slots_risk_v1, vacuum_health_v1, idle_in_txn_offenders_v1, temp_io_pressure_v1.
• Cluster identity & per-database configuration — cluster_identity_v1, pg_db_role_settings_v1.
• Index hygiene & bloat estimates — index_health_summary_v1, bloat_estimate_v1, index_bloat_estimate_v1 (statistical estimates that run on every PG without pgstattuple).
• In-flight operation progress — the pg_stat_progress_* family (vacuum, analyze, create index, cluster, basebackup, copy); empty rowsets are normal.
• I/O and WAL statistics — pg_stat_io_v1, pg_stat_wal_v1.
• Schema model & DDL definitions — daily structural inventory and bodies: pg_schemas_v1, pg_columns_v1, pg_indexes_v1, pg_functions_definitions_v1.
• Storage placement, activity summaries, function statistics, security capabilities, two-phase commit, FDW inventory — smaller focused groups such as pg_tablespaces_v1, pg_stat_activity_summary_v1, pg_role_capabilities_v1, and pg_prepared_xacts_v1.
• TimescaleDB (Tiger Data) — collected only when the timescaledb extension is present: timescaledb_hypertables_v1, timescaledb_chunks_v1, timescaledb_jobs_v1.

Cadence classes

Each collector carries its own natural cadence — the daemon does not run every collector on every cycle. Cadences fall into five classes:

• 5m — high-churn activity: sessions, locks, blocking chains, progress operations, replication lag (e.g. pg_stat_activity_v1, blocking_locks_v1).
• 15m — counters and I/O statistics (e.g. pg_stat_database_v1, vacuum_health_v1, pg_stat_io_v1).
• 1h — slower-moving operational metrics (e.g. database_sizes_v1, planner_stats_staleness_v1, pg_prepared_xacts_v1).
• 6h — configuration and structural fingerprints (e.g. pg_settings_v1, index_health_summary_v1, bloat_estimate_v1).
• 24h — daily schema model and DDL definitions (e.g. pg_schemas_v1, pg_columns_v1, wraparound_db_level_v1).

The per-collector cadence is independent of the daemon's poll_interval: a collector is eligible to run when its cadence has elapsed, so a frequent poll_interval does not force daily collectors to re-run every cycle.

Extension- and version-gated collectors

A collector may require a PostgreSQL extension or a minimum server version. When the requirement is not met, the collector is silently skipped — it never causes an error — and is recorded in collector_status.json with a reason field (extension_missing, version_unsupported, or config_disabled).

Extension-gated

• pg_stat_statements_v1 — requires the pg_stat_statements extension.
• pg_vector_columns_v1 — requires the vector extension.
• timescaledb_* — collected only when the timescaledb extension is installed; otherwise every member is skipped with reason=extension_missing.

Version-gated

• pg_stat_io_v1 — PostgreSQL 16+.
• pg_stat_wal_v1 — PostgreSQL 14+.
• pg_stat_progress_* — PostgreSQL 14+ (every member of the family).
• checkpointer_stats_v1 — PostgreSQL 17+.

High-sensitivity collectors

Some collectors read more detailed material — such as query text or rule and policy definitions. These "high-sensitivity" collectors require no privileges beyond pg_monitor, but can be disabled globally with a single toggle:

signals:
  high_sensitivity_collectors_enabled: false