Postgresql Receiver

Available in: contrib Maintainers: @antonblock, @ishleenk17, @Caleb-Hurshman, @ebrdarSplunk, @XSAM, @akshays-19, @sv-splunk, @splunk-shanu Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Prerequisites

See PostgreSQL documentation for supported versions. The monitoring user must be granted SELECT on pg_stat_database.

[!NOTE] The feature gate receiver.postgresql.separateSchemaAttr addresses an inconsistency in how schema names are reported across different metric types. When enabled, schema names are consistently reported in a dedicated postgresql.schema.name resource attribute. Status: Alpha (disabled by default) When disabled (default behavior):

Table metrics: postgresql.table.name = "schema_name.table_name" (schema included)

Index metrics: postgresql.table.name = "table_name" (schema missing)

Function metrics: Schema reported separately in some cases

When enabled (recommended for consistency):

All metrics consistently use:

postgresql.schema.name = "schema_name"

postgresql.table.name = "table_name"

This ensures reliable correlation of metrics when tables with identical names exist across different schemas. To enable:
otelcol-contrib --feature-gates=receiver.postgresql.separateSchemaAttr
Note: This gate is mutually exclusive with receiver.postgresql.useOTelSemconv. Both cannot be enabled at the same time. See https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/29559 for more details.

Configuration

The following setting is required to create a database connection:

username

Exactly one of the following credential settings is also required:

password: A static PostgreSQL password.
db_auth: The component ID of a database authentication provider extension. The provider supplies the password, and can optionally override username, whenever the receiver opens a connection. db_auth and password are mutually exclusive.

For example, a provider extension must be declared, referenced from the receiver, and enabled in service.extensions:

extensions:
  aws_iam_db_auth:
    region: us-east-2

receivers:
  postgresql:
    endpoint: my-database.example.com:5432
    username: monitor
    db_auth: aws_iam_db_auth

service:
  extensions: [aws_iam_db_auth]
  pipelines:
    metrics:
      receivers: [postgresql]

The selected provider extension must be included in the Collector distribution. Provider-wide settings, such as the region above, belong to the extension; endpoint and username are passed to it by the receiver for each credential request. The following settings are optional:

endpoint (default = localhost:5432): The endpoint of the PostgreSQL server. Whether using TCP or Unix sockets, this value should be host:port. If transport is set to unix, the endpoint will internally be translated from host:port to /host.s.PGSQL.port
transport (default = tcp): The transport protocol being used to connect to PostgreSQL. Available options are tcp and unix.
databases (default = []): The list of databases for which the receiver will attempt to collect statistics. If an empty list is provided, the receiver will attempt to collect statistics for all non-template databases.
exclude_databases (default = []): List of databases which will be excluded when collecting statistics.

The following settings are also optional and nested under tls to help configure client transport security

insecure (default = false): Whether to enable client transport security for the PostgreSQL connection.
insecure_skip_verify (default = true): Whether to validate server name and certificate if client transport security is enabled.
cert_file (default = $HOME/.postgresql/postgresql.crt): A certificate used for client authentication, if necessary.
key_file (default = $HOME/.postgresql/postgresql.key): An SSL key used for client authentication, if necessary.
ca_file (default = ""): A set of certificate authorities used to validate the database server’s SSL certificate.
collection_interval (default = 10s): This receiver collects metrics on an interval. This value must be a string readable by Golang’s time.ParseDuration. Valid time units are ns, us (or µs), ms, s, m, h.
initial_delay (default = 1s): defines how long this receiver waits before starting.

Query Sample Collection

We provide functionality to collect the query sample from PostgreSQL. It will get historical query from pg_stat_activity. To enable it, you will need the following configuration

...
    events:
      db.server.query_sample:
        enabled: true
...

By default, query sample collection is disabled, also note, to use it, you will need to grant the user you are using pg_monitor. Take the example from testdata/integration/init.sql

GRANT pg_monitor TO otelu;

To correlate query samples with traces, set the PostgreSQL application_name for the client connection to a valid W3C traceparent value before running the query:

SET application_name = '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01';

