​

Postgresql Receiver

​

Supported Telemetry

​

Overview

​

Prerequisites

[!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

See https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/29559 for more details.

​

Configuration

• username
• password

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

• 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

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

GRANT pg_monitor TO otelu;

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

​

Top Query Collection

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

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

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

​

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

​

Connection pool feature

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

​

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

​

Metrics

​

Metrics

​

Attributes

​

Resource Attributes

​

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