| title | postgres_exporter Documentation |
|---|---|
| nav_title | Overview |
| sort_rank | 1 |
postgres_exporter is a Prometheus exporter for PostgreSQL server metrics. It connects to a PostgreSQL instance as a regular database user, queries the server's built-in statistics views on each scrape, and exposes the results as Prometheus metrics over HTTP.
It is a Prometheus Community project.
The exporter reads PostgreSQL's own statistics and catalog views — nothing is instrumented inside your application. Metrics are grouped into collectors that can be enabled or disabled individually, covering areas such as:
- Connections and activity — backend counts by state, long-running transactions, idle sessions, autovacuum workers.
- Database-level statistics — commits, rollbacks, block reads/hits, deadlocks, temp file usage, size on disk.
- Table and index I/O — sequential vs. index scans, tuple counts, dead tuples, vacuum/analyze times.
- Replication — replica lag, replication slots, WAL receiver state, WAL generation.
- Checkpointing and background writer — checkpoint counts and timings, buffers written.
- Query statistics — per-query call counts and timings via the
pg_stat_statementsextension (opt-in). - Server configuration — the values of
pg_settings, exported as metrics so configuration drift is queryable.
All metrics are prefixed with pg_. The exporter's own health is exposed via pg_up and pg_exporter_* metrics alongside the standard Go runtime metrics.
Run postgres_exporter --help for the authoritative list of collectors and flags in the version you're running.
The exporter is tested in CI against PostgreSQL 13, 14, 15, 16, 17, and 18. Older versions generally still work — the exporter detects the server version at connection time and adjusts its queries — but they are not covered by CI and issues against them are lower priority.
A few collectors are version-gated, for example stat_checkpointer requires PostgreSQL 17 or newer.
The exporter can be run in either of two ways:
- Single-target (the default). One exporter process per PostgreSQL instance, usually deployed as a sidecar, serving that instance's metrics at
/metrics. This is the recommended setup. - Multi-target (
/probe). One exporter process scrapes many instances, with the target chosen per HTTP request. Useful when a sidecar isn't possible, such as with managed/SaaS PostgreSQL.
See Connecting to PostgreSQL for details on both.
Start here
- Getting Started — run the exporter and scrape your first metrics.
- Docker Images — where the images live and how to run them.
Configuration and operation
- Configuring the Exporter — collectors, flags, environment variables, and the config file.
- Connecting to PostgreSQL — DSNs, single-target vs. multi-target, timeouts.
- Database Permissions — the SQL grants the exporter needs.
- Secrets — ways to supply credentials without putting them on the command line.
Environment-specific
- Running Against AWS RDS — RDS-specific setup notes.
The repository ships a Prometheus mixin containing Grafana dashboards and alerting rules built on these metrics.
- Bugs and feature requests: GitHub issues.
- Questions and discussion: the
#prometheuschannel on CNCF Slack.