Sqlserver Receiver

Available in: contrib Maintainers: @sincejune, @crobert-1 Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Required Permissions

Windows Performance Counters

Make sure to run the collector as administrator in order to collect all performance counters for metrics.

Direct Connection

When configured to directly connect to the SQL Server instance, the user must have the following permissions:

At least one of the following permissions:

CREATE DATABASE
ALTER ANY DATABASE
VIEW ANY DATABASE

Permission to view server state:
- SQL Server pre-2022: VIEW SERVER STATE
- SQL Server 2022 and later: VIEW SERVER PERFORMANCE STATE

Configuration

The following is a generic configuration that can be used for the default logs and metrics scraped by the SQL Server receiver. A basic explanation on some of the fields has also been provided. For more information, please reference the following section.

sqlserver:
  collection_interval: 10s                     # interval for overall collection
  instance_name: CustomInstance
  username: myusername
  password: mypassword
  server: sqlserver.address
  port: 1433
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true
  top_query_collection:                        # this collection exports the most expensive queries as logs
    lookback_time: 60s                         # which time window should we look for the top queries
    max_query_sample_count: 1000               # maximum number query we store in cache for top queries.
    top_query_count: 250                       # The maximum number of active queries to report in a single run.
    collection_interval: 60s                   # collection interval for top query collection specifically
  query_sample_collection:                     # this collection exports the currently (relate to the query time) executing queries as logs
    max_rows_per_query: 100                    # the maximum number of samples to return for one single query.

The following settings are optional:

collection_interval (default = 10s): The interval at which metrics should be emitted by this receiver.
instance_name (optional): The instance name identifies the specific SQL Server instance being monitored. If unspecified, metrics will be scraped from all instances. If configured, the computer_name must also be set when running on Windows.

Direct connection options (optional, but all must be specified to enable):

username: The username used to connect to the SQL Server instance.
password: The password used to connect to the SQL Server instance.
server: IP Address or hostname of SQL Server instance to connect to.
port: Port of the SQL Server instance to connect to.

For finer control over the direct connection use the datasource, a.k.a. the “connection string”, instead. Note: it can’t be used in conjunction with the username, password, server and port options. Windows-specific options:

computer_name (optional): The computer name identifies the SQL Server name or IP address of the computer being monitored. If specified, instance_name is also required to be defined. This option is ignored in non-Windows environments.

Top-Query collection specific options (only useful when top-query collection are enabled):

lookback_time (optional, example = 60s, default = 2 * collection_interval): The time window (in second) in which to query for top queries.
- Queries that were finished execution outside the lookback window are not included in the collection. Increasing the lookback window (in seconds) will be useful for capturing long-running queries.
max_query_sample_count (optional, example = 5000, default = 1000): The maximum number of records to fetch in a single run.
top_query_count: (optional, example = 100, default = 250): The maximum number of active queries to report (to the next consumer) in a single run.
collection_interval: (optional, default = 60s): The interval at which top queries should be emitted by this receiver.
- This value can only guarantee that the top queries are collected at most once in this interval.
  - For instance, you have global collection_interval as 10s and top_query_collection.collection_interval as 60s.
    - In this case, the default receiver scraper will still try to run in every 10 seconds.
    - However, the top queries collection will only run after 60 seconds have passed since the last collection.
  - For instance, you have global collection_interval as 10s and top_query_collection.collection_interval as 5s.
    - In this case, top_query_collection.collection_internal will make no effects to the collection

Query sample collection related options (only useful when query sample is enabled)

max_rows_per_query: (optional, default = 100) use this to limit rows returned by the sampling query. Example:

    receivers:
      sqlserver:
        collection_interval: 10s
      sqlserver/1:
        collection_interval: 5s
        username: sa
        password: securepassword
        server: 0.0.0.0
        port: 1433

When a named instance is used on Windows, a computer name and an instance name must be specified. Example with named instance:

    receivers:
      sqlserver:
        collection_interval: 10s
        computer_name: CustomServer
        instance_name: CustomInstance
        resource_attributes:
          sqlserver.computer.name:
            enabled: true
          sqlserver.instance.name:
            enabled: true

The full list of settings exposed for this receiver are documented in config.go with detailed sample configurations in testdata/config.yaml. Top query collection enabled:

    receivers:
      sqlserver:
        collection_interval: 5s
        username: sa
        password: securepassword
        server: 0.0.0.0
        port: 1433
        top_query_collection:
          lookback_time: 60s
          max_query_sample_count: 1000
          top_query_count: 200
        query_sample_collection:
          max_rows_per_query: 1450

Feature Gate

A new feature gate was added in v0.129.0 for removing the server.address and server.port resource attributes, as they are not identified as resources attributes in the semantic conventions. To enable it, pass the following argument to the Collector:

