Skip to content

Getting Started

Get pg_exporter running and see PostgreSQL metrics in Prometheus within ten minutes

Follow these steps to install pg_exporter, connect to PostgreSQL, check metrics, and configure Prometheus.

You need a reachable PostgreSQL 10-19+ or pgBouncer 1.8+ instance and permission to create a user in it. For PostgreSQL 9.1-9.6, see Compatibility.

Step 1: Install

On Linux amd64, download the binary directly. For other platforms and RPM/DEB/Docker options, see the Installation guide.

VERSION=$(curl -fsSL https://api.github.com/repos/pgsty/pg_exporter/releases/latest | sed -n 's/.*"tag_name": "v\([^"]*\)".*/\1/p')
wget "https://github.com/pgsty/pg_exporter/releases/download/v${VERSION}/pg_exporter-${VERSION}.linux-amd64.tar.gz"
mkdir -p "pg_exporter-${VERSION}.linux-amd64"
tar -xf "pg_exporter-${VERSION}.linux-amd64.tar.gz" -C "pg_exporter-${VERSION}.linux-amd64"
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter" /usr/bin/
sudo install "pg_exporter-${VERSION}.linux-amd64/pg_exporter.yml" /etc/pg_exporter.yml

Confirm the installation:

pg_exporter --version
# pg_exporter v1.5.0 (built with go1.27.3 on linux/amd64)

Step 2: Create a Monitoring User

Create a dedicated monitoring user on the target PostgreSQL instance. Start with the built-in pg_monitor role in PostgreSQL 10+:

CREATE USER monitor WITH PASSWORD 'S3cret';
GRANT pg_monitor TO monitor;

On PostgreSQL 10–13, an administrator must also run the following grant in the exporter’s main connection database to read subscription OIDs. Granting it only in the database owning the subscription is insufficient. This does not expose the password-bearing subconninfo column. PostgreSQL 14+ needs no extra grant under standard catalog ACLs.

GRANT SELECT (oid) ON pg_catalog.pg_subscription TO monitor;

For a local test with a superuser such as postgres, you can skip this step.

Step 3: Run and Verify

Use --dry-run to check that the configuration parses correctly. Then start the exporter:

export PG_EXPORTER_URL='postgres://monitor:S3cret@localhost:5432/postgres'

pg_exporter --dry-run     # print parsed collector config, then exit
pg_exporter               # start for real, listening on :9630 by default

If you do not specify a URL, pg_exporter uses postgresql:///?sslmode=disable to connect on the same host. The URL source order is --url > PG_EXPORTER_URL > PGURL > PG_EXPORTER_URL_FILE > default. See the Deployment guide for details.

Get the metrics from another terminal:

curl -s http://localhost:9630/metrics | grep -E '^pg_(up|version|in_recovery) '

You should see the three core built-in metrics:

pg_up 1              # 1 when the target is reachable, 0 otherwise
pg_version 170000    # version in server_version_num format
pg_in_recovery 0     # 1 on replicas, 0 on primaries

pg_up 1 shows that the connection and metric collection work. The pg_exporter.yml bundle defines 460 distinct metric names (pg_db_*, pg_table_*, pg_wal_*, and others), with applicable metrics selected by version, role, and database objects. If pg_up is 0, restart with pg_exporter --log.level=debug and examine the connection error.

Step 4: Hook into Prometheus

Add a scrape target in prometheus.yml:

scrape_configs:
  - job_name: 'postgresql'
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9630']

Collectors cache results for their ttl. Most realtime collectors use ttl: 10. If the TTL is less than the scrape interval, each scrape gets fresh data. The cache also prevents high-frequency scrapes from overloading the database. Do not set scrape_interval below the common collector TTLs.

For Grafana, use the PostgreSQL dashboards from Pigsty, or view the live demo.

Troubleshooting

SymptomWhat to do
pg_up 0, connection failsRun pg_exporter --log.level=debug and read the error; check URL, pg_hba.conf, and network reachability
Some metrics are missingcurl localhost:9630/explain to see each collector’s planning verdict (version gates, tags, predicates)
A collector keeps failingcurl localhost:9630/stat for per-collector error counters and durations
Scrapes are slowFind the slow collector in /stat, raise its ttl, or set skip: true

/stat, /explain, and /reload are management endpoints. In production, protect them with --web.config.file for TLS/auth, or keep them on a trusted network. See the API Reference.

Next Steps

  • Monitor pgBouncer, enable auto-discovery, deploy with systemd / Docker / Kubernetes: Deployment guide
  • Understand and customize collectors (GAUGE/COUNTER/HISTOGRAM, TTL, tags, version gates): Configuration reference
  • Health check and primary/replica traffic routing endpoints (/up, /primary, /replica): API Reference

Was this page helpful?

Last Modified 2026-10-23 · docs: publish PG Exporter v1.5.0 release and manuals (dbaf295f)