PostgreSQL Server Exporter

To run the project's tests, you can use make test for unit tests. For integration tests, you must first start a test database using Docker and then run the test command with the appropriate DATA_SOURCE_NAME and GOOPTS environment variables.

# Run the unit tests
make test

# Start the test database with docker
docker run -p 5432:5432 -e POSTGRES_DB=circle_test -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=test -d postgres

# Run the integration tests
DATA_SOURCE_NAME='postgresql://postgres:test@localhost:5432/circle_test?sslmode=disable' GOOPTS='-v -tags integration' make test

To enable necessary extensions for metrics collection (like pg_stat_statements) on Amazon RDS, you must update your RDS Parameter Group with the following setting and then reboot the RDS instance:

shared_preload_libraries = "pg_stat_statements,pg_hint_plan"

If you are using non-officially-supported PostgreSQL versions (e.g., 8.2.15) or variants (e.g., Greenplum), you can disable all built-in metrics using the --disable-default-metrics flag.

Note: When using this flag, you must provide a custom queries file via the --extend.query-path flag, otherwise the exporter will only return internal status metrics and no database metrics.

When using postgres_exporter with Amazon Web Services' RDS, you must exclude the rdsadmin role and database to avoid errors.

Specifically:

1. Set the environment variable PG_EXPORTER_EXCLUDE_DATABASES=rdsadmin.
2. If using custom queries that reference roles (such as pg_stat_statements), ensure you add a filter to exclude the RDS admin role: WHERE t2.rolname != 'rdsadmin'.
3. It is recommended to disable default metrics using PG_EXPORTER_DISABLE_DEFAULT_METRICS=true and use --no-collector.settings to avoid conflicts with RDS-specific restrictions.

The multi-target pattern allows a single exporter instance to scrape multiple PostgreSQL targets. This is useful for SaaS-managed services where sidecar deployment is not possible.

Usage

Send an HTTP request to the /probe endpoint. The target parameter must be set to the DSN of the PostgreSQL instance you wish to scrape.

Example URL: /probe?target=foo:5432

To avoid passing sensitive credentials in the URL, use auth_modules defined in the configuration file and specify them via the auth_module parameter in the request (e.g., /probe?target=foo:5432&auth_module=my_module).

You can build the exporter from source using make or build a Docker image.

Build from source:

1. Clone the repository.
2. Run make build.
3. Execute the binary with desired flags: ./postgres_exporter <flags>.

Build Docker image: Use the following commands to build a multi-platform Docker image (e.g., prometheuscommunity/postgres_exporter:${branch}):

make promu
promu crossbuild -p linux/amd64 -p linux/armv7 -p linux/arm64 -p linux/ppc64le
make docker

git clone https://github.com/prometheus-community/postgres_exporter.git
cd postgres_exporter
make build
./postgres_exporter <flags>

To collect metrics from pg_stat* views as a non-superuser, you must grant appropriate permissions in PostgreSQL.

For PostgreSQL versions >= 10: Grant the built-in pg_monitor or pg_read_all_stats role to the exporter user:

GRANT pg_monitor to postgres_exporter;

For PostgreSQL versions < 10: You must create functions and views as a superuser using SECURITY DEFINER to allow the non-superuser to access the data. This involves creating a schema, specific functions for views like pg_stat_activity and pg_stat_replication, and granting SELECT permissions on those views to the exporter user.

The exporter requires a connection string to the PostgreSQL server, which must be provided via the DATA_SOURCE_NAME environment variable.

Single instance (URI format): DATA_SOURCE_NAME="postgresql://user:password@localhost:5432/postgres?sslmode=disable"

Single instance (Key=Value format): DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable"

Multiple instances: You can provide a comma-separated list of connection parameters to scrape different instances from a single exporter setup: DATA_SOURCE_NAME="port=5432,port=6432"

sudo -u postgres DATA_SOURCE_NAME="user=postgres host=/var/run/postgresql/ sslmode=disable" postgres_exporter

The configuration file (set via --config.file, defaults to postgres_exporter.yml) allows you to define auth_modules. These modules provide preset authentication and connection parameters for the /probe endpoint.

auth_modules is a map where the key is the module identifier. Currently, only the userpass type is supported. The options field allows you to pass key-value pairs that become parameters of the DSN (e.g., sslmode).

auth_modules:
  foo1: # Set this to any name you want
    type: userpass
    userpass:
      username: first
      password: firstpass
    options:
      # options become key=value parameters of the DSN
      sslmode: disable

The probe mode allows the exporter to act as a multi-target scraper. Instead of scraping a single static database, you can send an HTTP request to the exporter's endpoint specifying a target (the connection string or host) via query parameters. This is useful for Prometheus Blackbox-style monitoring where you want to probe multiple PostgreSQL instances through a single exporter instance.

To use this mode, you must provide the target parameter in the URL. You can optionally provide an auth_module parameter to use a pre-configured authentication module from your configuration file.