OpenTelemetry.Instrumentation.AspNetCore 1.13.0

ASP.NET Core Instrumentation for OpenTelemetry .NET

This is an Instrumentation Library, which instruments ASP.NET Core and collect metrics and traces about incoming web requests. This instrumentation also collects traces from incoming gRPC requests using Grpc.AspNetCore. Instrumentation support for gRPC server requests is supported via an experimental feature flag.

This component is based on the v1.23 of http semantic conventions. For details on the default set of attributes that are added, checkout Traces and Metrics sections below.

Steps to enable OpenTelemetry.Instrumentation.AspNetCore

Step 1: Install Package

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

dotnet add package OpenTelemetry.Instrumentation.AspNetCore

Step 2: Enable ASP.NET Core Instrumentation at application startup

ASP.NET Core instrumentation must be enabled at application startup. This is typically done in the ConfigureServices of your Startup class. Both examples below enables OpenTelemetry by calling AddOpenTelemetry() on IServiceCollection. This extension method requires adding the package OpenTelemetry.Extensions.Hosting to the application. This ensures instrumentations are disposed when the host is shutdown.

Traces

The following example demonstrates adding ASP.NET Core instrumentation with the extension method WithTracing() on OpenTelemetryBuilder. then extension method AddAspNetCoreInstrumentation() on TracerProviderBuilder to the application. This example also sets up the Console Exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application.

using Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Trace;

public void ConfigureServices(IServiceCollection services)
{
    services.AddOpenTelemetry()
        .WithTracing(builder => builder
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter());
}

Following list of attributes are added by default on activity. See http-spans for more details about each individual attribute:

• error.type
• http.request.method
• http.request.method_original
• http.response.status_code
• http.route
• network.protocol.version
• user_agent.original
• server.address
• server.port
• url.path
• url.query - By default, the values in the query component are replaced with the text Redacted. For example, ?key1=value1&key2=value2 becomes ?key1=Redacted&key2=Redacted. You can disable this redaction by setting the environment variable OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION to true.
• url.scheme

Enrich Api can be used if any additional attributes are required on activity.

Metrics

The following example demonstrates adding ASP.NET Core instrumentation with the extension method WithMetrics() on OpenTelemetryBuilder then extension method AddAspNetCoreInstrumentation() on MeterProviderBuilder to the application. This example also sets up the Console Exporter, which requires adding the package OpenTelemetry.Exporter.Console to the application.

using Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Metrics;

public void ConfigureServices(IServiceCollection services)
{
    services.AddOpenTelemetry()
        .WithMetrics(builder => builder
            .AddAspNetCoreInstrumentation()
            .AddConsoleExporter());
}

Following list of attributes are added by default on http.server.request.duration metric. See http-metrics for more details about each individual attribute. .NET8.0 and above supports additional metrics, see list of metrics produced for more details.

• error.type
• http.response.status_code
• http.request.method
• http.route
• network.protocol.version
• url.scheme

List of metrics produced

When the application targets .NET6.0 or .NET7.0, the instrumentation emits the following metric:

Starting from .NET8.0, metrics instrumentation is natively implemented, and the ASP.NET Core library has incorporated support for built-in metrics following the OpenTelemetry semantic conventions. The library includes additional metrics beyond those defined in the specification, covering additional scenarios for ASP.NET Core users. When the application targets .NET8.0 and newer versions, the instrumentation library automatically enables all built-in metrics by default.

Note that the AddAspNetCoreInstrumentation() extension simplifies the process of enabling all built-in metrics via a single line of code. Alternatively, for more granular control over emitted metrics, you can utilize the AddMeter() extension on MeterProviderBuilder for meters listed in built-in-metrics-aspnetcore. Using AddMeter() for metrics activation eliminates the need to take dependency on the instrumentation library package and calling AddAspNetCoreInstrumentation().

If you utilize AddAspNetCoreInstrumentation() and wish to exclude unnecessary metrics, you can utilize Views to achieve this.

Advanced configuration

Tracing

This instrumentation can be configured to change the default behavior by using AspNetCoreTraceInstrumentationOptions, which allows adding Filter, Enrich as explained below.

// TODO: This section could be refined. When used with OpenTelemetry.Extensions.Hosting, all configurations to AspNetCoreTraceInstrumentationOptions can be done in the ConfigureServices method of you applications Startup class as shown below.

// Configure
services.Configure<AspNetCoreTraceInstrumentationOptions>(options =>
{
    options.Filter = (httpContext) =>
    {
        // only collect telemetry about HTTP GET requests
        return httpContext.Request.Method.Equals("GET");
    };
});

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

