This page documents all command-line flags supported by postgres_exporter.
Usage
postgres_exporter [flags]
# Long form with equals
postgres_exporter --web.telemetry-path=/custom-metrics
# Long form with space
postgres_exporter --web.telemetry-path /custom-metrics
# Using environment variables (for supported flags)
PG_EXPORTER_WEB_TELEMETRY_PATH=/custom-metrics postgres_exporter
Flag Categories
Configuration File
| Flag | Type | Default | Env Variable | Description |
|---|
--config.file | string | postgres_exporter.yml | - | Path to the configuration file for auth modules |
Web Server
| Flag | Type | Default | Env Variable | Description |
|---|
--web.listen-address | string | :9187 | - | Address to listen on for web interface and telemetry |
--web.telemetry-path | string | /metrics | PG_EXPORTER_WEB_TELEMETRY_PATH | Path under which to expose metrics |
--web.config.file | string | - | - | Path to TLS and/or basic authentication configuration file. See exporter-toolkit docs |
--web.systemd-socket | boolean | false | - | Use systemd socket activation listeners instead of port listeners (Linux only) |
Metrics Configuration
| Flag | Type | Default | Env Variable | Description |
|---|
--disable-default-metrics | boolean | false | PG_EXPORTER_DISABLE_DEFAULT_METRICS | Only use metrics from custom queries. Disables all built-in collectors |
--disable-settings-metrics | boolean | false | PG_EXPORTER_DISABLE_SETTINGS_METRICS | Do not scrape pg_settings metrics |
--metric-prefix | string | pg | PG_EXPORTER_METRIC_PREFIX | Prefix for all metrics (default is pg_) |
Collection Settings
| Flag | Type | Default | Env Variable | Description |
|---|
--collection-timeout | duration | 1m | PG_EXPORTER_COLLECTION_TIMEOUT | Timeout for collecting statistics when the database is slow. Minimum value is 1ms |
Deprecated Flags
The following flags are deprecated and will be removed in a future release. They are maintained for backward compatibility only.
| Flag | Type | Default | Env Variable | Description | Replacement |
|---|
--auto-discover-databases | boolean | false | PG_EXPORTER_AUTO_DISCOVER_DATABASES | Dynamically discover databases on the server | Use multi-target pattern instead |
--exclude-databases | string | "" | PG_EXPORTER_EXCLUDE_DATABASES | Comma-separated list of databases to exclude when auto-discovery is enabled | Use multi-target pattern instead |
--include-databases | string | "" | PG_EXPORTER_INCLUDE_DATABASES | Comma-separated list of databases to include when auto-discovery is enabled | Use multi-target pattern instead |
--extend.query-path | string | "" | PG_EXPORTER_EXTEND_QUERY_PATH | Path to custom queries YAML file | Use built-in collectors or sql_exporter |
--constantLabels | string | "" | PG_EXPORTER_CONSTANT_LABELS | Comma-separated list of label=value pairs to add to all metrics | Use relabeling in Prometheus |
Utility Flags
| Flag | Type | Default | Description |
|---|
--dumpmaps | boolean | false | Print the internal metric maps and exit without running the exporter |
--version | boolean | false | Print version information and exit |
--help, -h | boolean | false | Show help information |
Logging
These flags are provided by the Prometheus common library:
| Flag | Type | Default | Description |
|---|
--log.level | string | info | Log level: debug, info, warn, error |
--log.format | string | logfmt | Log format: logfmt, json |
Collector Flags
Each collector can be individually enabled or disabled using boolean flags. The format is --collector.<name> or --no-collector.<name>.
Enabled by Default
| Flag | Description |
|---|
--[no-]collector.database | PostgreSQL databases statistics from pg_database |
--[no-]collector.locks | Lock statistics from pg_locks |
--[no-]collector.replication | Replication statistics from pg_stat_replication |
--[no-]collector.replication_slot | Replication slot statistics from pg_replication_slots |
--[no-]collector.roles | Role statistics from pg_roles |
--[no-]collector.stat_bgwriter | Background writer statistics from pg_stat_bgwriter |
--[no-]collector.stat_database | Database statistics from pg_stat_database |
--[no-]collector.stat_progress_vacuum | Vacuum progress from pg_stat_progress_vacuum (PG 13+) |
--[no-]collector.stat_user_tables | User table statistics from pg_stat_user_tables |
--[no-]collector.statio_user_tables | User table I/O statistics from pg_statio_user_tables |
--[no-]collector.wal | WAL statistics from pg_wal or pg_xlog |
Disabled by Default
| Flag | Description |
|---|
--[no-]collector.database_wraparound | Transaction ID wraparound monitoring from pg_database |
--[no-]collector.long_running_transactions | Long-running transaction detection |
--[no-]collector.postmaster | Postmaster process uptime |
--[no-]collector.process_idle | Idle process statistics |
--[no-]collector.stat_activity_autovacuum | Autovacuum activity from pg_stat_activity |
--[no-]collector.stat_checkpointer | Checkpointer statistics from pg_stat_checkpointer (PG 17+) |
--[no-]collector.stat_statements | Query statistics from pg_stat_statements extension |
--[no-]collector.stat_wal_receiver | WAL receiver statistics from pg_stat_wal_receiver |
--[no-]collector.statio_user_indexes | User index I/O statistics from pg_statio_user_indexes |
--[no-]collector.xlog_location | Transaction log location (deprecated, use wal collector) |
--[no-]collector.buffercache_summary | Buffer cache summary from pg_buffercache extension |
Why some collectors are disabled by default:
- High cardinality:
stat_statements creates one time series per unique query
- Performance overhead: Some collectors require expensive queries
- Extension required:
buffercache_summary requires pg_buffercache extension
- Specific use cases:
postmaster, process_idle are useful in specific scenarios
pg_stat_statements Flags
When the stat_statements collector is enabled, additional flags control its behavior:
| Flag | Type | Default | Description |
|---|
--collector.stat_statements.include_query | boolean | false | Include the full query text in metrics (increases cardinality) |
--collector.stat_statements.query_length | uint | 120 | Maximum length of query text to include |
--collector.stat_statements.limit | uint | 100 | Maximum number of statements to return per scrape |
--collector.stat_statements.exclude_databases | string | "" | Comma-separated list of databases to exclude from statement metrics |
--collector.stat_statements.exclude_users | string | "" | Comma-separated list of users to exclude from statement metrics |
Enabling pg_stat_statements with include_query can create extremely high cardinality. Use limit and exclude_* flags to control the number of time series created.
Examples
Basic Usage
# Use default settings
postgres_exporter
Custom Web Configuration
# Custom port and metrics path
postgres_exporter \
--web.listen-address=:9188 \
--web.telemetry-path=/custom-metrics
Enable Additional Collectors
# Enable commonly useful collectors
postgres_exporter \
--collector.database_wraparound \
--collector.long_running_transactions \
--collector.postmaster
Disable Default Collectors
# Disable noisy collectors
postgres_exporter \
--no-collector.stat_user_tables \
--no-collector.statio_user_tables
Enable pg_stat_statements
# Enable with safety limits
postgres_exporter \
--collector.stat_statements \
--collector.stat_statements.limit=50 \
--collector.stat_statements.query_length=80 \
--collector.stat_statements.exclude_databases=postgres,template0,template1
Production Configuration
# Full production setup
postgres_exporter \
--config.file=/etc/postgres_exporter/config.yml \
--web.listen-address=:9187 \
--web.config.file=/etc/postgres_exporter/web-config.yml \
--collection-timeout=30s \
--log.level=info \
--log.format=json \
--collector.database_wraparound \
--collector.long_running_transactions \
--no-collector.stat_user_tables
Debug Mode
# Enable debug logging
postgres_exporter \
--log.level=debug \
--log.format=logfmt
Dump Internal Metrics
# View metric definitions without running
postgres_exporter --dumpmaps
Flag Precedence
When the same configuration is specified in multiple ways, the precedence is:
- Command-line flags (highest priority)
- Environment variables (see [Environment Variables(../reference/environment-variables))
- Configuration file (for auth modules only)
- Default values (lowest priority)
Example:
# Environment variable sets path to /metrics
export PG_EXPORTER_WEB_TELEMETRY_PATH=/metrics
# Flag overrides environment variable
postgres_exporter --web.telemetry-path=/custom
# Result: metrics exposed at /custom
Boolean Flag Syntax
Boolean flags support multiple syntaxes:
# Enable a collector
postgres_exporter --collector.stat_statements
postgres_exporter --collector.stat_statements=true
# Disable a collector
postgres_exporter --no-collector.stat_statements
postgres_exporter --collector.stat_statements=false
Getting Help
# Show all flags with descriptions
postgres_exporter --help
# Show detailed help
postgres_exporter --help-long
# Show man-page style help
postgres_exporter --help-man
See Also
- [Configuration File(../reference/configuration-file) - YAML configuration reference
- [Environment Variables(../reference/environment-variables) - Environment variable reference
- [Collectors(../guides/collectors) - Detailed collector documentation