EntityFrameworkCore Instrumentation for OpenTelemetry .NET

This is an Instrumentation Library, which instruments Microsoft.EntityFrameworkCore and collects traces about outgoing requests.

Note: This component is based on the OpenTelemetry semantic conventions for metrics and 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.EntityFrameworkCore

Step 1: Install Package

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

dotnet add package --prerelease OpenTelemetry.Instrumentation.EntityFrameworkCore

Step 2: Enable EntityFrameworkCore Instrumentation at application startup

EntityFrameworkCore instrumentation must be enabled at application startup.

The following example demonstrates adding EntityFrameworkCore 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;
using OpenTelemetry.Trace;

public class Program
{
    public static void Main(string[] args)
    {
        using var tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddEntityFrameworkCoreInstrumentation()
            .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 the documentation for OpenTelemetry.Instrumentation.AspNet.

Advanced configuration

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

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddEntityFrameworkCoreInstrumentation(options =>
        {
            options.EnrichWithIDbCommand = (activity, command) =>
            {
                var stateDisplayName = $"{command.CommandType} main";
                activity.DisplayName = stateDisplayName;
                activity.SetTag("db.name", stateDisplayName);
            };
        })
        .AddConsoleExporter());

When used with OpenTelemetry.Extensions.Hosting, all configurations to EntityFrameworkInstrumentationOptions can be done in the ConfigureServices method of you applications Startup class as shown below.

// Configure
services.Configure<EntityFrameworkInstrumentationOptions>(options =>
{
    options.EnrichWithIDbCommand = (activity, command) =>
    {
        var stateDisplayName = $"{command.CommandType} main";
        activity.DisplayName = stateDisplayName;
        activity.SetTag("db.name", stateDisplayName);
    };
});

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddEntityFrameworkCoreInstrumentation()
        .AddConsoleExporter());

Filter

This option can be used to filter out activities based on the provider name and the properties of the db command object being instrumented using a Func<string, IDbCommand, bool>. The function receives a provider name and an instance of the db command and should return true if the telemetry is to be collected, and false if it should not.

The following code snippet shows how to use Filter to collect traces for stored procedures only.

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddEntityFrameworkCoreInstrumentation(options =>
        {
            options.Filter = (providerName, command) =>
            {
                return command.CommandType == CommandType.StoredProcedure;
            };
        })
        .AddConsoleExporter());

Experimental features

[!NOTE] Experimental features are not enabled by default and can only be activated with environment variables. They are subject to change or removal in future releases.

DB query parameters

The OTEL_DOTNET_EXPERIMENTAL_EFCORE_ENABLE_TRACE_DB_QUERY_PARAMETERS environment variable controls whether db.query.parameter.<key> attributes are emitted.

Query parameters may contain sensitive data, so only enable this experimental feature if your queries and/or environment are appropriate for enabling this option.

OTEL_DOTNET_EXPERIMENTAL_EFCORE_ENABLE_TRACE_DB_QUERY_PARAMETERS is implicitly false by default. When set to true, the instrumentation will set db.query.parameter.<key> attributes for each of the query parameters associated with a database command.

References

• OpenTelemetry Project