---
title: PostgreSQL metrics
slug: telemetry-pipeline/postgresql-metrics
docTags: 
createdAt: 2025-04-21T00:54:27.100Z
---

## 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.