database_observability on Grafana Labs

database_observability.mysql

Mon, 19 Oct 2026 11:17:26 +0000

`database_observability.mysql`

database_observability.mysql connects to a MySQL database and collects observability data from the performance_schema and information_schema. The component collects query details, schema information, explain plans, query samples, and lock information. It forwards this data as log entries to Loki receivers and exports targets for Prometheus scraping.

Usage

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

Arguments

You can use the following arguments with database_observability.mysql:

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the MySQL server to connect to. Required when no `database_instance` blocks are defined.		no
`forward_to`	`list(LogsReceiver)`	Where to forward log entries after processing.		yes
`targets`	`list(map(string))`	List of external targets to scrape.		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_schemas`	`list(string)`	A list of schemas to exclude from monitoring.	`["alloydbadmin", "alloydbmetadata", "azure_maintenance", "azure_sys", "cloudsqladmin", "rdsadmin"]`	no
`allow_update_performance_schema_settings`	`boolean`	Whether to allow updates to `performance_schema` settings in any collector. Enable this in conjunction with other collector-specific settings where required.	`false`	no

The following collectors are configurable:

Name	Description	Enabled by default
`query_details`	Collect queries information.	yes
`schema_details`	Collect schemas and tables from `information_schema`.	yes
`query_samples`	Collect query samples.	yes
`setup_consumers`	Collect enabled `performance_schema.setup_consumers`.	yes
`setup_actors`	Check and update `performance_schema.setup_actors` settings.	yes
`locks`	Collect queries that are waiting/blocking other queries.	no
`explain_plans`	Collect explain plans information.	yes
`table_stats`	Collect table-level index usage statistics.	no
`index_stats`	Collect per-index usage statistics.	no

Blocks

You can use the following blocks with database_observability.mysql:

Block	Description	Required
`cloud_provider`	Provide Cloud Provider information.	no
`cloud_provider` > `aws`	Provide AWS database host information.	no
`cloud_provider` > `azure`	Provide Azure database host information.	no
`cloud_provider` > `gcp`	Provide GCP database host information.	no
`database_instance`	Define one database to monitor. Repeat the block to monitor several databases.	no
`database_instance` > `cloud_provider`	Provide Cloud Provider information for one database.	no
`database_instance` > `rule`	Relabel the metrics and logs of one database.	no
`clustering`	Configure the component for when Alloy is running in clustered mode.	no
`setup_consumers`	Configure the `setup_consumers` collector.	no
`setup_actors`	Configure the `setup_actors` collector.	no
`query_details`	Configure the queries collector.	no
`schema_details`	Configure the schema and table details collector.	no
`explain_plans`	Configure the explain plans collector.	no
`locks`	Configure the locks collector.	no
`query_samples`	Configure the query samples collector.	no
`health_check`	Configure the health check collector.	no
`prometheus_exporter`	Configure the embedded mysqld_exporter.	no

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

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.

Name	Type	Description	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, for example `orders-db` for the host `orders-db.mysql.database.azure.com`.	no

`gcp`

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

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

`database_instance`

The database_instance block defines one database server to monitor. Repeat the block to monitor several databases with a single component. The block label must be unique across database_instance blocks and identifies the database in the component’s metrics endpoint path. Each database_instance block must also point to a distinct server: two blocks that resolve to the same host, port, and database name are rejected.

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the MySQL server to connect to.		yes

Each database_instance block can also contain a [cloud_provider][cloud_provider] block that applies to that database only, and [rule][rule] blocks that relabel the metrics and logs of that database only.

The component always embeds a mysqld_exporter for each database_instance block and serves its metrics on the block’s metrics path. Use the [prometheus_exporter][prometheus_exporter] block to configure it. External exporter targets are only supported in the top-level single-DSN form.

When you define database_instance blocks, don’t set the top-level data_source_name, targets, and cloud_provider arguments. They’re mutually exclusive with database_instance blocks. All other arguments and blocks, such as collector settings and prometheus_exporter, apply to every configured database.

The metrics for each database are served on a separate /db/<LABEL>/metrics path under the component’s HTTP endpoint, and the exported targets point to the corresponding path. When you don’t define database_instance blocks, the component serves metrics on its historical /metrics path. The metrics endpoints are served exactly at those paths: requests to any other path under the component’s HTTP endpoint return HTTP 404.

For example:

database_observability.mysql "pool" {
  forward_to = [loki.write.logs_service.receiver]

  database_instance "orders" {
    data_source_name = sys.env("ORDERS_DSN")

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

    rule {
      target_label = "environment"
      replacement  = "production"
    }
  }

  database_instance "billing" {
    data_source_name = sys.env("BILLING_DSN")

    rule {
      target_label = "environment"
      replacement  = "staging"
    }
  }
}

In this example, the metrics and logs of the orders database carry environment="production", and those of the billing database carry environment="staging".

`rule`

The rule block relabels the metrics and the logs of the database_instance block that contains it. Use it to tell the data of each monitored database apart, for example by environment, team, or tier.

The rule block defines a relabeling rule applied to the metrics and the logs of a single monitored database. If you define more than one rule block, the rules are applied in top-down order, after the labels the component sets itself, so a rule can read those labels with source_labels.

It takes the same arguments as the rule block used elsewhere in Alloy, in a restricted form: because one rule set applies to two signal paths, it supports the labelling actions only, and it can’t overwrite most of the labels the component sets. Alloy refuses to load a configuration containing a rule that breaks either restriction, so such a rule is never silently ignored.

Two further constraints are specific to a database_instance block:

target_label must be a literal label name: Alloy checks it against the reserved labels when it loads the configuration, so it can’t contain a capture group reference.
hashmod requires source_labels, and can’t target instance: hashing the empty value gives every database the same result, and hashing into instance buckets several databases onto one value even when the source is present.

Caution
A relabeling rule that computes an empty value removes its target label instead of setting it, and the default replacement of "$1" computes an empty value when a rule has no source_labels. So rule { target_label = "environment" } removes environment rather than setting it, and Alloy rejects it. Always set replacement alongside a target_label.

Alloy can only reject such a rule where the outcome is certain. A rule that reads source_labels depends on the labels present at runtime, so a missing or misspelled source label still removes the target label, except for the reserved labels and instance, which keep their previous value. Only removal is prevented: a rule that computes a non-empty value still overwrites those labels, which is why hashmod can’t target instance at all.

You can use the hashmod, labeldrop, lowercase, replace, and uppercase actions. The rest aren’t supported:

drop, dropequal, keep, and keepequal filter rather than label, and filtering means two different things on the two signal paths. Dropping a metrics target stops the database exporting metrics entirely, whereas dropping a log entry discards one line. To filter one database’s logs, use a loki.relabel component on the receiver named in forward_to, with a drop rule that matches that database’s instance or server_id. Every database the component monitors forwards to the same receivers, so the rule has to identify the one it applies to. To filter one database’s metrics, use a discovery.relabel component on the component’s exported targets.
labelmap builds label names from replacement at runtime, so Alloy can’t check them against the reserved labels when it loads the configuration.
labelkeep removes every label its regex doesn’t match, so a rule that preserves the reserved labels would have to match all of them. Use labeldrop to remove specific labels instead.

Because the rules run after the component’s own labels, and those are protected, a labeldrop rule can only remove a label that an earlier rule in the same block created.

Reserved labels

A rule can’t write to the following labels, and a labeldrop regular expression can’t match them:

Both metrics and logs: job and server_id.
Logs only: engine and op.
Metrics only: provider_name, provider_region, provider_account, __address__, __scheme__, and __metrics_path__.

This applies to rule blocks only. A downstream discovery.relabel or loki.relabel component can still overwrite any of them, but it applies to every database the component monitors rather than one.

The instance label is a special case: a rule can rewrite its value, which is a common reason to use a rule block, because a friendly name such as orders_db then applies to that database’s metrics and logs together. A rule can’t remove it, because metrics and logs are correlated on it, and because an empty instance on a metrics target makes Prometheus fill it in from __address__, which every database in one component shares, collapsing them all onto one series.

For the same reason, two database_instance blocks can’t rewrite instance to the same value. Alloy rejects that when both values are fixed in the configuration, but it can’t when the value comes from a label the databases share: source_labels = ["job"] gives every database the same instance, since they all carry the same job. Derive instance from something that differs per database, or set a literal value in each block.

Labels set on only one signal path

Some of the labels above exist on one signal path and not the other, and a rule that reads one with source_labels behaves differently on each path: where the label is absent the rule computes an empty value, which removes its target_label rather than setting it to an empty string.

A rule reading provider_region, which a database with a cloud_provider block carries on its metrics targets but not on its log entries, sets region on that database’s metrics and removes region from its logs. Reading a logs-only label such as op does the same in reverse. Only job, server_id, and instance are set on both paths, so prefer those as source_labels, or a label an earlier rule in the same block created.

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables distributing databases with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this database_observability.mysql component instance opts-in to distributing its configured databases between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file. All component instances opting in to clustering use the instance key of each configured database, <network>(<host>:<port>)/<dbname>, and a consistent hashing algorithm to determine ownership of each database between the cluster peers. Each peer then only collects from the subset of databases it’s responsible for, and only exports the targets of those databases, so prometheus.scrape components on the same node scrape exactly the databases the node owns. When a node joins or leaves the cluster, every peer recalculates ownership: expect a short gap or a brief duplicate collection for a database while its ownership moves. This includes the collectors that update performance_schema settings, such as setup_actors and setup_consumers, which can briefly run from two nodes during the move: their updates are idempotent. While the cluster isn’t yet ready to admit traffic, for example while it’s still forming and waiting for the minimum cluster size, the component doesn’t collect from any database.

Clustering is also useful with a single database: when several cluster nodes run an identical configuration, exactly one node collects from the database at a time, which gives you a highly available setup without duplicate collection.

If Alloy is not running in clustered mode, then the block is a no-op and database_observability.mysql collects from every configured database.

`setup_consumers`

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

`query_details`

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.	`250`	no

`schema_details`

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

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

`explain_plans`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect information from database.	`"1m"`	no
`initial_lookback`	`duration`	How far back to look for explain plan queries on the first collection interval.	`"24h"`	no
`per_collect_ratio`	`float`	Ratio of explain plan queries to collect per collect interval.	`1.0`	no

`locks`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect information from database.	`"30s"`	no
`threshold`	`duration`	Threshold for locks to be considered slow. Locks that exceed this duration are logged.	`"1s"`	no

`query_samples`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect information from database.	`"10s"`	no
`disable_query_redaction`	`bool`	Collect unredacted SQL query text (including query parameters) and query error messages.	`false`	no
`auto_enable_setup_consumers`	`boolean`	Enables specific `performance_schema.setup_consumers` options. You must also enable `allow_update_performance_schema_settings`.	`false`	no
`setup_consumers_check_interval`	`duration`	How frequently to check if `setup_consumers` are correctly enabled.	`"1h"`	no
`sample_min_duration`	`duration`	Minimum duration for query samples to be collected. Set to “0s” to disable filtering and collect all samples regardless of their duration.	`"0s"`	no
`wait_event_min_duration`	`duration`	Minimum duration for a wait event to be collected. Set to “0s” to disable filtering and collect all wait events regardless of their duration.	`"1us"`	no
`enable_pre_classified_wait_events`	`boolean`	When `true`, emits telemetry data with pre-classified wait event information.	`false`	no

`setup_actors`

Name	Type	Description	Default	Required
`auto_update_setup_actors`	`boolean`	Enables updates to `performance_schema.setup_actors` settings. You must also enable `allow_update_performance_schema_settings`.	`false`	no
`collect_interval`	`duration`	How frequently to check if `setup_actors` are configured correctly.	`"1h"`	no

`health_check`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to run health checks.	`"1h"`	no

`prometheus_exporter`

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

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

Example

database_observability.mysql "orders_db" {
  data_source_name = "user:pass@tcp(mysql:3306)/"
  forward_to       = [loki.relabel.orders_db.receiver]
  targets          = prometheus.exporter.mysql.orders_db.targets

  enable_collectors = ["query_samples", "explain_plans"]

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

prometheus.exporter.mysql "orders_db" {
  data_source_name  = "user:pass@tcp(mysql:3306)/"
  enable_collectors = ["perf_schema.eventsstatements"]
}

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.mysql.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.mysql can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

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

Components that consume Targets

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.

database_observability.postgres

Mon, 19 Oct 2026 11:17:26 +0000

`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

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:

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the Postgres server to connect to. Required when no `database_instance` blocks are defined.		no
`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
`exclude_current_user`	`bool`	Exclude from activity monitoring the user that Alloy uses to connect to the database. The resolved username is automatically added to `exclude_users`, if not already present.	`true`	no

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:

Name	Type	Description
`logs_receiver`	`LogsReceiver`	Receiver for PostgreSQL logs that processes and exports error metrics. Exported in the single-DSN form only.
`logs_receivers`	`map(LogsReceiver)`	One logs receiver per [`database_instance`][database_instance] block, keyed by block label. Empty in the single-DSN form.
`targets`	`list(map(string))`	Targets that can be used to collect metrics from the component.

The following collectors are configurable:

Name	Description	Enabled by default
`explain_plans`	Collect query explain plans.	yes
`table_stats`	Collect table-level scan statistics.	no
`index_stats`	Collect per-index usage statistics.	no
`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:

