This is documentation for the next version of Grafana Alloy Documentation. For the latest stable release, go to the latest version.

Documentation Grafana Alloy Reference Components database_observability database_observability.postgres

database_observability.postgres

database_observability.postgres connects to a PostgreSQL database and collects observability data from system catalogs and the pg_stat_statements extension. The component collects query details, schema information, explain plans, query samples, and processes PostgreSQL logs. It forwards this data as log entries to Loki receivers and exports targets for Prometheus scraping.

Usage

Alloy Copy

database_observability.postgres "<LABEL>" {
  data_source_name = <DATA_SOURCE_NAME>
  forward_to       = [<LOKI_RECEIVERS>]
}

Arguments

You can use the following arguments with database_observability.postgres:

Refer to the PostgreSQL documentation for more information about the format of the connection strings in data_source_name.

Exports

The following fields are exported and can be referenced by other components:

The following collectors are configurable:

Blocks

You can use the following blocks with database_observability.postgres:

cloud_provider

The cloud_provider block has no attributes. It contains zero or one of the aws, azure, or gcp blocks. You use the cloud_provider block to provide information related to the cloud provider that hosts the database under observation. This information is appended as labels to the collected metrics. The labels make it easier for you to filter and group your metrics.

aws

The aws block supplies the ARN identifier for the database being monitored.

azure

The azure block supplies the identifying information for the database being monitored.

gcp

The gcp block supplies the identifying information for the GCP Cloud SQL database being monitored.

query_details

query_samples

schema_details

The cache_enabled, cache_size, and cache_ttl settings are deprecated: they are accepted for backward compatibility, but ignored.

explain_plans

logs

The logs collector is always enabled and counts server errors from the PostgreSQL logs forwarded to logs_receiver. When enable_error_logs_processing is true, the collector additionally emits per-query error telemetry that associates each error with the query that caused it.

health_check

prometheus_exporter

The prometheus_exporter block configures the embedded postgres_exporter scrapers. The data_source_name is inherited from the parent block.

Refer to prometheus.exporter.postgres docs for the full list of supported arguments and sub-blocks.

logs collector

The logs collector processes PostgreSQL logs received through the logs_receiver entry point. It counts server errors and exposes them as a Prometheus metric on the component’s metrics endpoint. When enable_error_logs_processing is true, it also emits per-query error telemetry as Loki log entries, so each error can be associated with the query that caused it.

The logs_receiver entry point must be fed by loki log source components, for example:

• loki.source.file: to read and process PostgreSQL log files from a self-managed database instance
• otelcol.receiver.awscloudwatch and otelcol.exporter.loki: to read and process CloudWatch Logs for an AWS RDS instance

PostgreSQL must be configured with a specific log_line_prefix so the collector can parse the logs.

Example

Alloy Copy

database_observability.postgres "orders_db" {
  data_source_name = "postgres://user:pass@localhost:5432/dbname"
  forward_to       = [loki.relabel.orders_db.receiver]
  targets          = prometheus.exporter.postgres.orders_db.targets

  // Enable per-query error telemetry from the processed PostgreSQL logs.
  logs {
    enable_error_logs_processing = true
  }
}

prometheus.exporter.postgres "orders_db" {
  data_source_name   = "postgres://user:pass@localhost:5432/dbname"
  enabled_collectors = ["stat_statements"]
}

// OPTIONAL: read PostgreSQL log files and forward to logs collector
loki.source.file "postgres_logs" {
  targets = [{
    __path__ = "/var/log/postgresql/postgresql-*.log",
    job      = "postgres-logs",
  }]

  forward_to = [database_observability.postgres.orders_db.logs_receiver]
}

loki.relabel "orders_db" {
  forward_to = [loki.write.logs_service.receiver]
  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }
  rule {
    target_label = "instance"
    replacement  = "orders_db"
  }
}

discovery.relabel "orders_db" {
  targets = database_observability.postgres.orders_db.targets

  rule {
    target_label = "job"
    replacement  = "integrations/db-o11y"
  }
  rule {
    target_label = "instance"
    replacement  = "orders_db"
  }
}

prometheus.scrape "orders_db" {
  targets    = discovery.relabel.orders_db.targets
  job_name   = "integrations/db-o11y"
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}

prometheus.remote_write "metrics_service" {
  endpoint {
    url = sys.env("<GRAFANA_CLOUD_HOSTED_METRICS_URL>")
    basic_auth {
      username = sys.env("<GRAFANA_CLOUD_HOSTED_METRICS_ID>")
      password = sys.env("<GRAFANA_CLOUD_RW_API_KEY>")
    }
  }
}

loki.write "logs_service" {
  endpoint {
    url = sys.env("<GRAFANA_CLOUD_HOSTED_LOGS_URL>")
    basic_auth {
      username = sys.env("<GRAFANA_CLOUD_HOSTED_LOGS_ID>")
      password = sys.env("<GRAFANA_CLOUD_RW_API_KEY>")
    }
  }
}

Replace the following:

• <GRAFANA_CLOUD_HOSTED_METRICS_URL>: The URL for your Grafana Cloud hosted metrics.
• <GRAFANA_CLOUD_HOSTED_METRICS_ID>: The user ID for your Grafana Cloud hosted metrics.
• <GRAFANA_CLOUD_RW_API_KEY>: Your Grafana Cloud API key.
• <GRAFANA_CLOUD_HOSTED_LOGS_URL>: The URL for your Grafana Cloud hosted logs.
• <GRAFANA_CLOUD_HOSTED_LOGS_ID>: The user ID for your Grafana Cloud hosted logs.

Compatible components

database_observability.postgres can accept arguments from the following components:

• Components that export Targets
• Components that export Loki LogsReceiver

database_observability.postgres has exports that can be consumed by the following components:

• Components that consume Targets
• Components that consume Loki LogsReceiver