Reference on PG Exporter

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

This page is the shortest path: install pg_exporter, connect it to a PostgreSQL instance, verify metrics output, and hook it into Prometheus.

You only need two things: a reachable PostgreSQL 10-19+ (or pgBouncer 1.8+) instance, and permission to create a user in it. For older PostgreSQL 9.1-9.6 instances, see Compatibility.

Step 1: Install

On Linux amd64 you can download the binary directly (for other platforms and RPM/DEB/Docker options, see the Installation guide):

Installation

Mon, 01 Jan 0001 00:00:00 +0000

pg_exporter can be installed via Pigsty, YUM/APT repositories, GitHub release packages (RPM/DEB/Tarball), Docker images, or built from source — pick whichever fits your infrastructure.

Pigsty

The easiest way to get started with pg_exporter is to use Pigsty, which is a complete PostgreSQL distribution with built-in Observability best practices based on pg_exporter, Prometheus, and Grafana. You don’t even need to know any details about pg_exporter; it just gives you all the metrics and dashboard panels.

Compatibility

Mon, 01 Jan 0001 00:00:00 +0000

Compatibility has three separate layers: the exporter binary must run on the host, the selected collector branch must match the target server, and optional SQL objects or extensions must exist. “The process starts” therefore does not prove that every collector is eligible.

Database Targets

Target	Status	Configuration
PostgreSQL 10-18	Default support	`pg_exporter.yml` / `config/`
PostgreSQL 19	Collector branches included	Default config; validate against the current pre-release/final server build
PostgreSQL 9.1-9.6	Legacy support	`legacy/pg_exporter.yml` / `legacy/config/`
PostgreSQL 9.0 and older	Unsupported	—
pgBouncer 1.8-1.25+	Supported	`0910`-`0940` collector files; connect to the admin database

PostgreSQL 19-specific branches cover new recovery, lock, autovacuum-score, WAL, subscription, receiver, and slot fields. As of August 2026, PostgreSQL 19 is still in beta; the PostgreSQL project states that beta builds are for testing rather than production. Check the current PostgreSQL beta status before deploying a PG19 target.

Production Deployment

Mon, 01 Jan 0001 00:00:00 +0000

This page covers what it takes to run pg_exporter in production: process arguments and environment variables, monitoring user and credential management, the systemd / Docker / Kubernetes deployment forms, pgBouncer and auto-discovery, plus scrape and alerting configuration on the Prometheus side.

Process-level configuration comes from two sources, in decreasing precedence:

Command-line arguments (--url, --config, …)
Environment variables (every flag has a corresponding PG_EXPORTER_* variable)

Metric collection behavior is entirely driven by YAML collector definitions (default /etc/pg_exporter.yml, or a config directory) — see the Configuration reference.

Collector Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Every business metric in pg_exporter is driven by a YAML collector definition: one SQL query plus its execution conditions (version, role, tags, predicates) and runtime controls (caching, timeout). This page is the complete reference for collector definitions.

A configuration can be a single YAML file (like the default pg_exporter.yml) or a directory of YAML files — the official default bundle is merged from the 58 definition files under config/.

Configuration Loading

PG Exporter searches for configuration in the following order:

Bundled Collectors

Mon, 01 Jan 0001 00:00:00 +0000

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

Range	Area	Typical scope
`0000`	Authoring reference	YAML schema and examples; not an installed collector
`0100`	Identity and settings	Server identity, metadata, configuration limits
`0200`	Replication	senders, receivers, slots, subscriptions, origins
`0300`	Instance internals	I/O, storage, checkpoints, recovery, SLRU, shared memory
`0400`	Workload	WAL, sessions, waits, transactions, locks, query statistics
`0500`	Progress	VACUUM, indexing, clustering, and backup progress
`0600`	Database and logical replication	database counters, conflicts, publication/subscription state
`0700`	Relations	tables, indexes, functions, sequences, partitions
`0800`	Expensive relation analysis	size and bloat collectors
`0900`	PgBouncer	lists, databases, statistics, pools
`1000+`	Optional integrations	wait sampling, TimescaleDB, Citus, heartbeat

Complete Inventory