When query sample collection observes a valid traceparent in application_name, the receiver sets the trace ID and span ID on the emitted db.server.query_sample log record. This enables correlation between the query sample and the originating trace. The following options are available:

max_rows_per_query: (optional, default=1000) The max number of rows would return from the query against pg_stat_activity.

Top Query Collection

We provide functionality to collect the most executed queries from PostgreSQL. It will get data from pg_stat_statements and report incremental value of total_exec_time, total_plan_time, calls, rows, shared_blks_dirtied, shared_blks_hit, shared_blks_read, shared_blks_written, temp_blks_read, temp_blks_written. To enable it, you will need the following configuration

...
    events:
      db.server.top_query:
        enabled: true
...

Along with those attributes, we will also report the query plan we gathered if it is possible. By default, top query collection is disabled, also note, to use it, you will need to create the extension to every database. Take the example from testdata/integration/02-create-extension.sh

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

The following options are available:

max_rows_per_query: (optional, default=1000) The max number of rows would return from the query against pg_stat_statements.
top_n_query: (optional, default=200) The maximum number of active queries to report (to the next consumer) in a single run.
max_explain_each_interval: (optional, default=1000). The maximum number of explain query to be sent in each scrape interval. The top query collection would not get the query plan directly. Instead, we need to mimic the query in the database and get the query plan from database separately. This could lead some resources usage and limit this will reduce the impact on your database.
query_plan_cache_size: (optional, default=1000). The query plan cache size. Once we got explain for one query, we will store it in the cache. This defines the cache’s size for query plan.
query_plan_cache_ttl: (optional, default=1h). How long before the query plan cache got expired. Example values: 1m, 1h.
collection_interval: (optional, default=60s). This receiver can collect top_query metrics on an interval. If not provided then the global collection_interval takes effect. This value must be a string readable by Golang’s time.ParseDuration. Valid time units are ns, us (or µs), ms, s, m, h.

Vector Metrics

The receiver can report pgvector similarity-search and insert activity through a set of opt-in metrics. Prerequisites:

PostgreSQL 13 or later.
The pgvector extension installed in each scanned database. The l1, hamming, and jaccard distance functions additionally require pgvector 0.7.0 or later.
The pg_stat_statements extension (version 1.8+) installed and enabled in each scanned database (see below).

Search metrics

Three metrics report similarity-search activity

postgresql.vector.search.calls: the cumulative number of vector search executions.
postgresql.vector.search.duration: the cumulative execution time (in seconds) of vector searches.
postgresql.vector.search.rows_returned: the cumulative number of rows returned by vector searches.

[!NOTE] The distance function is inferred from the query text alone, so the receiver cannot tell which operator implementation is actually invoked. If the pg_trgm extension is also installed, its text-similarity <-> operator is indistinguishable from pgvector’s L2 <-> operator, so queries such as ORDER BY text_col <-> 'abc' may be counted under the l2 distance function.

Insert metrics

These metrics report write activity against pgvector tables

postgresql.vector.insert.rows: the cumulative number of vectors inserted.
postgresql.vector.insert.duration: the cumulative execution time (in seconds) of those inserts.

All of these metrics are disabled by default. Enable the ones you need via:

receivers:
  postgresql:
    metrics:
      postgresql.vector.search.calls:
        enabled: true
      postgresql.vector.search.duration:
        enabled: true
      postgresql.vector.search.rows_returned:
        enabled: true
      postgresql.vector.insert.rows:
        enabled: true
      postgresql.vector.insert.duration:
        enabled: true

The pg_stat_statements extension must be created in every database you want these metrics collected from:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Example Configuration

receivers:
  postgresql:
    endpoint: localhost:5432
    transport: tcp
    username: otel
    password: ${env:POSTGRESQL_PASSWORD}
    databases:
      - otel
    collection_interval: 10s
    tls:
      insecure: false
      insecure_skip_verify: false
      ca_file: /home/otel/authorities.crt
      cert_file: /home/otel/mypostgrescert.crt
      key_file: /home/otel/mypostgreskey.key
    events:
      db.server.query_sample:
        enabled: true
      db.server.top_query:
        enabled: true
    query_sample_collection:
      max_rows_per_query: 100
    top_query_collection:
      max_rows_per_query: 100
      top_n_query: 100
      collection_interval: 60s

