Collector Reference
All data collectors, their intervals, and what they collect.
The Basira agent runs collectors that periodically query your database for telemetry. Each collector targets a specific system view or data source.
Interval Types
Collectors have two interval types:
- Base-rate — uses the configurable
poll_interval(default 10s). The API can adjust this dynamically via heartbeat responses. - Fixed — runs at a hardcoded interval regardless of
poll_interval.
PostgreSQL Collectors
| Collector | Interval | Type | Data Collected |
|---|---|---|---|
pg_stat_statements | poll_interval | Base-rate | Query performance stats: calls, execution time, rows, block I/O |
pg_stat_user_tables | poll_interval | Base-rate | Table stats: row counts, seq/index scans, dead tuples, vacuum times |
pg_stat_user_indexes | poll_interval | Base-rate | Index stats: scans, tuples read/fetched, size |
explain_plans | poll_interval | Base-rate | Sampled EXPLAIN ANALYZE plans for active queries |
pg_stat_activity | 5s | Fixed | Active queries, session state, wait events, blocking info |
pg_locks | 5s | Fixed | Lock type, mode, granted status, blocking relationships |
pg_wait_events | 10s | Fixed | Wait event distribution and frequency |
pg_stat_replication | 10s | Fixed | Replica lag, slot status, streaming state |
pg_stat_wal | 30s | Fixed | WAL generation rate, bytes written (PostgreSQL 14+) |
pg_stat_io | 30s | Fixed | I/O operations by backend type and object (PostgreSQL 16+) |
auto_explain | 30s | Fixed | Slow query plans from PostgreSQL log files |
pg_stat_bgwriter | 60s | Fixed | Checkpoint frequency, buffer writes, backend flushes |
pg_settings | 5m | Fixed | PostgreSQL configuration parameters |
Version Requirements
- PostgreSQL 14+ —
pg_stat_walcollector activates - PostgreSQL 16+ —
pg_stat_iocollector activates - PostgreSQL 17+ — checkpoint stats from
pg_stat_checkpointer
Collectors for unavailable views are silently skipped.
ClickHouse Collectors
| Collector | Interval | Type | Data Collected |
|---|---|---|---|
ch_query_log | poll_interval | Base-rate | Historical query stats from system.query_log |
ch_processes | 5s | Fixed | Currently running queries with resource usage |
ch_merges | 10s | Fixed | Active merge operations from system.merges |
ch_replication | 10s | Fixed | Replication status and replica lag |
ch_parts | 30s | Fixed | Data parts metadata (active parts, sizes) |
ch_mutations | 30s | Fixed | Mutation operations and progress |
ch_server_metrics | 30s | Fixed | Server-level metrics: memory, disk, connections |
ch_settings | 5m | Fixed | ClickHouse configuration parameters |
Version Requirements
- ClickHouse 21.8+ — required for
normalized_query_hashused bych_query_log
Enabling and Disabling Collectors
By default, all collectors for your database engine are enabled. To run only specific collectors, set enabled_collectors in your agent config:
databases:
- name: primary-pg
dsn: postgres://basira_monitor:pass@host:5432/db
enabled_collectors:
- pg_stat_statements
- pg_stat_activity
- pg_locksThe API can also disable collectors dynamically — for example, turning off explain_plans or replication collectors. This happens automatically via the heartbeat response, controlled by the collect_explain_plans and collect_replication settings on each database instance.
Dynamic Interval Adjustment
The API can adjust the poll_interval for base-rate collectors via heartbeat responses. When the API sends a new poll_interval_seconds, all base-rate collectors update their interval without an agent restart.