File	Namespace	Scope and requirement
`0000-doc.yml`	config reference	YAML schema and collector authoring guide; not installed
`0110-pg.yml`	`pg`	Basic server information, with primary and replica branches
`0120-pg_meta.yml`	`pg_meta`	Cluster metadata; PG13+ includes `primary_conninfo`
`0130-pg_setting.yml`	`pg_setting`	Shared settings and capacity limits
`0210-pg_repl.yml`	`pg_repl`	Replication sender statistics
`0220-pg_sync_standby.yml`	`pg_sync_standby`	Synchronous standby status
`0230-pg_downstream.yml`	`pg_downstream`	Downstream replication client counts
`0240-pg_slot.yml`	`pg_slot`	Replication slots; standby-aware on PG16+, PG19 invalidation reason support
`0250-pg_recv.yml`	`pg_recv`	Replica WAL receiver; PG19 `connecting` status support
`0260-pg_sub.yml`	`pg_sub`	Subscription statistics; PG19 sync-error and conflict counters
`0270-pg_origin.yml`	`pg_origin`	Replication origins; disabled by default, may need extra privileges
`0300-pg_io.yml`	`pg_io`	`pg_stat_io` on PG16+, with a PG18+ branch
`0310-pg_size.yml`	`pg_size`	Database, WAL, and log sizes
`0320-pg_archiver.yml`	`pg_archiver`	Archiver process statistics
`0330-pg_bgwriter.yml`	`pg_bgwriter`	Background writer statistics, with a PG17+ branch
`0331-pg_checkpointer.yml`	`pg_checkpointer`	Checkpointer statistics; PG18+ completion and SLRU counters
`0340-pg_ssl.yml`	`pg_ssl`	SSL client connection counts
`0350-pg_checkpoint.yml`	`pg_checkpoint`	Checkpoint control information
`0355-pg_timeline.yml`	`pg_timeline`	Current timeline ID on primary or replica
`0360-pg_recovery.yml`	`pg_recovery`, `pg_recovery_prefetch`	Replica recovery and recovery-prefetch statistics
`0370-pg_recovery_state.yml`	`pg_recovery_state`	PG19 replica recovery state from `pg_stat_recovery`
`0380-pg_slru.yml`	`pg_slru`	SLRU cache statistics on PG13+
`0390-pg_shmem.yml`	`pg_shmem`	Shared memory allocation; disabled by default, requires `schema:monitor`
`0400-pg_wal.yml`	`pg_wal`	WAL statistics on PG14+; PG19 adds full-page-image byte counters
`0410-pg_activity.yml`	`pg_activity`	Backend counts by database and state
`0420-pg_wait.yml`	`pg_wait`	Backend waits by wait-event type
`0430-pg_backend.yml`	`pg_backend`	Backend counts grouped by `backend_type`
`0440-pg_xact.yml`	`pg_xact`	Transaction snapshot boundaries and active transaction count
`0450-pg_xact_age.yml`	`pg_xact_age`	PG10+ per-database open and idle transaction age histograms
`0460-pg_lock.yml`	`pg_lock`	Lock distribution by database and mode
`0470-pg_lock_stat.yml`	`pg_lock_stat`	PG19 cluster-wide lock wait and fast-path overflow counters
`0480-pg_query.yml`	`pg_query`	Query statistics; requires `extension:pg_stat_statements`
`0510-pg_vacuuming.yml`	`pg_vacuuming`	Primary-only VACUUM progress; PG18+ includes `delay_time`
`0520-pg_indexing.yml`	`pg_indexing`	Primary-only `CREATE INDEX` progress
`0530-pg_clustering.yml`	`pg_clustering`	Primary-only `CLUSTER` and `VACUUM FULL` progress
`0540-pg_backup.yml`	`pg_backup`	Base backup progress on PG13+
`0610-pg_db.yml`	`pg_db`	Per-database statistics; PG18+ parallel-worker counters
`0620-pg_db_confl.yml`	`pg_db_confl`	Replica database conflict counters
`0640-pg_pubrel.yml`	`pg_pubrel`	Publication and publication-relation counts
`0650-pg_subrel.yml`	`pg_subrel`	Subscription relation counts grouped by state
`0660-pg_vacuum_score.yml`	`pg_vacuum_score`	PG19 autovacuum score summary from `pg_stat_autovacuum_scores`
`0700-pg_table.yml`	`pg_table`	Per-table statistics; PG18+ maintenance-time and new-page counters
`0710-pg_index.yml`	`pg_index`	Per-index statistics
`0720-pg_func.yml`	`pg_func`	Function execution statistics
`0730-pg_seq.yml`	`pg_seq`	Sequence metrics
`0740-pg_relkind.yml`	`pg_relkind`	Relation counts by kind
`0750-pg_defpart.yml`	`pg_defpart`	Default partition tuple counts
`0810-pg_table_size.yml`	`pg_table_size`	Per-table sizes; can be slow on large schemas
`0820-pg_table_bloat.yml`	`pg_table_bloat`	Disabled by default; requires auxiliary view `pg_table_bloat`
`0830-pg_index_bloat.yml`	`pg_index_bloat`	Disabled by default; requires auxiliary view `pg_index_bloat`
`0910-pgbouncer_list.yml`	`pgbouncer_list`	PgBouncer list metrics from the admin database
`0920-pgbouncer_database.yml`	`pgbouncer_database`	PgBouncer database metrics with version-specific branches
`0930-pgbouncer_stat.yml`	`pgbouncer_stat`	PgBouncer per-database statistics with version-specific branches
`0940-pgbouncer_pool.yml`	`pgbouncer_pool`	PgBouncer pool metrics with version-specific branches
`1000-pg_wait_event.yml`	`pg_wait_event`, `pg_wait_event_1s`	Wait sampling; requires `extension:pg_wait_sampling`
`1800-pg_tsdb_hypertable.yml`	`pg_tsdb_hypertable`	Disabled by default; requires TimescaleDB and its information schema
`1900-pg_citus.yml`	`pg_citus_node`	Citus worker/coordinator inventory; requires `extension:citus`
`2000-pg_heartbeat.yml`	`pg_heartbeat`	Disabled by default; requires the `monitor` heartbeat table in `postgres`

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:

HTTP API

Mon, 01 Jan 0001 00:00:00 +0000

pg_exporter exposes four kinds of HTTP endpoints on its listen port (default :9630): metrics, health checks, traffic routing, and operational management. The full endpoint list:

Endpoint	Method	Description
`/metrics`	GET	Prometheus metrics endpoint (path configurable via `--web.telemetry-path`)
`/up`	GET	Aliveness check; aliases `/health`, `/liveness`, `/readiness`, `/read`
`/primary`	GET	Primary check; aliases `/leader`, `/master`, `/read-write`, `/rw`
`/replica`	GET	Replica check; aliases `/standby`, `/slave`, `/read-only`, `/ro`
`/reload`	GET/POST	Hot-reload collector configuration
`/explain`	GET	Show per-collector planning decisions
`/stat`	GET	Per-collector runtime statistics (hits / errors / duration)
`/version`	GET	Version and build information (plain text)
`/`	GET	Landing page linking to the metrics endpoint

Health and routing endpoints answer from a cached background-probe role state (primary / replica / down / starting / unknown) — they never query the database synchronously per HTTP request, so probe storms cannot reach the database.