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

Reference

Components

database_observability

database_observability.sql_server

Experimental Open source

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

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
`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
`explain_plans`	Configure the query execution plan collector.	no
`query_details`	Configure the Query Store query text collector.	no
`query_metrics`	Configure the Query Store metrics collector.	no
`schema_details`	Configure the schema and table details collector.	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.

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

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

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

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

Was this page helpful?

Suggest an edit in GitHub

Create a GitHub issue

Email docs@grafana.com

Help and support

Community

`database_observability.sql_server`

Usage

Arguments