Command-Line Flags

The PostgreSQL Server Exporter accepts various command-line flags to control its behavior. Flags take precedence over environment variables.

Usage

postgres_exporter [flags]

View all available flags:

postgres_exporter --help

General Flags

--help

flag

Show context-sensitive help. Also try --help-long and --help-man for detailed documentation.Short: -h

--version

flag

Show application version and build information.

--dumpmaps

flag

Print the internal representation of metric maps and exit. Useful for debugging custom queries. Does not start the exporter.

Configuration File

--config.file

string

default:"postgres_exporter.yml"

Path to the YAML configuration file containing auth modules and other settings.Example: --config.file=/etc/postgres_exporter/config.yml

Web Server Flags

--web.listen-address

string

default:":9187"

Address and port to listen on for HTTP requests. Format: host:port or :portExamples:

--web.listen-address=":9187" - Listen on all interfaces, port 9187
--web.listen-address="127.0.0.1:9187" - Listen only on localhost
--web.listen-address="0.0.0.0:8080" - Listen on all interfaces, port 8080

--web.telemetry-path

string

default:"/metrics"

HTTP path where metrics are exposed.Environment Variable: PG_EXPORTER_WEB_TELEMETRY_PATHExample: --web.telemetry-path="/custom/metrics"

--web.config.file

string

Path to configuration file for TLS and/or basic authentication. See exporter-toolkit documentation for format details.Example: --web.config.file=/etc/postgres_exporter/web-config.yml

--web.systemd-socket

boolean

default:"false"

Use systemd socket activation listeners instead of port listeners. Linux only.Example: --web.systemd-socket

Metrics Collection Flags

--disable-default-metrics

boolean

default:"false"

Disable all built-in metrics. When enabled, only metrics from --extend.query-path are exported. Useful for monitoring non-standard PostgreSQL variants.Environment Variable: PG_EXPORTER_DISABLE_DEFAULT_METRICSExample: --disable-default-metrics

--disable-settings-metrics

boolean

default:"false"

Disable scraping of pg_settings metrics.Environment Variable: PG_EXPORTER_DISABLE_SETTINGS_METRICSExample: --disable-settings-metrics

--metric-prefix

string

default:"pg"

Prefix for all exported metrics. Change to avoid conflicts when running multiple exporters.Environment Variable: PG_EXPORTER_METRIC_PREFIXExample: --metric-prefix=postgresResults in metrics like postgres_up, postgres_stat_database_*, etc.

--collection-timeout

duration

default:"1m"

Timeout for collecting statistics from PostgreSQL. Prevents connection pool exhaustion when queries are slow. Must be > 1ms.Environment Variable: PG_EXPORTER_COLLECTION_TIMEOUTExamples: 30s, 2m, 500ms

Collector Flags

Collectors can be individually enabled or disabled. Use [no-] prefix to explicitly disable.

Database Collectors

--[no-]collector.database

boolean

default:"enabled"

Enable the database collector. Exports pg_database metrics including database size and statistics.

--[no-]collector.database_wraparound

boolean

default:"disabled"

Enable the database wraparound collector. Monitors transaction ID wraparound risk.

Lock Collectors

--[no-]collector.locks

boolean

default:"enabled"

Enable the locks collector. Exports lock wait statistics.

Transaction Collectors

--[no-]collector.long_running_transactions

boolean

default:"disabled"

Enable the long running transactions collector. Identifies transactions exceeding a threshold.

Process Collectors

--[no-]collector.postmaster

boolean

default:"disabled"

Enable the postmaster collector. Exports postmaster process information.

--[no-]collector.process_idle

boolean

default:"disabled"

Enable the process idle collector. Monitors idle connections.

Replication Collectors

--[no-]collector.replication

boolean

default:"enabled"

Enable the replication collector. Monitors streaming replication status.

--[no-]collector.replication_slot

boolean

default:"enabled"

Enable the replication slot collector. Monitors replication slot lag.

Statistics Collectors