Block	Description	Required
`cloud_provider`	Provide Cloud Provider information.	no
`cloud_provider` > `aws`	Provide AWS database host information.	no
`cloud_provider` > `azure`	Provide Azure database host information.	no
`cloud_provider` > `gcp`	Provide GCP database host information.	no
`database_instance`	Define one database to monitor. Repeat the block to monitor several databases.	no
`database_instance` > `cloud_provider`	Provide Cloud Provider information for one database.	no
`database_instance` > `rule`	Relabel the metrics and logs of one database.	no
`clustering`	Configure the component for when Alloy is running in clustered mode.	no
`setup_consumers`	Configure the `setup_consumers` collector.	no
`setup_actors`	Configure the `setup_actors` collector.	no
`query_details`	Configure the queries collector.	no
`schema_details`	Configure the schema and table details collector.	no
`explain_plans`	Configure the explain plans collector.	no
`locks`	Configure the locks collector.	no
`query_samples`	Configure the query samples collector.	no
`health_check`	Configure the health check collector.	no
`prometheus_exporter`	Configure the embedded mysqld_exporter.	no

`cloud_provider`

`aws`

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

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.

Name	Type	Description	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, for example `orders-db` for the host `orders-db.postgres.database.azure.com`.	no

`gcp`

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

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

