OpenTelemetry.Instrumentation.SqlClient
1.12.0-beta.2
Prefix Reserved
dotnet add package OpenTelemetry.Instrumentation.SqlClient --version 1.12.0-beta.2
NuGet\Install-Package OpenTelemetry.Instrumentation.SqlClient -Version 1.12.0-beta.2
<PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.12.0-beta.2" />
<PackageVersion Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.12.0-beta.2" />
<PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" />
paket add OpenTelemetry.Instrumentation.SqlClient --version 1.12.0-beta.2
#r "nuget: OpenTelemetry.Instrumentation.SqlClient, 1.12.0-beta.2"
#:package OpenTelemetry.Instrumentation.SqlClient@1.12.0-beta.2
#addin nuget:?package=OpenTelemetry.Instrumentation.SqlClient&version=1.12.0-beta.2&prerelease
#tool nuget:?package=OpenTelemetry.Instrumentation.SqlClient&version=1.12.0-beta.2&prerelease
SqlClient Instrumentation for OpenTelemetry
Status | |
---|---|
Stability | Beta |
Code Owners | @open-telemetry/dotnet-contrib-maintainers |
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 | Versions 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. |
-
.NETFramework 4.6.2
- Microsoft.Extensions.Configuration (>= 9.0.0)
- Microsoft.Extensions.Options (>= 9.0.0)
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.12.0 && < 2.0.0)
-
.NETStandard 2.0
- Microsoft.Extensions.Configuration (>= 9.0.0)
- Microsoft.Extensions.Options (>= 9.0.0)
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.12.0 && < 2.0.0)
-
net8.0
- Microsoft.Extensions.Configuration (>= 9.0.0)
- Microsoft.Extensions.Options (>= 9.0.0)
- OpenTelemetry.Api.ProviderBuilderExtensions (>= 1.12.0 && < 2.0.0)
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 |