PostgreSQL metrics
PostgreSQL Metrics Source
The PostgreSQL Metrics source collects operational and performance metrics from PostgreSQL database instances by periodically scraping internal statistics views. It provides visibility into database health, activity, and resource usage, and emits metrics in a format suitable for centralized monitoring and alerting systems.
This source operates in stateless mode, runs as a daemon or sidecar, and delivers metrics in batch mode with at-least-once delivery semantics. Source-level acknowledgements are not supported.
Connection Settings
endpoints (required, [string])
Defines the list of PostgreSQL instances to scrape for metrics.
- Each entry must be a valid PostgreSQL connection URI.
- Multiple endpoints can be configured to collect metrics from multiple database instances.
Operational note: Ensure that the configured user has sufficient privileges to access PostgreSQL system catalog and statistics views required for metric collection.
Database Selection
include_databases (optional, [string])
Specifies which databases to include when collecting metrics.
- Each entry is evaluated as a POSIX regular expression against the datname column.
- If not configured, metrics are collected from all databases.
- An empty string ("") matches rows where datname is NULL.
Operational note: Use this setting to limit metric collection to critical databases in environments with many tenants or schemas.
exclude_databases (optional, [string])
Specifies which databases to exclude from metric collection.
- Each entry is evaluated as a POSIX regular expression against the datname column.
- An empty string ("") matches rows where datname is NULL.
Operational note: This setting can be combined with include_databases to precisely control which databases are monitored and to reduce metric volume.
Metric Namespacing
namespace (optional, string)
Overrides the default namespace applied to emitted metrics.
- Used as a prefix to identify the metric source.
- Helps distinguish PostgreSQL metrics from other database or infrastructure metrics.
Default: postgresql
Operational note: Custom namespaces are recommended in multi-cluster or multi-environment deployments to avoid naming collisions.
Scraping Behavior
scrape_interval_secs (optional, uint)
Defines how frequently metrics are collected from PostgreSQL instances.
- Shorter intervals provide higher resolution data.
- Longer intervals reduce database load and network traffic.
Default: 15 seconds.
Operational note: In high-load database environments, increasing the scrape interval can reduce overhead caused by frequent statistics queries.
TLS Configuration
tls (optional, object)
Configures TLS behavior when establishing connections to PostgreSQL instances.
tls.ca_file (required when TLS is used, string)
Path to an additional trusted CA certificate file.
- Used to validate the PostgreSQL server certificate.
- Supported formats include DER and PEM (X.509).
Security note: Using a trusted CA is strongly recommended when connecting to remote or production-grade PostgreSQL instances.
Operational Considerations
- Metric collection relies on PostgreSQL internal statistics, which may reset on database restart.
- High cardinality environments may generate a large volume of metrics; database filtering and scrape interval tuning are recommended.
- TLS should be enabled for all non-local PostgreSQL connections to protect credentials and metric data in transit.