`database_instance`

The database_instance block defines one database server to monitor. Repeat the block to monitor several databases with a single component. The block label must be unique across database_instance blocks and identifies the database in the component’s metrics endpoint path and in the logs_receivers export. Each database_instance block must also point to a distinct server: two blocks that resolve to the same host, port, and database name are rejected.

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the Postgres server to connect to.		yes

The component always embeds a postgres_exporter for each database_instance block and serves its metrics on the block’s metrics path. Use the [prometheus_exporter][prometheus_exporter] block to configure it. External exporter targets are only supported in the top-level single-DSN form.

Each database also gets its own logs receiver in the logs_receivers export, keyed by the block label. Forward each database’s PostgreSQL logs to its own receiver so log-derived error metrics are attributed to the right database.

For example:

database_observability.postgres "pool" {
  forward_to = [loki.write.logs_service.receiver]

  database_instance "orders" {
    data_source_name = sys.env("ORDERS_DSN")

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

    rule {
      target_label = "environment"
      replacement  = "production"
    }
  }

  database_instance "billing" {
    data_source_name = sys.env("BILLING_DSN")

    rule {
      target_label = "environment"
      replacement  = "staging"
    }
  }
}

loki.source.file "orders_db_logs" {
  targets    = local.file_match.orders_db_logs.targets
  forward_to = [database_observability.postgres.pool.logs_receivers["orders"]]
}