--[no-]collector.stat_activity_autovacuum

boolean

default:"disabled"

Enable the stat activity autovacuum collector. Monitors autovacuum processes.

--[no-]collector.stat_bgwriter

boolean

default:"enabled"

Enable the stat bgwriter collector. Exports background writer statistics.

--[no-]collector.stat_checkpointer

boolean

default:"disabled"

Enable the stat checkpointer collector (PostgreSQL 17+). Exports checkpoint statistics.

--[no-]collector.stat_database

boolean

default:"enabled"

Enable the stat database collector. Exports pg_stat_database metrics.

--[no-]collector.stat_progress_vacuum

boolean

default:"enabled"

Enable the stat progress vacuum collector. Monitors vacuum progress.

--[no-]collector.stat_user_tables

boolean

default:"enabled"

Enable the stat user tables collector. Exports pg_stat_user_tables metrics.

--[no-]collector.stat_wal_receiver

boolean

default:"disabled"

Enable the stat WAL receiver collector. Monitors WAL receiver on replicas.

--[no-]collector.statio_user_indexes

boolean

default:"disabled"

Enable the statio user indexes collector. Exports I/O statistics for indexes.

--[no-]collector.statio_user_tables

boolean

default:"enabled"

Enable the statio user tables collector. Exports I/O statistics for tables.

WAL Collectors

--[no-]collector.wal

boolean

default:"enabled"

Enable the WAL collector. Monitors write-ahead log statistics.

--[no-]collector.xlog_location

boolean

default:"disabled"

Enable the xlog location collector (older PostgreSQL versions). Monitors WAL position.

pg_stat_statements Collector

--[no-]collector.stat_statements

boolean

default:"disabled"

Enable the stat statements collector. Requires pg_stat_statements extension. Exports query execution statistics.

--[no-]collector.stat_statements.include_query

boolean

default:"disabled"

Include the full query text with queryid in pg_stat_statements metrics.

May expose sensitive data in metrics. Use with caution.

--collector.stat_statements.query_length

integer

default:"120"

Maximum length of statement text to include in metrics (when include_query is enabled).Example: --collector.stat_statements.query_length=200

--collector.stat_statements.limit

integer

default:"100"

Maximum number of statements to return from pg_stat_statements.Example: --collector.stat_statements.limit=500

--collector.stat_statements.exclude_databases

string

Comma-separated list of database names to exclude from pg_stat_statements metrics.Example: --collector.stat_statements.exclude_databases=template0,template1

--collector.stat_statements.exclude_users

string

Comma-separated list of user names to exclude from pg_stat_statements metrics.Example: --collector.stat_statements.exclude_users=postgres,admin

Deprecated Flags

The following flags are deprecated and will be removed in a future release.

--auto-discover-databases

boolean

default:"false"

DEPRECATED: Automatically discover and monitor all databases on the server.Environment Variable: PG_EXPORTER_AUTO_DISCOVER_DATABASESReplacement: Use Prometheus service discovery instead

--exclude-databases

string

default:""

DEPRECATED: Comma-separated list of databases to exclude when --auto-discover-databases is enabled.Environment Variable: PG_EXPORTER_EXCLUDE_DATABASES

--include-databases

string

default:""

DEPRECATED: Comma-separated list of databases to exclusively monitor when --auto-discover-databases is enabled.Environment Variable: PG_EXPORTER_INCLUDE_DATABASES

--extend.query-path

string

default:""

DEPRECATED: Path to YAML file containing custom queries.Environment Variable: PG_EXPORTER_EXTEND_QUERY_PATHReplacement: Use built-in collectors or sql_exporter

--constantLabels

string

default:""

DEPRECATED: Comma-separated list of label=value pairs to add to all metrics.Environment Variable: PG_EXPORTER_CONSTANT_LABELSExample: --constantLabels=environment=prod,region=us-east

Logging Flags

--log.level

string

default:"info"

Set logging verbosity level.Options: debug, info, warn, errorExample: --log.level=debug

