Connect trace context with database commands

This guide describes how to extend database telemetry with trace context propagation and query parameter capture using OpenTelemetry for .NET.

Check Compatibility and Requirements

Before enabling trace context propagation or query parameter tracing, review the required runtime, configuration, and database conditions. These prerequisites ensure that OpenTelemetry features can operate correctly and safely in your environment.

Runtime Compatibility

Trace context propagation and query parameter tracing are supported only under specific runtime conditions. The following constraints apply at the .NET runtime level:

Only supported on .NET runtimes.
Requires use of CommandType.Text for database commands.
Applies exclusively to applications using the System.Data.SqlClient or Microsoft.Data.SqlClient libraries. See Requirements for .NET instrumentation for full compatibility details.

Environment Variables

To configure trace context propagation in .NET applications, use the following environment variable:

Table 1. Environment Variable Configuration
Variable Name	Default Value	Description
`OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_TRACE_CONTEXT_PROPAGATION`	false	Enables trace context propagation.

Note: The variable is disabled by default and must be explicitly set to true to activate the corresponding feature.

Warning: This feature is experimental and may change or be removed in future releases. Use with caution in production environments.

Enable Trace Context Propagation

To propagate trace context to the database, set the following environment variable:

OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_TRACE_CONTEXT_PROPAGATION=true

This uses the SET CONTEXT_INFO command to attach traceparent information to the current connection. This results in an additional round-trip to the database.

Note: This feature is useful for linking database activity to distributed traces, but may impact performance due to the extra round-trip. For guidance on analyzing database spans or correlating SQL activity with traces, refer to the Splunk APM documentation.

CAUTION: Trace context propagation relies on database-specific features. The target database must support SET CONTEXT_INFO, and enabling this feature introduces an additional round-trip per connection, which may affect performance.