Documentation Grafana Alloy Reference Components database_observability database_observability.postgres

database_observability.postgres

Usage

Alloy Copy

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

Arguments

You can use the following arguments with database_observability.postgres:

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:

The > symbol indicates deeper levels of nesting. For example, cloud_provider > aws refers to a aws block defined inside an cloud_provider block.

cloud_provider

The cloud_provider block has no attributes. It contains zero or more aws 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.

query_details

query_samples

schema_details

explain_plans

health_check

Logs Collector

The logs collector processes PostgreSQL logs received through the logs_receiver entry point and exports Prometheus metrics for query and server errors.

Exported Receiver

The component exports a logs_receiver entry point that must be fed by log source components.

• otelcol.receiver.awscloudwatch + otelcol.exporter.loki - reads CloudWatch Logs (RDS) and forwards to the receiver
• loki.source.file - reads PostgreSQL log files and forwards to the receiver
• otelcol.receiver.otlp + otelcol.exporter.loki - receives OTLP logs and forwards to the receiver

Metrics

The logs collector exports the following Prometheus metrics:

Required PostgreSQL Configuration

For the logs collector to work correctly, PostgreSQL must be configured with the following RDS log format:

SQL Copy

-- Set log format (requires superuser or rds_superuser)
ALTER SYSTEM SET log_line_prefix = '%m:%r:%u@%d:[%p]:%l:%e:%s:%v:%x:%c:%q%a';

-- Reload configuration
SELECT pg_reload_conf();

Use the following SELECT statement to show and verify the current string format applied to the beginning of each log line.

SQL Copy

SHOW log_line_prefix;

Supported Log Format

The collector expects PostgreSQL logs in the RDS format with these fields:

Copy

<timestamp>:<remote_host:port>:<user>@<database>:[<pid>]:<line>:<SQLSTATE>:<session_start>:<vtxid>:<txid>:<session_id>:<query><app><severity>: <message>

Example log line:

Copy

2026-02-02 21:35:40.130 UTC:10.24.155.141(34110):app_user@books_store:[32032]:2:40001:2026-02-02 21:33:19 UTC:25/112:0:693c34cb.2398::psqlERROR:  canceling statement due to user request

Watermark and Historical Log Processing

The logs collector uses a watermark file to track the last processed log timestamp. This prevents re-counting historical logs on component restart and maintains proper Prometheus counter semantics.

Default behavior:

• Watermark file: <data_path>/dbo11y_pg_logs_watermark.txt
• On first run: Starts processing logs from the current time (skips historical logs)
• On restart: Resumes from the last processed timestamp
• Sync frequency: Every 10 seconds (atomic writes for crash safety)

Benefits:

• postgres_errors_total maintains monotonically increasing values
• No duplicate counting on Alloy restarts
• Proper rate() and increase() calculations in Prometheus
• Resumes from last position after downtime (no data loss)

Example with custom watermark path:

Alloy Copy

database_observability.postgres "orders_db" {
  data_source_name = "postgres://user:pass@localhost:5432/dbname"
  watermark_path   = "/var/lib/alloy/postgres_orders_watermark.txt"
  forward_to       = [loki.relabel.orders_db.receiver]
  targets          = prometheus.exporter.postgres.orders_db.targets
}

Important: When using log sources with start_from set to historical timestamps (e.g., otelcol.receiver.awscloudwatch with start_from = "2026-01-01T00:00:00Z"), the watermark ensures that historical logs are only counted once, even if Alloy restarts multiple times.

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_collectors = ["query_samples", "explain_plans"]

  cloud_provider {
    aws {
      arn = "your-rds-db-arn"
    }
  }
}

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

// 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