---
title: "database_observability.postgres | Grafana Cloud documentation"
description: "Learn about 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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`:

Expand table

| Name                 | Type                 | Description                                                                                                                          | Default                                                                                              | Required |
|----------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|----------|
| `data_source_name`   | `secret`             | [Data Source Name](https://pkg.go.dev/github.com/lib/pq#hdr-URL_connection_strings-NewConfig) for the Postgres server to connect to. |                                                                                                      | yes      |
| `forward_to`         | `list(LogsReceiver)` | Where to forward log entries after processing.                                                                                       |                                                                                                      | yes      |
| `targets`            | `list(map(string))`  | List of external targets to scrape for Prometheus metrics.                                                                           |                                                                                                      | no       |
| `disable_collectors` | `list(string)`       | A list of collectors to disable from the default set.                                                                                |                                                                                                      | no       |
| `enable_collectors`  | `list(string)`       | A list of collectors to enable on top of the default set.                                                                            |                                                                                                      | no       |
| `exclude_databases`  | `list(string)`       | A list of databases to exclude from monitoring.                                                                                      | `["alloydbadmin", "alloydbmetadata", "azure_maintenance", "azure_sys", "cloudsqladmin", "rdsadmin"]` | no       |
| `exclude_users`      | `list(string)`       | A list of users to exclude from monitoring.                                                                                          | `["azuresu", "cloudsqladmin", "db-o11y", "rdsadmin"]`                                                | no       |

Refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) 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:

Expand table

| Name            | Type                | Description                                                            |
|-----------------|---------------------|------------------------------------------------------------------------|
| `logs_receiver` | `LogsReceiver`      | Receiver for PostgreSQL logs that processes and exports error metrics. |
| `targets`       | `list(map(string))` | Targets that can be used to collect metrics from the component.        |

The following collectors are configurable:

Expand table

| Name             | Description                                                           | Enabled by default |
|------------------|-----------------------------------------------------------------------|--------------------|
| `explain_plans`  | Collect query explain plans.                                          | yes                |
| `logs`           | Process PostgreSQL logs and export error metrics.                     | yes                |
| `query_details`  | Collect queries information.                                          | yes                |
| `query_samples`  | Collect query samples and wait events information.                    | yes                |
| `schema_details` | Collect schemas, tables, and columns from PostgreSQL system catalogs. | yes                |

## Blocks

You can use the following blocks with `database_observability.postgres`:

No valid configuration blocks found.

### `cloud_provider`

The `cloud_provider` block has no attributes. It contains zero or more \[`aws`]\[aws], \[`azure`]\[azure], or \[`gcp`]\[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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html) identifier for the database being monitored.

Expand table

| Name  | Type     | Description                                             | Default | Required |
|-------|----------|---------------------------------------------------------|---------|----------|
| `arn` | `string` | The ARN associated with the database under observation. |         | yes      |

### `azure`

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

Expand table

| Name              | Type     | Description                                          | Default | Required |
|-------------------|----------|------------------------------------------------------|---------|----------|
| `subscription_id` | `string` | The Subscription ID for your Azure account.          |         | yes      |
| `resource_group`  | `string` | The Resource Group that holds the database resource. |         | yes      |
| `server_name`     | `string` | The database server name.                            |         | no       |

### `gcp`

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

Expand table

| Name              | Type     | Description                                                                                                                 | Default | Required |
|-------------------|----------|-----------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `connection_name` | `string` | The Cloud SQL instance connection name in the format `project:region:instance`, for example `my-project:us-central1:my-db`. |         | yes      |

### `query_details`

Expand table

| Name               | Type       | Description                                          | Default | Required |
|--------------------|------------|------------------------------------------------------|---------|----------|
| `collect_interval` | `duration` | How frequently to collect information from database. | `"1m"`  | no       |
| `statements_limit` | `integer`  | Max number of recent queries to collect details for. | `100`   | no       |

### `query_samples`

Expand table

| Name                      | Type       | Description                                                   | Default | Required |
|---------------------------|------------|---------------------------------------------------------------|---------|----------|
| `collect_interval`        | `duration` | How frequently to collect information from database.          | `"15s"` | no       |
| `disable_query_redaction` | `bool`     | Collect unredacted SQL query text (might include parameters). | `false` | no       |
| `exclude_current_user`    | `bool`     | Do not collect query samples for current database user.       | `true`  | no       |

### `schema_details`

Expand table

| Name               | Type       | Description                                          | Default | Required |
|--------------------|------------|------------------------------------------------------|---------|----------|
| `collect_interval` | `duration` | How frequently to collect information from database. | `"1m"`  | no       |
| `cache_enabled`    | `boolean`  | Whether to enable caching of table definitions.      | `true`  | no       |
| `cache_size`       | `integer`  | Cache size.                                          | `256`   | no       |
| `cache_ttl`        | `duration` | Cache TTL.                                           | `"10m"` | no       |

### `explain_plans`

Expand table

| Name                | Type       | Description                                          | Default | Required |
|---------------------|------------|------------------------------------------------------|---------|----------|
| `collect_interval`  | `duration` | How frequently to collect information from database. | `"1m"`  | no       |
| `per_collect_ratio` | `float64`  | The ratio of queries to collect explain plans for.   | `1.0`   | no       |

### `health_check`

Expand table

| Name               | Type       | Description                                          | Default | Required |
|--------------------|------------|------------------------------------------------------|---------|----------|
| `collect_interval` | `duration` | How frequently to collect information from database. | `"1h"`  | no       |

### `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/grafana-cloud/send-data/alloy/reference/components/prometheus/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 and exports Prometheus metrics for query and server errors.

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-hosted database instance
- `otelcol.receiver.awscloudwatch` and `otelcol.exporter.loki`: to read and process CloudWatch Logs for an AWS RDS instance

> Note
> 
> Refer to the [documentation](/docs/grafana-cloud/monitor-applications/database-observability/get-started/postgres/) for detailed log configuration options.

## Example

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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"]
}

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](/docs/grafana-cloud/send-data/alloy/reference/compatibility/#targets-exporters)
- Components that export [Loki `LogsReceiver`](/docs/grafana-cloud/send-data/alloy/reference/compatibility/#loki-logsreceiver-exporters)

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

- Components that consume [Targets](/docs/grafana-cloud/send-data/alloy/reference/compatibility/#targets-consumers)
- Components that consume [Loki `LogsReceiver`](/docs/grafana-cloud/send-data/alloy/reference/compatibility/#loki-logsreceiver-consumers)

> Note
> 
> Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.