README.md

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.

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. You can track the progress from milestones.

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. The example below enables this instrumentation by using an extension method on IServiceCollection. This extension method requires adding the package OpenTelemetry.Extensions.Hosting to the application. This ensures the instrumentation is disposed when the host is shutdown.

Additionally, this examples sets up the OpenTelemetry Jaeger exporter, which requires adding the package OpenTelemetry.Exporter.Jaeger to the application.

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

public void ConfigureServices(IServiceCollection services)
{
    services.AddOpenTelemetryTracing((builder) => builder
        .AddAspNetCoreInstrumentation()
        .AddJaegerExporter()
    );
}

Advanced configuration

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

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

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

services.AddOpenTelemetryTracing((builder) => builder
    .AddAspNetCoreInstrumentation()
    .AddJaegerExporter()
);

Filter

This instrumentation by default collects all the incoming http requests. It allows filtering of requests by using the Filter function in AspNetCoreInstrumentationOptions. 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.AddOpenTelemetryTracing((builder) => builder
    .AddAspNetCoreInstrumentation((options) => options.Filter = httpContext =>
    {
        // only collect telemetry about HTTP GET requests
        return httpContext.Request.Method.Equals("GET");
    })
    .AddJaegerExporter()
);

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 option allows one to enrich the activity with additional information from the raw HttpRequest, HttpResponse objects. 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. For event name "OnStartActivity", the actual object will be HttpRequest. For event name "OnStopActivity", the actual object will be HttpResponse

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

services.AddOpenTelemetryTracing((builder) =>
{
    builder.AddAspNetCoreInstrumentation((options) => options.Enrich
        = (activity, eventName, rawObject) =>
    {
        if (eventName.Equals("OnStartActivity"))
        {
            if (rawObject is HttpRequest httpRequest)
            {
                activity.SetTag("requestProtocol", httpRequest.Protocol);
            }
        }
        else if (eventName.Equals("OnStopActivity"))
        {
            if (rawObject is HttpResponse httpResponse)
            {
                activity.SetTag("responseLength", httpResponse.ContentLength);
            }
        }
    })
});

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.

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.

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