--log.format

string

default:"logfmt"

Set the log output format.Options: logfmt, jsonExample: --log.format=json

Configuration Examples

postgres_exporter \
  --web.listen-address=":9187" \
  --web.telemetry-path="/metrics" \
  --log.level=info

# Enable only essential collectors
postgres_exporter \
  --collector.database \
  --collector.stat_database \
  --no-collector.locks \
  --no-collector.replication \
  --no-collector.replication_slot \
  --no-collector.stat_bgwriter \
  --no-collector.stat_user_tables \
  --no-collector.statio_user_tables \
  --no-collector.wal

# Monitor query performance with pg_stat_statements
postgres_exporter \
  --collector.stat_statements \
  --collector.stat_statements.limit=500 \
  --collector.stat_statements.query_length=200 \
  --collector.stat_statements.exclude_databases=template0,template1

# Focus on replication health
postgres_exporter \
  --collector.replication \
  --collector.replication_slot \
  --collector.stat_wal_receiver \
  --collector.wal \
  --collection-timeout=30s

# With TLS and basic auth
postgres_exporter \
  --web.listen-address=":9187" \
  --web.config.file=/etc/postgres_exporter/web-config.yml \
  --config.file=/etc/postgres_exporter/config.yml \
  --log.level=warn \
  --log.format=json

web-config.yml:

tls_server_config:
  cert_file: /etc/certs/server.crt
  key_file: /etc/certs/server.key
basic_auth_users:
  prometheus: $2y$10$...

# Avoid conflicts with custom prefix
postgres_exporter \
  --metric-prefix=pgsql \
  --web.telemetry-path="/postgres-metrics"

# Metrics will be named:
# pgsql_up
# pgsql_stat_database_*
# etc.

Combining with Environment Variables

Flags override environment variables:

# Set defaults via environment
export PG_EXPORTER_WEB_TELEMETRY_PATH="/metrics"
export PG_EXPORTER_DISABLE_SETTINGS_METRICS="true"

# Override with flags
postgres_exporter \
  --web.telemetry-path="/custom" \
  --disable-settings-metrics=false

# Result: /custom endpoint with settings metrics enabled

Checking Current Configuration

View the active configuration by checking the landing page:

curl http://localhost:9187/

Or inspect logs on startup:

level=info msg="Starting postgres_exporter" version=...
level=info msg="Listening on" address=:9187
level=info msg="TLS is disabled" http2=false

Get Started

Configuration

Deployment

Collectors

Advanced

Usage

General Flags

Configuration File

Web Server Flags

Metrics Collection Flags

Collector Flags

Database Collectors

Lock Collectors

Transaction Collectors

Process Collectors

Replication Collectors

Statistics Collectors

WAL Collectors

pg_stat_statements Collector

Deprecated Flags

Logging Flags

Configuration Examples

Combining with Environment Variables

Checking Current Configuration

Next Steps

Environment Variables

Collectors Reference

Build docs developers (and LLMs) love

Get Started

Configuration

Deployment

Collectors

Advanced

​Usage

​General Flags

​Configuration File

​Web Server Flags

​Metrics Collection Flags

​Collector Flags

​Database Collectors

​Lock Collectors

​Transaction Collectors

​Process Collectors

​Replication Collectors

​Statistics Collectors

​WAL Collectors

​pg_stat_statements Collector

​Deprecated Flags

​Logging Flags

​Configuration Examples

​Combining with Environment Variables

​Checking Current Configuration

​Next Steps

Environment Variables

Collectors Reference

Build docs developers (and LLMs) love

Usage

General Flags

Configuration File

Web Server Flags

Metrics Collection Flags

Collector Flags

Database Collectors

Lock Collectors

Transaction Collectors

Process Collectors

Replication Collectors

Statistics Collectors

WAL Collectors

pg_stat_statements Collector

Deprecated Flags

Logging Flags

Configuration Examples

Combining with Environment Variables

Checking Current Configuration

Next Steps