README.md

ASP.NET Instrumentation for OpenTelemetry

This is an Instrumentation Library, which instruments ASP.NET and collect telemetry about incoming web requests.

Steps to enable OpenTelemetry.Instrumentation.AspNet

Step 1: Install Package

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

dotnet add package OpenTelemetry.Instrumentation.AspNet

Step 2: Modify Web.config

OpenTelemetry.Instrumentation.AspNet requires adding an additional HttpModule to your web server. This additional HttpModule is shipped as part of Microsoft.AspNet.TelemetryCorrelation which is implicitly brought by OpenTelemetry.Instrumentation.AspNet. The following shows changes required to your Web.config when using IIS web server.

<system.webServer>
    <modules>
    <add name="TelemetryCorrelationHttpModule"
    type="Microsoft.AspNet.TelemetryCorrelation.TelemetryCorrelationHttpModule,
    Microsoft.AspNet.TelemetryCorrelation"
    preCondition="integratedMode,managedHandler" />
    </modules>
</system.webServer>

Step 3: Enable ASP.NET Instrumentation at application startup

ASP.NET instrumentation must be enabled at application startup. This is typically done in the Global.asax.cs as shown below. This example also sets up the OpenTelemetry Jaeger exporter, which requires adding the package OpenTelemetry.Exporter.Jaeger to the application.

using OpenTelemetry;
using OpenTelemetry.Trace;

public class WebApiApplication : HttpApplication
{
    private TracerProvider tracerProvider;
    protected void Application_Start()
    {
        this.tracerProvider = Sdk.CreateTracerProviderBuilder()
            .AddAspNetInstrumentation()
            .AddJaegerExporter()
            .Build();
    }
    protected void Application_End()
    {
        this.tracerProvider?.Dispose();
    }
}

Advanced configuration

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

Filter

This instrumentation by default collects all the incoming http requests. It allows filtering of requests by using Filter function in AspNetInstrumentationOptions. This can be used to filter out any requests based on some condition. The Filter receives the HttpContext of the incoming request, and filters out the request if the Filter returns false or throws exception.

The following shows an example of Filter being used to filter out all POST requests.

this.tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAspNetInstrumentation(
        (options) =>
        {
            options.Filter = (httpContext) =>
            {
                // filter out all HTTP POST requests.
                return !httpContext.Request.HttpMethod.Equals("POST");
            };
        })
    .Build();

It is important to note that this Filter option is specific to this instrumentation. OpenTelemetry has a concept of Sampler, and the Filter option does the filtering before 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.

this.tracerProvider = Sdk.CreateTracerProviderBuilder()
    .AddAspNetInstrumentation(opt => opt.Enrich
        = (activity, eventName, rawObject) =>
    {
        if (eventName.Equals("OnStartActivity"))
        {
            if (rawObject is HttpRequest httpRequest)
            {
                activity.SetTag("physicalPath", httpRequest.PhysicalPath);
            }
        }
        else if (eventName.Equals("OnStopActivity"))
        {
            if (rawObject is HttpResponse httpResponse)
            {
                activity.SetTag("responseType", httpResponse.ContentType);
            }
        }
    })
    .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 HttpRequest and HttpResponse.

References

• ASP.NET
• OpenTelemetry Project