README.md

SqlClient Instrumentation for OpenTelemetry

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

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 OpenTelemetry.Instrumentation.SqlClient

Step 2: Enable SqlClient Instrumentation at application startup

SqlClient instrumentation must be enabled at application startup.

The following example demonstrates adding SqlClient 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 Sdk.CreateTracerProviderBuilder()
            .AddSqlClientInstrumentation()
            .AddConsoleExporter()
            .Build();
    }
}

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.

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

Advanced configuration

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

SetStoredProcedureCommandName

By default, when CommandType is CommandType.StoredProcedure this instrumentation will set the db.statement attribute to the stored procedure command name. This behavior can be disabled by setting the SetStoredProcedureCommandName to false.

The following example shows how to use SetStoredProcedureCommandName.

using Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.SetStoredProcedureCommandName = false)
    .AddConsoleExporter()
    .Build();

SetTextCommandContent

By default, when CommandType is CommandType.Text, this instrumentation will not set the db.statement attribute. This behavior can be enabled by setting SetTextCommandContent to true.

For .NET Framework, SetTextCommandContent is unavailable when using System.Data.SqlClient. It is only available when using Microsoft.Data.SqlClient. SetTextCommandContent is fully functional in .NET Core when using either System.Data.SqlClient or Microsoft.Data.SqlClient.

The following example shows how to use SetTextCommandContent.

using Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.SetTextCommandContent = true)
    .AddConsoleExporter()
    .Build();

EnableConnectionLevelAttributes

By default, EnabledConnectionLevelAttributes is disabled and this instrumentation sets the peer.service attribute to the DataSource property of the connection. If EnabledConnectionLevelAttributes is enabled, the DataSource will be parsed and the server name will be sent as the net.peer.name or net.peer.ip attribute, the instance name will be sent as the db.mssql.instance_name attribute, and the port will be sent as the net.peer.port attribute if it is not 1433 (the default port).

The following example shows how to use EnableConnectionLevelAttributes.

using Sdk.CreateTracerProviderBuilder()
    .AddSqlClientInstrumentation(
        options => options.EnableConnectionLevelAttributes = true)
    .AddConsoleExporter()
    .Build();

References

• OpenTelemetry Project