Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components database_observability database_observability.sql_server

database_observability.sql_server

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

Alloy Copy

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:

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:

Blocks

You can use the following blocks with database_observability.sql_server:

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.

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.

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.

explain_plans

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.

query_details

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

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

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

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

Alloy Copy

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