In this example, the metrics and logs of the orders database carry environment="production", and those of the billing database carry environment="staging".

The component doesn’t forward the raw PostgreSQL log lines it receives on logs_receivers. It reads them to derive error-message entries, and those derived entries are what the rule blocks relabel. Deriving them requires [logs.enable_error_logs_processing][logs], which is disabled by default.

`rule`

Two further constraints are specific to a database_instance block:

target_label must be a literal label name: Alloy checks it against the reserved labels when it loads the configuration, so it can’t contain a capture group reference.
hashmod requires source_labels, and can’t target instance: hashing the empty value gives every database the same result, and hashing into instance buckets several databases onto one value even when the source is present.

Caution
A relabeling rule that computes an empty value removes its target label instead of setting it, and the default replacement of "$1" computes an empty value when a rule has no source_labels. So rule { target_label = "environment" } removes environment rather than setting it, and Alloy rejects it. Always set replacement alongside a target_label.

Alloy can only reject such a rule where the outcome is certain. A rule that reads source_labels depends on the labels present at runtime, so a missing or misspelled source label still removes the target label, except for the reserved labels and instance, which keep their previous value. Only removal is prevented: a rule that computes a non-empty value still overwrites those labels, which is why hashmod can’t target instance at all.

You can use the hashmod, labeldrop, lowercase, replace, and uppercase actions. The rest aren’t supported:

