OpenTelemetry.Instrumentation.SqlClient 1.12.0-beta.2

Prefix Reserved
This is a prerelease version of OpenTelemetry.Instrumentation.SqlClient.
dotnet add package OpenTelemetry.Instrumentation.SqlClient --version 1.12.0-beta.2
                    
NuGet\Install-Package OpenTelemetry.Instrumentation.SqlClient -Version 1.12.0-beta.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.12.0-beta.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.12.0-beta.2" />
                    
Directory.Packages.props
<PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add OpenTelemetry.Instrumentation.SqlClient --version 1.12.0-beta.2
                    
#r "nuget: OpenTelemetry.Instrumentation.SqlClient, 1.12.0-beta.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package OpenTelemetry.Instrumentation.SqlClient@1.12.0-beta.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=OpenTelemetry.Instrumentation.SqlClient&version=1.12.0-beta.2&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=OpenTelemetry.Instrumentation.SqlClient&version=1.12.0-beta.2&prerelease
                    
Install as a Cake Tool

SqlClient Instrumentation for OpenTelemetry

Status
Stability Beta
Code Owners @open-telemetry/dotnet-contrib-maintainers

NuGet NuGet codecov.io

This is an Instrumentation Library, which instruments Microsoft.Data.SqlClient and System.Data.SqlClient and collects traces about database operations.

Instrumentation is not working with Microsoft.Data.SqlClient v3.* due to the issue. It was fixed in 4.0 and later.

This component is based on the OpenTelemetry semantic conventions for traces. These conventions are Experimental, and hence, this package is a pre-release. Until a stable version is released, there can be breaking changes.

Steps to enable OpenTelemetry.Instrumentation.SqlClient

Step 1: Install Package

Add a reference to the OpenTelemetry.Instrumentation.SqlClient package. Also, add any other instrumentations & exporters you will need.

dotnet add package --prerelease OpenTelemetry.Instrumentation.SqlClient

Step 2: Enable SqlClient Instrumentation at application startup

SqlClient instrumentation must be enabled at application startup.

Traces

The following example demonstrates adding SqlClient traces instrumentation to a console application. This example also sets up the OpenTelemetry Console exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application.

using OpenTelemetry.Trace;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddSqlClientInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}
Metrics

The following example demonstrates adding SqlClient metrics instrumentation to a console application. This example also sets up the OpenTelemetry Console exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application.

using OpenTelemetry.Metrics;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk.CreateMeterProviderBuilder()
            .AddSqlClientInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}
List of metrics produced

The instrumentation is implemented based on metrics semantic conventions. Currently, the instrumentation supports the following metric.

Name Instrument Type Unit Description
db.client.operation.duration Histogram s Duration of database client operations.
ASP.NET Core

For an ASP.NET Core application, adding instrumentation is typically done in the ConfigureServices of your Startup class. Refer to documentation for OpenTelemetry.Instrumentation.AspNetCore.

ASP.NET

For an ASP.NET application, adding instrumentation is typically done in the Global.asax.cs. Refer to the documentation for OpenTelemetry.Instrumentation.AspNet.

Advanced configuration

This instrumentation can be configured to change the default behavior by using SqlClientTraceInstrumentationOptions.

SetDbStatementForText

SetDbStatementForText controls whether the db.statement attribute is emitted. The behavior of SetDbStatementForText depends on the runtime used, see below for more details.

Query text may contain sensitive data, so when SetDbStatementForText is enabled the raw query text is sanitized by automatically replacing literal values with a ? character.

.NET

On .NET, SetDbStatementForText controls whether or not this instrumentation will set the db.statement attribute to the CommandText of the SqlCommand being executed when the CommandType is CommandType.Text. The db.statement attribute is always captured for CommandType.StoredProcedure because the SqlCommand.CommandText only contains the stored procedure name.

SetDbStatementForText is false by default. When set to true, the instrumentation will set db.statement attribute to the text of the SQL command being executed.

To enable capturing of SqlCommand.CommandText for CommandType.Text use the following configuration.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.SetDbStatementForText = true)
    .AddConsoleExporter()
    .Build();