--feature-gates=receiver.sqlserver.RemoveServerResourceAttribute

Metrics

Details about the metrics produced by this receiver can be found in documentation.md

Logs

Details about the logs produced by this receiver can be found in logs-documentation.md

Known issues

SQL Server docker users may run into an issue that the collector fails to parse certificate from server due to x509: negative serial number. That’s because we adopted Go 1.23 starting from contrib v0.121.0:

Before Go 1.23, ParseCertificate accepted certificates with negative serial numbers. This behavior can be restored by including “x509negativeserial=1” in the GODEBUG environment variable. references:

Troubleshooting

`service.instance.id` is `unknown:1433`

In a rare case, the service.instance.id resource attribute is set to unknown:1433. This is because the receiver is unable to parse and compute the service.instance.id resource attribute. You can file an issue that includes your configuration to help us investigate the issue.

Metrics

Metric Name	Description	Unit	Type	Attributes
✅ `sqlserver.batch.request.rate`	Number of batch requests received by SQL Server.	{requests}/s	Gauge
✅ `sqlserver.batch.sql_compilation.rate`	Number of SQL compilations needed.	{compilations}/s	Gauge
✅ `sqlserver.batch.sql_recompilation.rate`	Number of SQL recompilations needed.	{compilations}/s	Gauge
❌ `sqlserver.computer.uptime`	Computer uptime.	{seconds}	Gauge
❌ `sqlserver.cpu.count`	Number of CPUs.	{CPUs}	Gauge
❌ `sqlserver.database.backup_or_restore.rate`	Total number of backups/restores.	“{backups_or_restores}/s”	Gauge
❌ `sqlserver.database.count`	The number of databases	{databases}	Gauge	database.status
❌ `sqlserver.database.execution.errors`	Number of execution errors.	“{errors}”	Gauge
❌ `sqlserver.database.full_scan.rate`	The number of unrestricted full table or index scans.	{scans}/s	Gauge
❌ `sqlserver.database.io`	The number of bytes of I/O on this file.	By	Counter	physical_filename, logical_filename, file_type, direction
❌ `sqlserver.database.latency`	Total time that the users waited for I/O issued on this file.	s	Counter	physical_filename, logical_filename, file_type, direction
❌ `sqlserver.database.operations`	The number of operations issued on the file.	{operations}	Counter	physical_filename, logical_filename, file_type, direction
❌ `sqlserver.database.tempdb.space`	Total free space in temporary DB.	“KB”	UpDownCounter	tempdb.state
❌ `sqlserver.database.tempdb.version_store.size`	TempDB version store size.	“KB”	Gauge
❌ `sqlserver.deadlock.rate`	Total number of deadlocks.	“{deadlocks}/s”	Gauge
❌ `sqlserver.index.search.rate`	Total number of index searches.	“{searches}/s”	Gauge
❌ `sqlserver.lock.timeout.rate`	Total number of lock timeouts.	“{timeouts}/s”	Gauge
❌ `sqlserver.lock.wait.count`	Cumulative count of lock waits that occurred.	{wait}	Counter
✅ `sqlserver.lock.wait.rate`	Number of lock requests resulting in a wait.	{requests}/s	Gauge
✅ `sqlserver.lock.wait_time.avg`	Average wait time for all lock requests that had to wait.	ms	Gauge
❌ `sqlserver.login.rate`	Total number of logins.	“{logins}/s”	Gauge
❌ `sqlserver.logout.rate`	Total number of logouts.	“{logouts}/s”	Gauge
❌ `sqlserver.memory.grants.pending.count`	Total number of memory grants pending.	“{grants}”	UpDownCounter
❌ `sqlserver.memory.usage`	Total memory in use.	“KB”	UpDownCounter
❌ `sqlserver.os.wait.duration`	Total wait time for this wait type	s	Counter	wait.category, wait.type
❌ `sqlserver.page.buffer_cache.free_list.stalls.rate`	Number of free list stalls.	“{stalls}/s”	Gauge
✅ `sqlserver.page.buffer_cache.hit_ratio`	Pages found in the buffer pool without having to read from disk.	%	Gauge
✅ `sqlserver.page.checkpoint.flush.rate`	Number of pages flushed by operations requiring dirty pages to be flushed.	{pages}/s	Gauge
✅ `sqlserver.page.lazy_write.rate`	Number of lazy writes moving dirty pages to disk.	{writes}/s	Gauge
✅ `sqlserver.page.life_expectancy`	Time a page will stay in the buffer pool.	s	Gauge	performance_counter.object_name
❌ `sqlserver.page.lookup.rate`	Total number of page lookups.	“{lookups}/s”	Gauge
✅ `sqlserver.page.operation.rate`	Number of physical database page operations issued.	{operations}/s	Gauge	page.operations
✅ `sqlserver.page.split.rate`	Number of pages split as a result of overflowing index pages.	{pages}/s	Gauge
❌ `sqlserver.processes.blocked`	The number of processes that are currently blocked	{processes}	Gauge
❌ `sqlserver.replica.data.rate`	Throughput rate of replica data.	By/s	Gauge	replica.direction
❌ `sqlserver.resource_pool.disk.operations`	The rate of operations issued.	{operations}/s	Gauge	direction
❌ `sqlserver.resource_pool.disk.throttled.read.rate`	The number of read operations that were throttled in the last second	{reads}/s	Gauge
❌ `sqlserver.resource_pool.disk.throttled.write.rate`	The number of write operations that were throttled in the last second	{writes}/s	Gauge
❌ `sqlserver.table.count`	The number of tables.	“{tables}”	UpDownCounter	table.state, table.status
❌ `sqlserver.transaction.delay`	Time consumed in transaction delays.	ms	UpDownCounter
❌ `sqlserver.transaction.mirror_write.rate`	Total number of mirror write transactions.	“{transactions}/s”	Gauge
✅ `sqlserver.transaction.rate`	Number of transactions started for the database (not including XTP-only transactions).	{transactions}/s	Gauge
✅ `sqlserver.transaction.write.rate`	Number of transactions that wrote to the database and committed.	{transactions}/s	Gauge
✅ `sqlserver.transaction_log.flush.data.rate`	Total number of log bytes flushed.	By/s	Gauge
✅ `sqlserver.transaction_log.flush.rate`	Number of log flushes.	{flushes}/s	Gauge
✅ `sqlserver.transaction_log.flush.wait.rate`	Number of commits waiting for a transaction log flush.	{commits}/s	Gauge
✅ `sqlserver.transaction_log.growth.count`	Total number of transaction log expansions for a database.	{growths}	Counter
✅ `sqlserver.transaction_log.shrink.count`	Total number of transaction log shrinks for a database.	{shrinks}	Counter
✅ `sqlserver.transaction_log.usage`	Percent of transaction log space used.	%	Gauge
✅ `sqlserver.user.connection.count`	Number of users connected to the SQL Server.	{connections}	Gauge