Filter

This instrumentation by default collects all the incoming http requests. It allows filtering of requests by using the Filter function in AspNetCoreTraceInstrumentationOptions. This defines the condition for allowable requests. The Filter receives the HttpContext of the incoming request, and does not collect telemetry about the request if the Filter returns false or throws exception.

The following code snippet shows how to use Filter to only allow GET requests.

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddAspNetCoreInstrumentation((options) => options.Filter = httpContext =>
        {
            // only collect telemetry about HTTP GET requests
            return httpContext.Request.Method.Equals("GET");
        })
        .AddConsoleExporter());

It is important to note that this Filter option is specific to this instrumentation. OpenTelemetry has a concept of a Sampler, and the Filter option does the filtering after the Sampler is invoked.

Enrich

This instrumentation library provides EnrichWithHttpRequest, EnrichWithHttpResponse and EnrichWithException options that can be used to enrich the activity with additional information from the raw HttpRequest, HttpResponse and Exception objects respectively. These actions are called only when activity.IsAllDataRequested is true. It contains the activity itself (which can be enriched) and the actual raw object.

The following code snippet shows how to enrich the activity using all 3 different options.

services.AddOpenTelemetry()
    .WithTracing(builder => builder
        .AddAspNetCoreInstrumentation(o =>
        {
            o.EnrichWithHttpRequest = (activity, httpRequest) =>
            {
                activity.SetTag("requestProtocol", httpRequest.Protocol);
            };
            o.EnrichWithHttpResponse = (activity, httpResponse) =>
            {
                activity.SetTag("responseLength", httpResponse.ContentLength);
            };
            o.EnrichWithException = (activity, exception) =>
            {
                if (exception.Source != null)
                {
                    activity.SetTag("exception.source", exception.Source);
                }
            };
        }));

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 HttpRequest and HttpResponse.

When overriding the default settings provided by instrumentation or adding additional telemetry, it is important to consider the sequence of callbacks. Generally, it is recommended to use EnrichWithHttpResponse for any activity enrichment that does not need access to exceptions, as the instrumentation library populates all telemetry following the OTel specification before this callback. The following is the sequence in which these callbacks are executed:

1. Processor OnStart
2. EnrichWithHttpRequest
3. EnrichWithException
4. EnrichWithHttpResponse
5. Processor OnEnd

As an example, if you need to override the default DisplayName or tags set by the library you can do so as follows:

.AddAspNetCoreInstrumentation(o =>
{
  o.EnrichWithHttpResponse = (activity, response) =>
  {
      // Access request object if needed
      // response.HttpContext.Request
      activity.DisplayName = "CustomDisplayName";

      // Overrides the value
      activity.SetTag("http.route", "CustomRoute");

      // Removes the tag
      activity.SetTag("network.protocol.version", null);
  };
});

RecordException

This instrumentation automatically sets Activity Status to Error if an unhandled exception is thrown. Additionally, RecordException feature may be turned on, to store the exception to the Activity itself as ActivityEvent.

Activity duration and http.server.request.duration metric calculation

Activity.Duration and http.server.request.duration values represents the time used to handle an inbound HTTP request as measured at the hosting layer of ASP.NET Core. The time measurement starts once the underlying web host has:

• Sufficiently parsed the HTTP request headers on the inbound network stream to identify the new request.
• Initialized the context data structures such as the HttpContext.

The time ends when:

• The ASP.NET Core handler pipeline is finished executing.
• All response data has been sent.
• The context data structures for the request are being disposed.

Experimental support for gRPC requests

gRPC instrumentation can be enabled by setting OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION flag to True. The flag can be set as an environment variable or via IConfiguration as shown below.

var appBuilder = WebApplication.CreateBuilder(args);

appBuilder.Configuration.AddInMemoryCollection(
    new Dictionary<string, string?>
    {
        ["OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_ENABLE_GRPC_INSTRUMENTATION"] = "true",
    });

appBuilder.Services.AddOpenTelemetry()
    .WithTracing(tracing => tracing
    .AddAspNetCoreInstrumentation());

Semantic conventions for RPC are still experimental and hence the instrumentation only offers it as an experimental feature.

Troubleshooting

This component uses an EventSource with the name "OpenTelemetry-Instrumentation-AspNetCore" for its internal logging. Please refer to SDK troubleshooting for instructions on seeing these internal logs.

References

• Introduction to ASP.NET Core
• gRPC services using ASP.NET Core
• OpenTelemetry Project