The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in testdata/config.yaml. TLS config is documented further under the opentelemetry collector’s configtls package.

Connection pool feature

The feature gate receiver.postgresql.connectionPool allows to enable the creation & reuse of a pool per database for the connections instead of creating & closing on each scrape. This is generally a useful optimization but also alleviates the volume of generated audit logs when the PostgreSQL instance is configured with log_connections=on and/or log_disconnections=on. When this feature gate is enabled, the following optional settings are available nested under connection_pool to help configure the connection pools:

max_idle_time: The maximum amount of time a connection may be idle before being closed.
max_lifetime: The maximum amount of time a connection may be reused.
max_idle: The maximum number of connections in the idle connection pool.
max_open: The maximum number of open connections to the database.

Those settings and their defaults are further documented in the sql/database package. The connection pool composes with a db_auth block (e.g. AWS IAM). The credential is re-resolved on every new connection the pool opens, so a short-lived token (an RDS IAM token lives ~15 minutes) is re-minted as the pool grows or replaces connections, and a connection is never opened with an expired token. Connections already established stay valid for their lifetime — IAM authenticates only at connection open, not per query — so tune max_lifetime to bound how long a connection lives before it must reconnect with a fresh token.

Example Configuration

receivers:
  postgresql:
    endpoint: localhost:5432
    transport: tcp
    username: otel
    password: ${env:POSTGRESQL_PASSWORD}
    connection_pool:
      max_idle_time: 10m
      max_lifetime: 0
      max_idle: 2
      max_open: 5

OpenTelemetry semantic conventions feature gate

The feature gate receiver.postgresql.useOTelSemconv (alpha, disabled by default) controls the resource model used by this receiver:

Gate disabled (default): Legacy per-entity resource model. Each database, table, and index emits metrics under a separate resource with postgresql.database.name, postgresql.table.name, postgresql.index.name, and postgresql.schema.name as resource attributes. service.instance.id is in host:port format.
Gate enabled: Single resource per server. All metrics are emitted under one resource with server.address, server.port, and service.instance.id (UUID v5) as resource attributes, aligning with OpenTelemetry semantic conventions. Metric-level attributes db.namespace, db.collection.name, and postgresql.index.name are present on applicable metrics.

This gate is mutually exclusive with receiver.postgresql.separateSchemaAttr — both cannot be enabled simultaneously.

Metrics

Details about the metrics produced by this receiver can be found in metadata.yaml

[!NOTE] The optional postgresql.query.execution.time metric requires the pg_stat_statements extension to be installed and enabled.

Metrics