Attributes

Attribute Name	Description	Type	Values
`client.address`	Hostname or address of the client.	string
`client.port`	TCP port used by the client.	int
`database.status`	The current status of a database	string	`online`, `restoring`, `recovering`, `pending_recovery`, `suspect`, `offline`
`db.namespace`	The database name.	string
`db.query.text`	The text of the database query being executed.	string
`db.system.name`	The database management system (DBMS) product as identified by the client instrumentation.	string
`direction`	The direction of flow of bytes or operations.	string	`read`, `write`
`file_type`	The type of file being monitored.	string
`logical_filename`	The logical filename of the file being monitored.	string
`network.peer.address`	IP address of the peer client.	string
`network.peer.port`	TCP port used by the peer client.	int
`type`	The page operation types.	string	`read`, `write`
`performance_counter.object_name`	Category to which this counter belongs	string
`physical_filename`	The physical filename of the file being monitored.	string
`replica.direction`	The direction of flow of bytes for replica.	string	`transmit`, `receive`
`server.address`	The network address of the server hosting the database.	string
`server.port`	The port number on which the server is listening.	int
`sqlserver.blocking.start_time`	Timestamp of when the current blocking wait began (ISO 8601 format).	string
`sqlserver.blocking_session_id`	Session ID that is blocking the current session. 0 if none.	int
`sqlserver.command`	SQL command type being executed.	string
`sqlserver.context_info`	Context information for the session, represented as a hexadecimal string.	string
`sqlserver.cpu_time`	CPU time consumed by the query, in seconds.	double
`sqlserver.deadlock_priority`	Deadlock priority value for the session.	int
`sqlserver.estimated_completion_time`	Estimated time remaining for the request to complete, in seconds.	double
`sqlserver.execution_count`	Number of times that the plan has been executed since it was last compiled, reported in delta value.	int
`sqlserver.lock_timeout`	Lock timeout value in seconds.	double
`sqlserver.logical_reads`	Number of logical reads (data read from cache/memory).	int
`sqlserver.open_transaction_count`	Number of transactions currently open in the session.	int
`sqlserver.percent_complete`	Percentage of work completed.	double
`sqlserver.procedure_execution_count`	Number of times that the procedure has been executed since it was last compiled, reported in delta value.	int
`sqlserver.procedure_id`	The SQL Server ID of the stored procedure, if any	string
`sqlserver.procedure_name`	The name of the stored procedure, if any	string
`sqlserver.query_hash`	Binary hash value calculated on the query and used to identify queries with similar logic, reported in the HEX format.	string
`sqlserver.query_plan`	The query execution plan used by the SQL Server.	string
`sqlserver.query_plan_hash`	Binary hash value calculated on the query execution plan and used to identify similar query execution plans, reported in the HEX format.	string
`sqlserver.query_start`	Timestamp of when the SQL query started (ISO 8601 format).	string
`sqlserver.reads`	Number of physical reads performed by the query.	int
`sqlserver.request_status`	Status of the request (e.g., running, suspended).	string
`sqlserver.row_count`	Number of rows affected or returned by the query.	int
`sqlserver.session_id`	ID of the SQL Server session.	int
`sqlserver.session_status`	Status of the session (e.g., running, sleeping).	string
`sqlserver.total_elapsed_time`	Total elapsed time for completed executions of this plan, reported in delta seconds.	double
`sqlserver.total_grant_kb`	The total amount of reserved memory grant in KB this plan received since it was compiled, reported in delta value.	int
`sqlserver.total_logical_reads`	Total number of logical reads performed by executions of this plan since it was compiled, reported in delta value.	int
`sqlserver.total_logical_writes`	Total number of logical writes performed by executions of this plan since it was compiled, reported in delta value.	int
`sqlserver.total_physical_reads`	Total number of physical reads performed by executions of this plan since it was compiled, reported in delta value.	int
`sqlserver.total_rows`	Total number of rows returned by the query, reported in delta value.	int
`sqlserver.total_worker_time`	Total amount of CPU time that was consumed by executions of this plan since it was compiled, reported in delta seconds.	double
`sqlserver.transaction_id`	Unique ID of the active transaction.	int
`sqlserver.transaction_isolation_level`	Transaction isolation level used in the session. Represented as numeric constant.	int
`sqlserver.wait.resource.id`	SQL Server identifier for the locked or waited-on resource, if available.	string
`sqlserver.wait.resource.type`	SQL Server type of the locked or waited-on resource, if available.	string
`sqlserver.wait_resource`	The resource for which the session is waiting.	string
`sqlserver.wait_time`	Duration in seconds the request has been waiting.	double
`sqlserver.wait_type`	Type of wait encountered by the request. Empty if none.	string
`sqlserver.writes`	Number of writes performed by the query.	int
`table.state`	The state of the table.	string	`active`, `inactive`
`table.status`	The status of the table.	string	`temporary`, `permanent`
`tempdb.state`	The status of the tempdb space usage.	string	`free`, `used`
`user.name`	Login name associated with the SQL Server session.	string
`wait.category`	Category of the reason for a wait.	string
`wait.type`	Type of the wait, view WaitTypes documentation for more information.	string

