API Reference
pg_exporter provides four types of HTTP endpoints: metrics, health checks, traffic routing, and operational management.
The default listen port is :9630. The following table lists all endpoints:
| 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 return the cached state from background probes: primary, replica, down, starting, or unknown.
They do not query the database for each HTTP request. In v1.5.0, each response reads one atomic state snapshot, so its HTTP status and body always describe the same state. The cached state can still lag behind the database. A successful PgBouncer probe maps to primary; it does not describe the role of its PostgreSQL backend.
Metrics Endpoint
GET /metrics
This endpoint returns all collected metrics in Prometheus format.
Request
Response
Response Format
Metrics follow the Prometheus exposition format:
Since v1.6.0, at most two metrics requests are admitted across collection, waiting, and response writing. Scrapes still run serially; one request can wait within its remaining budget, and further concurrent requests receive HTTP 503. The budget defaults to 30 seconds and is shortened by a valid, finite, positive X-Prometheus-Scrape-Timeout-Seconds header. A request canceled while waiting does not start SQL work.
After request cancellation, the exporter does not start the next collector or database. A collector already started with a positive timeout keeps its shared predicate-and-query deadline and caches a successful refresh. A negative timeout disables that deadline, so the query cancels with the request. An interrupted scrape returns 503 if the connection still accepts a response. Driver and network blocking mean these deadlines are not hard wall-clock caps; configure connect_timeout in the DSN to bound connection handshakes.
Interrupted rounds do not increment pg_exporter_scrape_error_count or pg_exporter_server_scrape_error_count, and log INFO interrupted; query error counters and fatal-query ERROR logs remain active. A real failure that overlaps request cancellation can therefore be omitted from those two round counters. Without request cancellation, connection/precheck failures and fatal query failures (including their own timeouts) still count as errors; non-fatal failures remain visible in query-level counters.
Failed refreshes keep the existing failure TTL. In particular, a fatal collector with a negative timeout caches a fatal failure when canceled; later active scrapes can count that cached failure and report pg_up 0 until a refresh succeeds. Keep positive timeouts on fatal collectors. See Scrape Lifetime for rationale.
Self-Monitoring Metrics
Built-in PostgreSQL metrics default to the pg prefix; PgBouncer uses pgbouncer. --namespace changes these prefixes, and invalid namespaces are rejected at startup. It does not rename metrics defined in YAML.
| Metric | Type | Labels | Meaning |
|---|---|---|---|
pg_up | Gauge | — | Primary-target availability seen by scrapes; see interruption rules below |
pg_version | Gauge | — | Primary target version number |
pg_in_recovery | Gauge | — | 1 on standby, 0 on primary; use when pg_up = 1 |
pg_exporter_build_info | Gauge | version, revision, branch, builddate, goversion, goos, goarch | Constant 1 with build metadata labels |
pg_exporter_up | Gauge | — | Constant 1 |
pg_exporter_uptime | Gauge | — | Seconds since exporter initialization |
pg_exporter_scrape_total_count | Counter | — | Scrape rounds |
pg_exporter_scrape_error_count | Counter | — | Rounds where the primary target had a connection or fatal collector error |
pg_exporter_scrape_duration | Gauge | — | Duration of the last complete scrape round, in seconds |
pg_exporter_last_scrape_time | Gauge | — | Unix timestamp when the last scrape round finished |
pg_exporter_server_scrape_duration | Gauge | datname | Duration of the database’s last scrape round, in seconds |
pg_exporter_server_scrape_total_seconds | Gauge | datname | Cumulative scrape duration for the database, in seconds |
pg_exporter_server_scrape_total_count | Gauge | datname | Scrape rounds for the database |
pg_exporter_server_scrape_error_count | Gauge | datname | Connection or fatal collector errors for the database |
pg_exporter_query_scrape_total_count | Gauge | datname, query | Collector invocations, including cache hits and predicate skips |
pg_exporter_query_scrape_error_count | Gauge | datname, query | Collector invocation errors |
pg_exporter_query_scrape_hit_count | Gauge | datname, query | Result cache hits |
pg_exporter_query_scrape_metric_count | Gauge | datname, query | Samples in the collector’s current result |
pg_exporter_query_scrape_duration | Gauge | datname, query | Duration of the last actual execution, in seconds; unchanged on cache hit |
pg_exporter_query_scrape_predicate_skip_count | Gauge | datname, query | Skips because a predicate returned false, NULL, or zero rows |
pg_exporter_query_cache_ttl | Gauge | datname, query | Remaining result cache lifetime, in seconds |
These series also receive configured constant labels. On pg_exporter_build_info, build values for version, revision, branch, builddate, goversion, goos, and goarch take precedence over user labels. Invalid labels on built-in database/query samples cause a warning and that sample is skipped to avoid a panic. Cumulative database/collector counters are exposed as Gauges. Replanning a server resets collector statistics; configuration reload also triggers replanning. Recreating a database connection object resets that database’s statistics.
--disable-intro suppresses all built-in metrics in this table, including pg_up. YAML metrics, Go/process metrics, and HTTP health endpoints remain available.
On interruption, pg_up preserves the primary target’s previous availability state, or stays 1 if the current precheck already succeeded. If the first precheck is interrupted before succeeding, it remains 0 and recovers on a later successful scrape. Interrupted child databases follow the same per-database rule without incrementing primary-target error counters.
Health Checks
Health endpoints provide multiple ways to monitor PG Exporter and the target database state.
GET /up
After initialization, HTTP health state is updated only by the once-per-second background probe. Slow scrapes do not hold the probe lock or overwrite newer probe results. HTTP health requests read the snapshot without running SQL. pg_up and pg_in_recovery remain scrape metrics: a fatal collector failure can set pg_up to 0 while /up still returns 200 if the database is reachable. Connection pool limits are three for the PostgreSQL main target, two for PgBouncer, and one per discovered database.
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Target is available (primary / replica) |
| 503 | Service Unavailable | Target is unavailable (down / starting / unknown) |
Example
GET /health
Alias of /up with identical behavior.
GET /liveness and GET /readiness
These aliases use the same handler and behavior as /up. Use them for Kubernetes probes:
Both endpoints return 503 when the target database is unreachable. To prevent a database failure from restarting the exporter Pod, use a TCP liveness probe on the listen port.
Traffic Routing
Load balancers and proxies use these endpoints to route traffic by server role.
GET /primary
Check whether the server is a primary instance.
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Server is primary and accepting writes |
| 404 | Not Found | Server is not primary and is acting as a replica |
| 503 | Service Unavailable | Server is unavailable (down / starting / unknown) |
Aliases
/leader/master/read-write/rw
Example
GET /replica
Check whether the server is a replica instance.
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Server is a replica and in recovery |
| 404 | Not Found | Server is not a replica and is acting as primary |
| 503 | Service Unavailable | Server is unavailable (down / starting / unknown) |
Aliases
/standby/read-only/ro
/slave remains compatible, but /replica is the preferred name.
Example
GET /read
Check whether the server can handle read traffic. Both primaries and replicas may return success.
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Server is healthy and can handle reads |
| 503 | Service Unavailable | Server is unavailable (down / starting / unknown) |
Example
Operational Endpoints
GET /reload / POST /reload
Reload configuration without restarting the exporter.
Request
Response
Response Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Reload completed successfully |
| 500 | Internal Server Error | Reload failed and returns fail to reload: ... |
| 405 | Method Not Allowed | Non-GET/POST request, with Allow: GET, POST |
Use Cases
- Update collector definitions
- Change query parameters
- Modify cache TTL values
- Add or remove collectors
Reload updates collector configuration, query plans, caches, and query statistics. A parsing failure preserves the previous plan and caches. Empty YAML is a valid empty configuration; a successful reload clears the collectors. Directory mode permits partial file loading; see Configuration Loading. To change process settings, such as listen addresses or CLI arguments, restart the exporter.
/reload, /explain, and /stat are management endpoints.
If the exporter is reachable outside localhost or a trusted private network, protect these endpoints.
Use --web.config.file, or restrict access through a reverse proxy or firewall.
GET /explain
Display the collectors selected in the primary target’s current plan. Predicates run during refresh and are not evaluated by this endpoint.
Request
Response
GET /stat
Show runtime statistics, including collector execution times and success/error counters.
Request
Response
Use this endpoint to identify slow or failed collectors.
Using with Load Balancers
HAProxy Example
A Note on Nginx
Open-source Nginx does not support active HTTP health checks outside the traffic connection.
The health_check directive requires NGINX Plus.
PostgreSQL traffic also requires the stream module instead of http proxying.
To route PostgreSQL traffic by role, use HAProxy as shown above, or a solution such as Patroni + vip-manager.