Metric Name	Description	Unit	Type	Attributes
✅ `postgresql.backends`	The number of backend processes associated with each database. Counts backends across all connection states (active, idle, idle-in-transaction) and all backend types, including non-client backends such as autovacuum and parallel workers.	1	UpDownCounter	db.namespace
✅ `postgresql.bgwriter.buffers.allocated`	Number of buffers allocated.	{buffers}	Counter
✅ `postgresql.bgwriter.buffers.writes`	Number of buffers written.	{buffers}	Counter	bg_buffer_source
✅ `postgresql.bgwriter.checkpoint.count`	The number of checkpoints performed.	{checkpoints}	Counter	bg_checkpoint_type
✅ `postgresql.bgwriter.duration`	Total time spent writing and syncing files to disk by checkpoints.	ms	Counter	bg_duration_type
✅ `postgresql.bgwriter.maxwritten`	Number of times the background writer stopped a cleaning scan because it had written too many buffers.	1	Counter
❌ `postgresql.blks_hit`	Number of times disk blocks were found already in the buffer cache.	{blks_hit}	Counter	db.namespace
❌ `postgresql.blks_read`	Number of disk blocks read in this database.	{blks_read}	Counter	db.namespace
✅ `postgresql.blocks_read`	The number of blocks read.	1	Counter	source, db.namespace, db.collection.name
✅ `postgresql.commits`	The number of commits.	1	Counter	db.namespace
✅ `postgresql.connection.max`	Configured maximum number of client connections allowed	{connections}	Gauge
✅ `postgresql.database.count`	Number of user databases.	{databases}	UpDownCounter
❌ `postgresql.database.locks`	The number of database locks.	{lock}	Gauge	relation, mode, lock_type, db.namespace
✅ `postgresql.db_size`	The database disk usage.	By	UpDownCounter	db.namespace
❌ `postgresql.deadlocks`	The number of deadlocks.	{deadlock}	Counter	db.namespace
❌ `postgresql.function.calls`	The number of calls made to a function. Requires `track_functions=pl\|all` in Postgres config.	{call}	Counter	function, db.namespace
✅ `postgresql.index.scans`	The number of index scans on a table.	{scans}	Counter	db.namespace, db.collection.name, postgresql.index.name
✅ `postgresql.index.size`	The size of the index on disk.	By	Gauge	db.namespace, db.collection.name, postgresql.index.name
✅ `postgresql.operations`	The number of db row operations.	1	Counter	operation, db.namespace, db.collection.name
❌ `postgresql.query.conflicts`	Number of queries canceled due to conflicts with recovery on this database. Conflicts only occur on standby servers; this metric will be zero on primary servers.	{query}	Counter	postgresql.conflict.type, db.namespace
❌ `postgresql.query.execution.time`	The total execution time of SQL statements currently tracked by pg_stat_statements for the database.	s	Counter	db.namespace
✅ `postgresql.replication.data_delay`	The amount of data delayed in replication.	By	Gauge	replication_client
✅ `postgresql.rollbacks`	The number of rollbacks.	1	Counter	db.namespace
✅ `postgresql.rows`	The number of rows in the database.	1	UpDownCounter	state, db.namespace, db.collection.name
❌ `postgresql.sequential_scans`	The number of sequential scans.	{sequential_scan}	Counter	db.namespace, db.collection.name
✅ `postgresql.table.count`	Number of user tables in a database.	{table}	UpDownCounter	db.namespace
✅ `postgresql.table.size`	Disk space used by a table.	By	UpDownCounter	db.namespace, db.collection.name
✅ `postgresql.table.vacuum.count`	Number of times a table has manually been vacuumed.	{vacuum}	Counter	db.namespace, db.collection.name
❌ `postgresql.temp.io`	Total amount of data written to temporary files by queries.	By	Counter	db.namespace
❌ `postgresql.temp_files`	The number of temp files.	{temp_file}	Counter	db.namespace
❌ `postgresql.tup_deleted`	Number of rows deleted by queries in the database.	{tup_deleted}	Counter	db.namespace
❌ `postgresql.tup_fetched`	Number of rows fetched by queries in the database.	{tup_fetched}	Counter	db.namespace
❌ `postgresql.tup_inserted`	Number of rows inserted by queries in the database.	{tup_inserted}	Counter	db.namespace
❌ `postgresql.tup_returned`	Number of rows returned by queries in the database.	{tup_returned}	Counter	db.namespace
❌ `postgresql.tup_updated`	Number of rows updated by queries in the database.	{tup_updated}	Counter	db.namespace
❌ `postgresql.vector.insert.duration`	The cumulative execution time of statements that insert vectors into pgvector tables.	s	Counter	db.namespace
❌ `postgresql.vector.insert.rows`	The number of vectors inserted into pgvector tables.	{vectors}	Counter	db.namespace
❌ `postgresql.vector.search.calls`	The number of vector similarity search operations executed, grouped by the distance function used.	{search}	Counter	postgresql.distance.function.name, db.namespace
❌ `postgresql.vector.search.duration`	The cumulative execution time of vector similarity searches, grouped by the distance function used.	s	Counter	postgresql.distance.function.name, db.namespace
❌ `postgresql.vector.search.rows_returned`	The cumulative number of rows returned by vector similarity searches, grouped by the distance function used.	{rows}	Counter	postgresql.distance.function.name, db.namespace
✅ `postgresql.wal.age`	Age of the oldest WAL file.	s	Gauge
❌ `postgresql.wal.delay`	Time between flushing recent WAL locally and receiving notification that the standby server has completed an operation with it.	s	Gauge	wal_operation_lag, replication_client
✅ `postgresql.wal.lag`	Time between flushing recent WAL locally and receiving notification that the standby server has completed an operation with it.	s	Gauge	wal_operation_lag, replication_client