Resource Attributes

Attribute Name	Description	Type	Enabled
`host.name`	The host name of SQL Server	string	✅
`server.address`	Name of the database host.	string	❌
`server.port`	Server port number.	int	❌
`service.instance.id`	A unique identifier of the SQL Server instance in the format host:port. This resource attribute is only available when the receiver is configured to directly connect to SQL Server.	string	✅
`sqlserver.computer.name`	The name of the SQL Server instance being monitored.	string	❌
`sqlserver.database.name`	The name of the SQL Server database.	string	✅
`sqlserver.instance.name`	The name of the SQL Server instance being monitored.	string	❌

Configuration

Example Configuration

sqlserver:
  collection_interval: 10s

sqlserver/named:
  collection_interval: 10s
  computer_name: CustomServer
  instance_name: CustomInstance
  resource_attributes:
    sqlserver.computer.name:
      enabled: true
    sqlserver.instance.name:
      enabled: true
    server.port:
      enabled: true
    server.address:
      enabled: true
    service.instance.id:
      enabled: false
  top_query_collection:
    lookback_time: 60s
    max_query_sample_count: 1000
    top_query_count: 200
    collection_interval: 80s
  query_sample_collection:
    max_rows_per_query: 1450
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true

Last generated: 2026-04-20

Documentation Index

​Sqlserver Receiver

​Supported Telemetry

​Overview

​Required Permissions

​Windows Performance Counters

​Direct Connection

​Configuration

​Feature Gate

​Metrics

​Logs

​Known issues

​Troubleshooting

​service.instance.id is unknown:1433

​Metrics

​Attributes

​Resource Attributes

​Configuration

​Example Configuration

Sqlserver Receiver

Supported Telemetry

Overview

Required Permissions

Windows Performance Counters

Direct Connection

Configuration

Feature Gate

Metrics

Logs

Known issues

Troubleshooting

`service.instance.id` is `unknown:1433`

Metrics

Attributes

Resource Attributes

Configuration

Example Configuration