.NET Framework

On .NET Framework, there is no way to determine the type of command being executed, so the SetDbStatementForText property always controls whether or not this instrumentation will set the db.statement attribute to the CommandText of the SqlCommand being executed. The CommandText could be the name of a stored procedure (when CommandType.StoredProcedure is used) or the full text of a CommandType.Text query.

SetDbStatementForText is false by default. When set to true, the instrumentation will set db.statement attribute to the text of the SQL command being executed.

To enable capturing of SqlCommand.CommandText for CommandType.Text use the following configuration.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.SetDbStatementForText = true)
    .AddConsoleExporter()
    .Build();

When using the built-in System.Data.SqlClient, only stored procedure command names will be captured. To capture query text, other command text and stored procedure command names, you need to use the Microsoft.Data.SqlClient NuGet package (v1.1+).

Enrich

Enrich is supported on .NET and .NET Core runtimes only.

This option can be used to enrich the activity with additional information from the raw SqlCommand object. The Enrich action is called only when activity.IsAllDataRequested is true. It contains the activity itself (which can be enriched), the name of the event, and the actual raw object.

Currently there is only one event name reported, "OnCustom". The actual object is Microsoft.Data.SqlClient.SqlCommand for Microsoft.Data.SqlClient and System.Data.SqlClient.SqlCommand for System.Data.SqlClient.

The following code snippet shows how to add additional tags using Enrich.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(opt => opt.Enrich
        = (activity, eventName, rawObject) =>
    {
        if (eventName.Equals("OnCustom"))
        {
            if (rawObject is SqlCommand cmd)
            {
                activity.SetTag("db.commandTimeout", cmd.CommandTimeout);
            }
        };
    })
    .Build();

Processor, is the general extensibility point to add additional properties to any activity. The Enrich option is specific to this instrumentation, and is provided to get access to SqlCommand object.

RecordException

RecordException is supported on .NET and .NET Core runtimes only.

This option can be set to instruct the instrumentation to record SqlExceptions as Activity events.

The default value is false and can be changed by the code like below.

using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.RecordException = true)
    .AddConsoleExporter()
    .Build();

Filter

Filter is supported on .NET and .NET Core runtimes only.

This option can be used to filter out activities based on the properties of the SqlCommand object being instrumented using a Func<object, bool>. The function receives an instance of the raw SqlCommand and should return true if the telemetry is to be collected, and false if it should not. The parameter of the Func delegate is of type object and needs to be cast to the appropriate type of SqlCommand, either Microsoft.Data.SqlClient.SqlCommand or System.Data.SqlClient.SqlCommand. The example below filters out all commands that are not stored procedures.