Attributes

Attribute Name	Description	Type	Values
`source`	The source of a buffer write.	string	`backend`, `backend_fsync`, `checkpoints`, `bgwriter`
`type`	The type of checkpoint state.	string	`requested`, `scheduled`
`type`	The type of time spent during the checkpoint.	string	`sync`, `write`
`db.collection.name`	The name of the table within the database.	string
`db.namespace`	The database namespace, following the `{database}\|{schema}` format defined by OpenTelemetry semantic conventions for PostgreSQL.	string
`db.query.text`	The text of the database query being executed.	string
`db.system.name`	The database management system (DBMS) product as identified by the client instrumentation.	string	`postgresql`
`function`	The name of the function.	string
`lock_type`	Type of the lockable object.	string
`mode`	Name of the lock mode held or desired by the process.	string
`network.peer.address`	IP address of the client connected to this backend.	string
`network.peer.port`	TCP port number that the client is using for communication with this backend.	int
`operation`	The database operation.	string	`ins`, `upd`, `del`, `hot_upd`
`postgresql.application_name`	Name of the application that is connected to this backend.	string
`postgresql.blocking.lock.mode`	The lock mode being requested by the blocked session (e.g. RowExclusiveLock, AccessExclusiveLock). Empty string when not blocked.	string
`postgresql.blocking.lock.relation`	The name of the relation (table) being waited on. Empty string when not blocked or when lock is not on a relation.	string
`postgresql.blocking.lock.type`	The type of lock resource being waited on (e.g. relation, transactionid, tuple). Empty string when not blocked.	string
`postgresql.blocking.pids`	Array of PIDs of sessions blocking this session (from pg_blocking_pids). Empty array when not blocked.	string
`postgresql.blocking.start_time`	UTC timestamp (RFC3339) when the current lock wait began, derived from pg_locks.waitstart. Empty string when not blocked.	string
`postgresql.blocking.transaction.start_time`	UTC timestamp (RFC3339) when the current transaction started. Empty string when no active transaction.	string
`postgresql.blocking.wait_duration`	Whole seconds this session has been waiting for a lock, measured from pg_locks.waitstart. 0 when not blocked.	int
`postgresql.calls`	Number of times the statement was executed, reported in delta value.	int
`postgresql.client_hostname`	Host name of the connected client, as reported by a reverse DNS lookup of client_addr.	string
`postgresql.conflict.type`	The type of recovery conflict that caused a query to be canceled on a standby server.	string	`tablespace`, `lock`, `snapshot`, `bufferpin`, `deadlock`
`postgresql.distance.function.name`	The vector distance (similarity) function used by the query, one of the pgvector distance functions.	string	`cosine`, `l2`, `inner_product`, `l1`, `hamming`, `jaccard`
`postgresql.index.name`	The name of the index on a table.	string
`postgresql.pid`	Process ID of this backend.	int
`postgresql.query_id`	Identifier of this backend’s most recent query. If state is active this field shows the identifier of the currently executing query. In all other states, it shows the identifier of last query that was executed.	string
`postgresql.query_plan`	The execution plan used by PostgreSQL for the query.	string
`postgresql.query_start`	Time when the currently active query was started, or if state is not active, when the last query was started.	string
`postgresql.queryid`	Hash code to identify identical normalized queries.	string
`postgresql.rolname`	The name of the PostgreSQL role that executed the query.	string
`postgresql.rows`	Total number of rows retrieved or affected by the statement, reported in delta value.	int
`postgresql.shared_blks_dirtied`	Total number of shared blocks dirtied by the statement, reported in delta value.	int
`postgresql.shared_blks_hit`	Total number of shared block cache hits by the statement, reported in delta value.	int
`postgresql.shared_blks_read`	Total number of shared blocks read by the statement, reported in delta value.	int
`postgresql.shared_blks_written`	Total number of shared blocks written by the statement, reported in delta value.	int
`postgresql.state`	Current overall state of this backend	string
`postgresql.temp_blks_read`	Total number of temp blocks read by the statement, reported in delta value.	int
`postgresql.temp_blks_written`	Total number of temp blocks written by the statement, reported in delta value.	int
`postgresql.total_exec_time`	Total time spent executing the statement, in delta seconds.	double
`postgresql.total_plan_time`	Total time spent planning the statement, in delta seconds.	double
`postgresql.wait_event`	Wait event name if backend is currently waiting, otherwise NULL.	string
`postgresql.wait_event_type`	The type of event for which the backend is waiting, if any; otherwise NULL.	string
`relation`	OID of the relation targeted by the lock, or null if the target is not a relation or part of a relation.	string
`replication_client`	The IP address of the client connected to this backend. If this field is “unix”, it indicates either that the client is connected via a Unix socket.	string
`source`	The block read source type.	string	`heap_read`, `heap_hit`, `idx_read`, `idx_hit`, `toast_read`, `toast_hit`, `tidx_read`, `tidx_hit`
`state`	The tuple (row) state.	string	`dead`, `live`
`user.name`	Name of the user logged into this backend.	string
`operation`	The operation which is responsible for the lag.	string	`flush`, `replay`, `write`

