Skip to main content
PostgreSQL Exporter

​
Overview

PostgreSQL Server Exporter is a Prometheus exporter that exposes comprehensive metrics from PostgreSQL database servers. It provides deep visibility into database performance, replication status, query statistics, and operational health metrics. Built and maintained by the Prometheus Community, this exporter is production-ready and widely deployed for monitoring PostgreSQL infrastructure at scale.

​
Why PostgreSQL Server Exporter?

PostgreSQL Server Exporter solves critical challenges in database observability:

Comprehensive Metrics

Exposes 20+ built-in collectors covering database statistics, replication lag, locks, WAL activity, and query performance

Production-Ready

Battle-tested across thousands of deployments with support for PostgreSQL versions 13-18

Multi-Target Support

Monitor multiple PostgreSQL instances from a single exporter using the multi-target pattern

Flexible Deployment

Deploy as Docker container, binary, sidecar, or centralized service with configurable authentication

​
Key Features

​
Built-in Collectors

The exporter includes comprehensive collectors that are enabled by default:
  • Database Statistics: Transactions, block reads/writes, deadlocks, conflicts
  • Replication Monitoring: Replication lag in bytes, slot status, WAL sender state
  • Lock Analysis: Lock types, counts, and wait states
  • Table Statistics: Sequential scans, index usage, vacuum/analyze status
  • WAL Activity: Write-ahead log generation rate and location
  • Background Writer: Checkpoint statistics and buffer allocation
  • Query Performance: pg_stat_statements integration for top queries (optional)

​
Optional Collectors

Enable additional collectors for specific monitoring needs:
  • database_wraparound: Transaction ID wraparound monitoring
  • long_running_transactions: Detect queries running beyond thresholds
  • stat_activity_autovacuum: Autovacuum progress tracking
  • stat_checkpointer: Checkpoint timing and I/O statistics
  • stat_statements: Top queries by execution time and frequency
  • process_idle: Idle connection tracking
  • postmaster: PostgreSQL server process information

​
Multi-Target Pattern (Beta)

Monitor multiple PostgreSQL servers from a single exporter instance: 
scrape_configs:
  - job_name: 'postgres'
    static_configs:
      - targets:
        - server1:5432
        - server2:5432
    metrics_path: /probe
    params:
      auth_module: [production]
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: postgres-exporter:9187

​
Secure Authentication

Multiple authentication methods protect sensitive credentials:
  • Environment variables (DATA_SOURCE_URI, DATA_SOURCE_USER, DATA_SOURCE_PASS)
  • File-based secrets (DATA_SOURCE_PASS_FILE, DATA_SOURCE_USER_FILE)
  • Configuration file with reusable auth modules
  • Support for all PostgreSQL connection parameters (SSL, timeouts, etc.)

​
Non-Superuser Support

Run with minimal privileges using PostgreSQL’s built-in monitoring roles: 
-- PostgreSQL 10+
GRANT pg_monitor TO postgres_exporter;

-- PostgreSQL 9.x requires custom functions
CREATE SCHEMA postgres_exporter;
GRANT USAGE ON SCHEMA postgres_exporter TO postgres_exporter;

​
Supported PostgreSQL Versions

The exporter is CI-tested against PostgreSQL versions 13, 14, 15, 16, 17, and 18.PostgreSQL 9.1+ is supported with reduced functionality. Some collectors require newer versions.

​
Architecture

The exporter connects directly to PostgreSQL using the standard lib/pq driver: The exporter:
  1. Receives scrape requests from Prometheus on port 9187
  2. Executes SQL queries against PostgreSQL system catalogs and statistics views
  3. Transforms results into Prometheus metrics format
  4. Caches connections between scrapes for efficiency
  5. Supports version-specific query optimization

​
Metrics Endpoint

The exporter exposes metrics on port 9187 by default:
  • /metrics: Primary metrics endpoint (configurable path)
  • /probe: Multi-target probe endpoint for monitoring multiple servers
  • /: Landing page with version info and links
curl http://localhost:9187/metrics

​
Performance Characteristics

Collection Timeout

Default 1-minute timeout prevents hung queries from blocking scrapes

Connection Pooling

Reuses database connections between scrapes for low overhead

Selective Collectors

Enable only needed collectors to minimize database load

Version Optimization

Automatically uses optimal queries based on PostgreSQL version

​
Get Started

Quick Start

Get the exporter running in minutes with Docker

Installation Guide

Detailed installation methods for all deployment scenarios

Configuration Reference

Complete guide to collectors, flags, and environment variables

Multi-Target Setup

Configure centralized monitoring for multiple PostgreSQL servers

​
Use Cases

​
Database Performance Monitoring

Track query throughput, cache hit ratios, and transaction rates to optimize database performance.

​
Replication Lag Alerting

Monitor replication lag in bytes (pg_wal_lsn_diff) to detect and prevent replica drift.

​
Capacity Planning

Analyze connection counts, disk I/O patterns, and table growth trends for infrastructure planning.

​
Incident Response

Investigate lock contention, long-running transactions, and autovacuum issues during outages.

​
Community & Support

GitHub Repository

Report issues, contribute code, or view the source

Docker Hub

Official Docker images published by the Prometheus Community
Next Steps: Follow the Quick Start guide to deploy your first exporter instance in under 5 minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us