drop, dropequal, keep, and keepequal filter rather than label, and filtering means two different things on the two signal paths. Dropping a metrics target stops the database exporting metrics entirely, whereas dropping a log entry discards one line. To filter one database’s logs, use a loki.relabel component on the receiver named in forward_to, with a drop rule that matches that database’s instance or server_id. Every database the component monitors forwards to the same receivers, so the rule has to identify the one it applies to. To filter one database’s metrics, use a discovery.relabel component on the component’s exported targets.
labelmap builds label names from replacement at runtime, so Alloy can’t check them against the reserved labels when it loads the configuration.
labelkeep removes every label its regex doesn’t match, so a rule that preserves the reserved labels would have to match all of them. Use labeldrop to remove specific labels instead.

Because the rules run after the component’s own labels, and those are protected, a labeldrop rule can only remove a label that an earlier rule in the same block created.

Reserved labels

A rule can’t write to the following labels, and a labeldrop regular expression can’t match them:

Both metrics and logs: job and server_id.
Logs only: engine and op.
Metrics only: provider_name, provider_region, provider_account, __address__, __scheme__, and __metrics_path__.

Labels set on only one signal path

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables distributing databases with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this database_observability.postgres component instance opts-in to distributing its configured databases between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file. All component instances opting in to clustering use the instance key of each configured database, postgresql://<host>:<port>/<dbname>, and a consistent hashing algorithm to determine ownership of each database between the cluster peers. Each peer then only collects from the subset of databases it’s responsible for, and only exports the targets of those databases, so prometheus.scrape components on the same node scrape exactly the databases the node owns. When a node joins or leaves the cluster, every peer recalculates ownership: expect a short gap or a brief duplicate collection for a database while its ownership moves. While the cluster isn’t yet ready to admit traffic, for example while it’s still forming and waiting for the minimum cluster size, the component doesn’t collect from any database.

Every node exports the logs receivers of all configured databases, whether it owns them or not: a node that doesn’t own a database accepts and discards entries sent to that database’s receiver. Log pipelines that forward PostgreSQL logs to the exported receivers therefore work unchanged on every node, but only the owning node processes the logs into error metrics.

If Alloy is not running in clustered mode, then the block is a no-op and database_observability.postgres collects from every configured database.

`query_details`

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`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect information from database.	`"10s"`	no
`disable_query_redaction`	`bool`	Collect unredacted SQL query text (might include parameters).	`false`	no
`exclude_current_user`	`bool`	Deprecated. Use the top-level `exclude_current_user` argument instead. This setting takes precedence over the top-level setting.	(unset)	no
`enable_pre_classified_wait_events`	`boolean`	When `true`, emits telemetry data with pre-classified wait event information.	`false`	no

`schema_details`

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

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

`explain_plans`

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

`logs`

Name	Type	Description	Default	Required
`enable_error_logs_processing`	`bool`	Emit per-query error telemetry by pairing error and statement log lines.	`false`	no

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`

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 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. When you define [database_instance][database_instance] blocks, each database has its own entry point in the logs_receivers export instead, keyed by block label.

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.

Note
Refer to the PostgreSQL setup documentation for the required log_line_prefix and detailed log configuration options.