using var traceProvider = Sdk.CreateTracerProviderBuilder()
   .AddSqlClientInstrumentation(
       opt =>
       {
           opt.Filter = cmd =>
           {
               if (cmd is SqlCommand command)
               {
                   return command.CommandType == CommandType.StoredProcedure;
               }

               return false;
           };
       })
   .AddConsoleExporter()
   .Build();
{

Trace Context Propagation

Only CommandType.Text commands are supported for trace context propagation. Only .NET runtimes are supported.

Database trace context propagation can be enabled by setting OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_TRACE_CONTEXT_PROPAGATION environment variable to true. This uses the SET CONTEXT_INFO command to set traceparentinformation for the current connection, which results in an additional round-trip to the database.

References

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 is compatible.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (82)

Showing the top 5 NuGet packages that depend on OpenTelemetry.Instrumentation.SqlClient:

Package Downloads
OpenTelemetry.AutoInstrumentation.Runtime.Managed

Managed components used by the OpenTelemetry.AutoInstrumentation project.

Grafana.OpenTelemetry.Base

Minimal Grafana distribution of OpenTelemetry .NET

Honeycomb.OpenTelemetry.CommonInstrumentations

Honeycomb's OpenTelemetry common instrumentations package. Adds support for many common instrumentation libraries for you.

GreatUtilities.Web

Essencial tools to agile development.

ShtrihM.Wattle3.OpenTelemetry

Framework for creating high-performance servers with domain object models.

GitHub repositories (8)

Showing the top 8 popular GitHub repositories that depend on OpenTelemetry.Instrumentation.SqlClient:

Repository Stars
Azure/azure-sdk-for-net
This repository is for active development of the Azure SDK for .NET. For consumers of the SDK we recommend visiting our public developer docs at https://learn.microsoft.com/dotnet/azure/ or our versioned developer docs at https://azure.github.io/azure-sdk-for-net.
DuendeSoftware/products
The most flexible and standards-compliant OpenID Connect and OAuth 2.x framework for ASP.NET Core
thangchung/clean-architecture-dotnet
🕸 Yet Another .NET Clean Architecture, but for Microservices project. It uses Minimal Clean Architecture with DDD-lite, CQRS-lite, and just enough Cloud-native patterns apply on the simple eCommerce sample and run on Tye with Dapr extension 🍻
CodeMazeBlog/CodeMazeGuides
The main repository for all the Code Maze guides
Aguafrommars/TheIdServer
OpenID/Connect, OAuth2, WS-Federation and SAML 2.0 server based on Duende IdentityServer and ITFoxtec Identity SAML 2.0 with its admin UI
damikun/trouble-training
FullStack DDD/CQRS with GraphQL workshop including distributed tracing and monitoring. This shows the configuration from React frontend to .Net backend.
mburumaxwell/dependabot-azure-devops
Tools for updating dependencies in Azure DevOps repositories using https://dependabot.com
Azure/modern-web-app-pattern-dotnet
The Modern Web App Pattern is a set of objectives to help you apply an iterative change to modernize a cloud deployed monolith. This content builds on the Reliable Web App. This repo contains a reference implementation of a Modern Web App for .NET.
Version Downloads Last Updated
1.12.0-beta.2 0 7/15/2025
1.12.0-beta.1 384,421 5/6/2025
1.11.0-beta.2 1,158,413 3/5/2025
1.11.0-beta.1 610,956 1/27/2025
1.10.0-beta.1 477,980 12/9/2024
1.9.0-beta.1 8,032,945 6/17/2024
1.8.0-beta.1 4,216,675 4/4/2024
1.7.0-beta.1 2,143,249 2/10/2024
1.6.0-beta.3 2,911,562 11/17/2023
1.6.0-beta.2 715,180 10/27/2023
1.5.1-beta.1 4,204,254 7/21/2023
1.5.0-beta.1 1,122,089 6/6/2023
1.0.0-rc9.14 7,349,910 2/24/2023
1.0.0-rc9.13 376,040 2/11/2023
1.0.0-rc9.12 431,069 2/2/2023
1.0.0-rc9.11 241,025 1/9/2023
1.0.0-rc9.10 465,882 12/12/2022
1.0.0-rc9.9 779,256 11/7/2022
1.0.0-rc9.8 418,428 10/17/2022
1.0.0-rc9.7 156,860 9/30/2022
1.0.0-rc9.6 623,003 8/18/2022
1.0.0-rc9.5 628,122 8/3/2022
1.0.0-rc9.4 2,615,700 6/3/2022
1.0.0-rc9.3 744,781 4/20/2022
1.0.0-rc9.2 225,245 4/13/2022
1.0.0-rc9.1 290,857 3/30/2022
1.0.0-rc9 1,514,091 2/3/2022
1.0.0-rc8 2,318,012 10/8/2021
1.0.0-rc7 922,049 7/13/2021
1.0.0-rc6 177,685 6/26/2021
1.0.0-rc5 319,583 6/9/2021
1.0.0-rc4 107,672 4/23/2021
1.0.0-rc3 191,381 3/19/2021
1.0.0-rc2 258,657 1/30/2021
1.0.0-rc10 14,553 3/5/2022
1.0.0-rc1.1 165,784 11/18/2020
0.8.0-beta.1 9,171 11/5/2020
0.7.0-beta.1 6,580 10/16/2020
0.6.0-beta.1 51,968 9/16/2020
0.5.0-beta.2 4,320 8/28/2020
0.4.0-beta.2 62,780 7/25/2020
0.3.0-beta.1 528 7/23/2020