Bundled Collectors

PG Exporter v1.4.1 ships 58 collector definition files under config/. They are merged in filename order into the default pg_exporter.yml by make conf.

The filename prefix is an ordering convention, not a metric name. A file can define multiple version- or role-specific branches with the same public metric namespace. At startup, PG Exporter evaluates server facts and installs only the eligible branch; GET /explain shows that plan for the connected target.

Numbering Map

Complete Inventory

Plan Before Enabling

Do not treat all 58 files as 58 unconditional queries. The planner selects branches using PostgreSQL or PgBouncer version, recovery role, target database, extensions, schemas, username, and predicate results. Inspect the real plan before tuning:

curl -fsS http://127.0.0.1:9630/explain
curl -fsS http://127.0.0.1:9630/explain | jq '.[] | {name, status, reason}'

Disabled collectors deserve an explicit review. pg_origin, pg_shmem, both bloat collectors, the TimescaleDB collector, and pg_heartbeat are intentionally not enabled in the generic plan because they need privileges, helper objects, a specific extension, or a deliberate write/read workflow.

Cardinality and Cost

Per-relation and per-query collectors are the main cardinality drivers. Review these before enabling them on a large estate:

• pg_table, pg_index, pg_func, and pg_seq emit one or more series per object.
• pg_query grows with the normalized statements retained by pg_stat_statements.
• pg_table_size, pg_table_bloat, and pg_index_bloat can be expensive on catalogs with many relations.
• Wait-event sampling uses an extension and can emit dimensions that vary with workload.

Use collector ttl to cache expensive results, set a realistic per-collector timeout, and scrape at an interval that exceeds the slowest expected collector. Compare /metrics duration and series count before and after a change; never infer safety from config validation alone.

Customize Safely

Keep local collector overrides in a separate directory rather than editing the generated monolith. Copy the smallest relevant file, give every top-level branch a globally unique name, preserve non-overlapping version ranges, and validate the result with:

pg_exporter --config=/path/to/collectors --dry-run
PG_EXPORTER_CONFIG=/path/to/collectors pg_exporter
curl -fsS http://127.0.0.1:9630/explain
curl -fsS http://127.0.0.1:9630/metrics >/dev/null

The complete collector schema, query-to-metric mapping, tags, predicates, cache behavior, timeout semantics, and histogram rules are documented in Collector Configuration.