Resource Attributes

Attribute Name	Description	Type	Enabled
`postgresql.database.name`	The name of the database.	string	✅
`postgresql.index.name`	The name of the index on a table.	string	✅
`postgresql.schema.name`	The schema name.	string	✅
`postgresql.table.name`	The table name.	string	✅
`server.address`	The address of the PostgreSQL server.	string	✅
`server.port`	The port number of the PostgreSQL server.	int	✅
`service.instance.id`	A unique identifier of the PostgreSQL instance.	string	✅
`service.name`	Logical name of the service. When enabled, defaults to unknown_service:postgresql.	string	❌
`service.namespace`	Logical namespace for the service (for example team or environment). When enabled, defaults to an empty string until set via configuration.	string	❌

Configuration

Example Configuration

postgresql/minimal:
  endpoint: localhost:5432
  username: otel
  password: ${env:POSTGRESQL_PASSWORD}
  top_query_collection:
    top_n_query: 1234
    query_plan_cache_ttl: 123s
postgresql/pool:
  endpoint: localhost:5432
  transport: tcp
  username: otel
  password: ${env:POSTGRESQL_PASSWORD}
  connection_pool:
    max_idle_time: 30s
    max_idle: 5
postgresql/all:
  endpoint: localhost:5432
  transport: tcp
  username: otel
  password: ${env:POSTGRESQL_PASSWORD}
  databases:
    - otel
  exclude_databases:
    - template0
  collection_interval: 10s
  tls:
    insecure: false
    insecure_skip_verify: false
    ca_file: /home/otel/authorities.crt
    cert_file: /home/otel/mypostgrescert.crt
    key_file: /home/otel/mypostgreskey.key
  connection_pool:
    max_idle_time: 30s
    max_lifetime: 1m
    max_idle: 5
    max_open: 10

Last generated: 2026-08-24

​Postgresql Receiver

​Supported Telemetry

​Overview

​Prerequisites

​Configuration

​Query Sample Collection

​Top Query Collection

​Vector Metrics

​Search metrics

​Insert metrics

​Example Configuration

​Connection pool feature

​Example Configuration

​OpenTelemetry semantic conventions feature gate

​Metrics

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

Postgresql Receiver

Supported Telemetry

Overview

Prerequisites

Configuration

Query Sample Collection

Top Query Collection

Vector Metrics

Search metrics

Insert metrics

Example Configuration

Connection pool feature

Example Configuration

OpenTelemetry semantic conventions feature gate

Metrics

Metrics

Attributes

Resource Attributes

Configuration

Example Configuration