Example

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

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.

database_observability.sql_server

Mon, 19 Oct 2026 11:17:26 +0000

`database_observability.sql_server`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

database_observability.sql_server connects to a Microsoft SQL Server instance and collects observability data across every accessible user database on that instance. The component forwards this data as log entries to Loki receivers and exports targets for Prometheus scraping.

Usage

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

Arguments

You can use the following arguments with database_observability.sql_server:

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the SQL Server instance to connect to. Required when no `database_instance` blocks are defined.		no
`forward_to`	`list(LogsReceiver)`	Where to forward log entries after processing.		yes
`targets`	`list(map(string))`	List of external targets to scrape.		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_current_user`	`bool`	Exclude query samples from sessions opened with the login that Alloy uses.	`true`	no
`exclude_schemas`	`list(string)`	A list of schemas to exclude from monitoring, on top of the always-excluded system schemas `sys` and `information_schema`.	`["alloydbadmin", "alloydbmetadata", "azure_maintenance", "azure_sys", "cloudsqladmin", "rdsadmin"]`	no
`exclude_databases`	`list(string)`	A list of databases to exclude from monitoring, on top of the always-excluded system databases `master`, `model`, `msdb`, and `tempdb`.	`["alloydbadmin", "alloydbmetadata", "azure_maintenance", "azure_sys", "cloudsqladmin", "rdsadmin"]`	no
`exclude_users`	`list(string)`	A list of original SQL Server login names to exclude from query samples.	`["azuresu", "cloudsqladmin", "db-o11y", "rdsadmin"]`	no
`query_timeout`	`duration`	Timeout for each SQL statement.	`"10s"`	no

The query_timeout applies separately to each SQL statement. The timeout includes waiting for an available connection and reading the statement results. A collection cycle can run multiple statements and can take longer than query_timeout.

The following collectors are configurable:

Name	Description	Enabled by default
`explain_plans`	Collect and parse query execution plans already captured by Query Store.	yes
`query_details`	Collect query text and parsed table names from Query Store.	yes
`query_metrics`	Collect per-query executions, errors, and duration counters from Query Store.	yes
`query_samples`	Collect query samples and wait events for tracked queries.	yes
`schema_details`	Collect schemas and tables from `information_schema`.	yes

Blocks

You can use the following blocks with database_observability.sql_server:

Block	Description	Required
`cloud_provider`	Provide Cloud Provider information.	no
`cloud_provider` > `aws`	Provide AWS database host information.	no
`cloud_provider` > `azure`	Provide Azure database host information.	no
`cloud_provider` > `gcp`	Provide GCP database host information.	no
`database_instance`	Define one database to monitor. Repeat the block to monitor several databases.	no
`database_instance` > `cloud_provider`	Provide Cloud Provider information for one database.	no
`database_instance` > `rule`	Relabel the metrics and logs of one database.	no
`clustering`	Configure the component for when Alloy is running in clustered mode.	no
`setup_consumers`	Configure the `setup_consumers` collector.	no
`setup_actors`	Configure the `setup_actors` collector.	no
`query_details`	Configure the queries collector.	no
`schema_details`	Configure the schema and table details collector.	no
`explain_plans`	Configure the explain plans collector.	no
`locks`	Configure the locks collector.	no
`query_samples`	Configure the query samples collector.	no
`health_check`	Configure the health check collector.	no
`prometheus_exporter`	Configure the embedded mysqld_exporter.	no

`cloud_provider`

When you don’t configure a cloud_provider block, Alloy attempts to detect AWS RDS and Azure SQL hosts from the data_source_name.

`aws`

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

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.

Name	Type	Description	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, for example `orders-db` for the host `orders-db.database.windows.net`.	no

`gcp`

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

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

`database_instance`

The database_instance block defines one SQL Server instance to monitor. Repeat the block to monitor several instances with a single component. The block label must be unique across database_instance blocks and identifies the instance in the component’s metrics endpoint path. Each database_instance block must also point to a distinct server: two blocks that resolve to the same host, port or named instance, and database name are rejected.

Name	Type	Description	Default	Required
`data_source_name`	`secret`	Data Source Name for the SQL Server instance to connect to.		yes

Each database_instance block can also contain a [cloud_provider][cloud_provider] block that applies to that instance only, and [rule][rule] blocks that relabel the metrics and logs of that instance only.

The metrics for each instance are served on a separate /db/<LABEL>/metrics path under the component’s HTTP endpoint, and the exported targets point to the corresponding path. When you don’t define database_instance blocks, the component serves metrics on its historical /metrics path. The metrics endpoints are served exactly at those paths: requests to any other path under the component’s HTTP endpoint return HTTP 404.

For example:

database_observability.sql_server "pool" {
  forward_to = [loki.write.logs_service.receiver]

  database_instance "orders" {
    data_source_name = sys.env("ORDERS_DSN")

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

    rule {
      target_label = "environment"
      replacement  = "production"
    }
  }

  database_instance "billing" {
    data_source_name = sys.env("BILLING_DSN")

    rule {
      target_label = "environment"
      replacement  = "staging"
    }
  }
}

In this example, the metrics and logs of the orders instance carry environment="production", and those of the billing instance carry environment="staging".

`rule`

The rule block relabels the metrics and the logs of the database_instance block that contains it. Use it to tell the data of each monitored instance apart, for example by environment, team, or tier.

Two further constraints are specific to a database_instance block:

target_label must be a literal label name: Alloy checks it against the reserved labels when it loads the configuration, so it can’t contain a capture group reference.
hashmod requires source_labels, and can’t target instance: hashing the empty value gives every database the same result, and hashing into instance buckets several databases onto one value even when the source is present.

Caution
A relabeling rule that computes an empty value removes its target label instead of setting it, and the default replacement of "$1" computes an empty value when a rule has no source_labels. So rule { target_label = "environment" } removes environment rather than setting it, and Alloy rejects it. Always set replacement alongside a target_label.

Alloy can only reject such a rule where the outcome is certain. A rule that reads source_labels depends on the labels present at runtime, so a missing or misspelled source label still removes the target label, except for the reserved labels and instance, which keep their previous value. Only removal is prevented: a rule that computes a non-empty value still overwrites those labels, which is why hashmod can’t target instance at all.

You can use the hashmod, labeldrop, lowercase, replace, and uppercase actions. The rest aren’t supported:

drop, dropequal, keep, and keepequal filter rather than label, and filtering means two different things on the two signal paths. Dropping a metrics target stops the database exporting metrics entirely, whereas dropping a log entry discards one line. To filter one database’s logs, use a loki.relabel component on the receiver named in forward_to, with a drop rule that matches that database’s instance or server_id. Every database the component monitors forwards to the same receivers, so the rule has to identify the one it applies to. To filter one database’s metrics, use a discovery.relabel component on the component’s exported targets.
labelmap builds label names from replacement at runtime, so Alloy can’t check them against the reserved labels when it loads the configuration.
labelkeep removes every label its regex doesn’t match, so a rule that preserves the reserved labels would have to match all of them. Use labeldrop to remove specific labels instead.

Because the rules run after the component’s own labels, and those are protected, a labeldrop rule can only remove a label that an earlier rule in the same block created.

Reserved labels

A rule can’t write to the following labels, and a labeldrop regular expression can’t match them:

Both metrics and logs: job and server_id.
Logs only: engine and op.
Metrics only: provider_name, provider_region, provider_account, __address__, __scheme__, and __metrics_path__.

Labels set on only one signal path

`clustering`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables distributing instances with other cluster nodes.	`false`	yes

When Alloy is using clustering, and enabled is set to true, then this database_observability.sql_server component instance opts-in to distributing its configured instances between all cluster nodes.

Clustering assumes that all cluster nodes are running with the same configuration file. All component instances opting in to clustering use the instance key of each configured instance, <host>:<port>/<database>, and a consistent hashing algorithm to determine ownership of each instance between the cluster peers. Each peer then only collects from the subset of instances it’s responsible for, and only exports the targets of those instances, so prometheus.scrape components on the same node scrape exactly the instances the node owns. When a node joins or leaves the cluster, every peer recalculates ownership: expect a short gap or a brief duplicate collection for an instance while its ownership moves. While the cluster isn’t yet ready to admit traffic, for example while it’s still forming and waiting for the minimum cluster size, the component doesn’t collect from any instance.

Clustering is also useful with a single instance: when several cluster nodes run an identical configuration, exactly one node collects from the instance at a time, which gives you a highly available setup without duplicate collection.

If Alloy is not running in clustered mode, then the block is a no-op and database_observability.sql_server collects from every configured instance.

`explain_plans`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to check for a changed execution plan.	`"1m"`	no

The explain_plans collector reads the execution plan Query Store already captured for each query tracked by the query_metrics collector. It doesn’t compile or run a fresh plan. Only queries that query_metrics is currently tracking are eligible. When query_metrics is disabled, explain_plans produces no output.

The collector checks for a changed plan every collect_interval. It forwards a log entry only when the plan’s shape has changed since the last entry. It also forwards a log entry when 30 minutes have passed since the last entry. This keeps log volume low and ensures a fresh entry at least every 30 minutes.

`health_check`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to run health checks.	`"1h"`	no

The health_check collector periodically verifies that the login has the required grants (VIEW DEFINITION, plus VIEW DATABASE STATE or its SQL Server 2022+ equivalent VIEW DATABASE PERFORMANCE STATE) and that Query Store is enabled and populated, on every database the login can access on the instance. Each check emits a log entry with op="health_status" and a check field identifying it: AlloyVersion, RequiredGrantsPresent, QueryStoreEnabled, or QueryStoreHasRows.

RequiredGrantsPresent and QueryStoreEnabled pass only when true on every database the login can access; when they fail, the log entry’s value lists the non-compliant databases. QueryStoreHasRows passes as soon as any accessible database has Query Store data, since it’s expected for a low-traffic database to have none.

`query_details`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect query text from Query Store.	`"1m"`	no

The query_details collector reads Query Store query text for the database selected in the data_source_name, not every database on the instance.

`query_metrics`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect metrics from Query Store.	`"1m"`	no
`statements_limit`	`int`	Maximum number of queries to track, ranked by recent duration.	`50`	no
`statements_lookback`	`duration`	Only queries executed within this window are eligible for tracking.	`"1h"`	no

The query_metrics collector reads Query Store for the database selected in the data_source_name, not every database on the instance. Configure the data_source_name to select a user database that has Query Store enabled. When the connected database is a system database such as master, or Query Store is disabled or read-only, the collector skips collection and remains healthy.

The login requires VIEW DATABASE STATE on the connected database. On SQL Server 2022 and later, VIEW DATABASE PERFORMANCE STATE is also sufficient.

`query_samples`

Name	Type	Description	Default	Required
`collect_interval`	`duration`	How frequently to collect query samples.	`"10s"`	no
`disable_query_redaction`	`bool`	Collect unredacted SQL query text (might include parameters).	`false`	no

The query_samples collector only collects requests whose query hash is tracked by the query_metrics collector.

The collector polls live requests and can miss queries shorter than collect_interval, wait events that start and finish between collections, and a query’s first execution before Query Store admits its hash. For completed requests, the emitted resource counters contain the values from the final observation and can omit work performed after that observation.

The login requires VIEW SERVER STATE on SQL Server 2019 and earlier. On SQL Server 2022 and later, VIEW SERVER PERFORMANCE STATE is also sufficient. Azure SQL Database can restrict the dynamic management views to the current session. In that case, the collector can’t observe other sessions.

`schema_details`

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

The collector scans every database that the login can access on the instance and collects schema details from each. Only databases where the login has CONNECT access to catalog views are collected.

Example

database_observability.sql_server "orders_db" {
  data_source_name = "sqlserver://user:pass@server:1433"
  forward_to       = [loki.write.logs_service.receiver]
}

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_LOGS_URL>: The URL for your Grafana Cloud hosted logs.
<GRAFANA_CLOUD_HOSTED_LOGS_ID>: The user ID for your Grafana Cloud hosted logs.
<GRAFANA_CLOUD_RW_API_KEY>: Your Grafana Cloud API key.

Compatible components

database_observability.sql_server can accept arguments from the following components:

Components that export Targets
Components that export Loki LogsReceiver

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

Components that consume Targets

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.