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

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow database_observabilitybreadcrumb arrow 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

Alloy 
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:

NameTypeDescriptionDefaultRequired
data_source_namesecretData Source Name for the SQL Server instance to connect to.yes
forward_tolist(LogsReceiver)Where to forward log entries after processing.yes
targetslist(map(string))List of external targets to scrape.no
disable_collectorslist(string)A list of collectors to disable from the default set.no
enable_collectorslist(string)A list of collectors to enable on top of the default set.no
exclude_schemaslist(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_databaseslist(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:

NameDescriptionEnabled by default
schema_detailsCollect schemas and tables from information_schema.yes
query_metricsCollect per-query executions, errors, and duration counters from Query Store.yes

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.

NameTypeDescriptionDefaultRequired
arnstringThe ARN associated with the database under observation.yes

azure

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

NameTypeDescriptionDefaultRequired
subscription_idstringThe Subscription ID for your Azure account.yes
resource_groupstringThe Resource Group that holds the database resource.yes
server_namestringThe 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.

NameTypeDescriptionDefaultRequired
connection_namestringThe Cloud SQL instance connection name in the format project:region:instance, for example my-project:us-central1:my-db.yes

schema_details

NameTypeDescriptionDefaultRequired
collect_intervaldurationHow 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.

query_metrics

NameTypeDescriptionDefaultRequired
collect_intervaldurationHow frequently to collect metrics from Query Store."1m"no
statements_limitintMaximum number of queries to track, ranked by recent duration.50no
statements_lookbackdurationOnly queries executed within this window are eligible for tracking."1h"no

The query_metrics collector reads [Query Store][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.

The collector exports the following counters, each labeled with database and query_hash:

MetricDescription
database_observability_query_executions_totalTotal number of query executions observed while the query is selected.
database_observability_query_errors_totalTotal number of failed executions (aborted or exception) observed while the query is selected.
database_observability_query_duration_seconds_totalTotal query execution duration in seconds observed while the query is selected.

Example

Alloy 
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:

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

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.