Guide on PG Exporter

Security

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

pg_exporter sits between two trust domains: it authenticates to PostgreSQL or pgBouncer, then exposes metrics and management endpoints over HTTP. Secure both sides independently. Database TLS does not protect the HTTP listener, and HTTP Basic Auth does not reduce database privileges.

Threat Surface

Surface	Sensitive capability	Primary control
PostgreSQL connection	Read monitoring views and execute collector SQL	Dedicated login, `pg_monitor`, `pg_hba.conf`, TLS
Target URL	Contains host, user, and often a password	`.pgpass`, secret file, file permissions, secret manager
`/metrics`	Reveals topology, object names, workload, and capacity	Private network, firewall, TLS/auth
`/explain` and `/stat`	Reveal collector definitions, eligibility, timing, and errors	Restrict or authenticate HTTP access
`/reload`	Triggers config parsing and an atomic query-plan replacement	Restrict or authenticate HTTP access
Collector SQL	Consumes database resources and may expose labels	Query review, least privilege, timeout, TTL, cardinality review

Use a Dedicated Database Role

For PostgreSQL 10+, the built-in pg_monitor role covers the read permissions needed by the default collectors:

Troubleshooting

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

Start by separating four layers: process, HTTP, database connectivity, and individual collectors. A running systemd unit only proves the process layer; pg_up 1 proves the current target connection and fatal collector path; a successful Prometheus scrape proves the end-to-end HTTP path.

Five-Minute Triage

# Process and logs
systemctl status pg_exporter --no-pager
journalctl -u pg_exporter -n 100 --no-pager

# HTTP and build identity
curl -fsS http://127.0.0.1:9630/version
curl -i http://127.0.0.1:9630/up

# Core metrics
curl -fsS http://127.0.0.1:9630/metrics \
  | grep -E '^(pg|pgbouncer)_(up|version|in_recovery) '

# Planning and runtime evidence
curl -fsS http://127.0.0.1:9630/explain
curl -fsS http://127.0.0.1:9630/stat

Observation	Layer to investigate
Unit exits immediately	Arguments, config path, telemetry path, listen address, file permissions
Port answers but `/up` is 503	Target URL, network, authentication, `pg_hba.conf`, TLS, startup probe state
`/up` is 200 but a metric family is absent	Dynamic plan, version/role/tags/predicates, auto-discovery, disabled collector
`/metrics` returns an error or Prometheus times out	Fatal collector, slow query, scrape timeout, label/schema mismatch
Exporter is healthy but Prometheus target is down	Prometheus address, scheme, auth, TLS, firewall, telemetry path

Process Will Not Start

`no valid config path`

The config search order is --config, PG_EXPORTER_CONFIG, ./pg_exporter.yml, /etc/pg_exporter.yml, then /etc/pg_exporter. Confirm the file exists and is readable by the runtime user:

Development

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

The project intentionally keeps most monitoring logic in YAML and a smaller execution engine in Go. Changes therefore fall into two paths: collector work and exporter-runtime work. Both paths should keep the merged configs, tests, documentation, and release metadata aligned.

Repository Layout

Path	Purpose
`exporter/`	CLI parsing, URL/config loading, planning, execution, metrics, health state, HTTP handlers, tests
`config/`	58 ordered collector definition files for PostgreSQL 10-19+ and pgBouncer
`pg_exporter.yml`	Generated monolithic default config (`make conf`)
`legacy/config/`	Collector definitions for PostgreSQL 9.1-9.6
`legacy/pg_exporter.yml`	Generated legacy monolithic config (`make conf9`)
`docs/design/`	Authoritative design notes such as snapshot histogram semantics
`monitor/`	Grafana dashboards and database initialization helper
`package/`	systemd environment/unit files and package scripts
`.goreleaser.yml`	Cross-platform archives, RPM/DEB packages, checksums, Docker images, and GitHub Release

Toolchain

The current go.mod declares Go 1.26.5. For a normal development build: