Bundled Collectors

PG Exporter v1.6.0 ships 58 YAML files (57 collector files and one schema reference) 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. On the first scrape, PG Exporter evaluates server facts and selects eligible branches; GET /explain shows that plan for the connected target.

Across version branches, v1.6.0 defines 59 collector namespaces and 460 distinct metric names before histogram expansion. This count includes disabled collectors and two HISTOGRAM definitions. The number of series in a scrape depends on the selected branches, rows, labels, and histogram buckets.

Before upgrading PostgreSQL or replacing the collector configuration, review the metric compatibility and migration tables. They distinguish v1.5.0 label/state corrections, PG19 additions and semantic changes, and metrics removed at earlier PostgreSQL version boundaries, with checks for missing-series alerts.

Numbering Map

Complete Inventory

Plan Before Enabling

The planner selects branches by target type, server version, recovery role, database, extensions, schemas, username, and tags. Predicates run later, when a collector refreshes its results. After the first scrape, inspect the current plan for the main target:

curl -fsS http://127.0.0.1:9630/metrics >/dev/null
curl -fsS http://127.0.0.1:9630/explain

/explain returns plain text for selected collectors. Use --log.level=debug to see why a branch was excluded.

pg_origin, pg_shmem, both bloat collectors, the TimescaleDB collector, and pg_heartbeat use skip: true. Prepare their required permissions and objects before setting skip: false. The heartbeat collector reads a table maintained by a separate heartbeat writer.

Replication origin permissions

pg_origin remains disabled by default. On PostgreSQL 14+ with standard catalog ACLs, an administrator must grant access in the exporter’s main connection database, substituting the actual monitoring role for monitor:

GRANT SELECT ON pg_catalog.pg_replication_origin_status TO monitor;
GRANT EXECUTE ON FUNCTION
  pg_catalog.pg_show_replication_origin_status() TO monitor;

Then explicitly set skip: false for this collector in the configuration you load, reload or restart the exporter, and check its query errors and expected origin samples. pg_monitor membership alone is insufficient. PostgreSQL 13 and older also check for superuser inside the function, so these grants alone cannot enable direct access for an ordinary monitoring role; keep this optional collector disabled there. The exporter does not grant privileges automatically.

Publication and subscription counts

pg_pubrel_count counts table entries returned by pg_get_publication_tables(). It excludes sequences, including on PG19. Empty and sequence-only publications produce no series, rather than an explicit zero.

pg_subrel_count counts pg_subscription_rel entries grouped by subscription and synchronization state. On PG19 this includes both tables and sequences. Table states are i (initialize), d (data copy), f (finished table copy), s (synchronized), and r (ready); PG19 sequences use i or r.

Do not treat equal publication/subscription counts as a replication-health test: the two collectors count different sets. Publication overlap, partition handling, refresh, and synchronization progress also affect the counts.

Subscription identity and receiver states

The v1.5.0 configuration corrects subscription identity and receiver states. Review these upgrade requirements when replacing an older collector configuration:

• Every pg_sub_* sample gains a datname label for the database owning the subscription. Together with subname, this distinguishes equal names in different databases. The existing pg_sub_id gauge is retained. The label change creates new time series; check label-sensitive PromQL joins and aggregations before rollout.
• On PG10–13, before deploying the new configuration, an administrator must run GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor; in each database used as the exporter’s main connection database. Granting it only in a subscription’s database is insufficient. This does not grant access to subconninfo. PG14+ needs no extra grant under the standard catalog ACLs. Without this prerequisite, subscription queries fail and their metrics are absent; HTTP 200 alone does not prove a successful scrape.
• pg_recv_state uses the dictionary below in both current and legacy configurations. Codes 1–3 are reserved. PG9.6–18 has no connecting state. A missing receiver row remains absent; it is not filled with zero or a synthetic stopped sample.
• The legacy receiver query uses PG9.6-compatible scalar substring() to extract the host and port. On PG9.6, PostgreSQL still hides receiver details from non-superusers: only the PID is visible and the collector reports state -1. This SQL correction does not change database privileges.

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 selects up to 128 statement groups, ordered by calls, from pg_stat_statements. Its query IDs can change over time.
• 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 ttl to limit how often expensive SQL runs. Set timeout from measured query duration. The scrape timeout must allow for the complete collection pass, including all discovered databases. Compare pg_exporter_scrape_duration and the series count before and after a change.

Customize Collectors

Start with a copy of the complete configuration directory. Put local definitions in a later file, such as 9990-local.yml. To replace an existing branch, use its exact top-level key and provide the full definition; directory loading replaces the whole branch. Give new branches unique keys and keep version ranges for the same metric family separate.

Select that directory explicitly and validate it:

pg_exporter --config=/path/to/collectors --dry-run
# Run this command in one terminal.
PG_EXPORTER_CONFIG=/path/to/collectors pg_exporter

# In another terminal, scrape first, then inspect the plan.
curl -fsS http://127.0.0.1:9630/metrics >/dev/null
curl -fsS http://127.0.0.1:9630/explain

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