Intility.OpenTelemetry.Instrumentation.Assembly 0.2.1

OpenTelemetry.Instrumentation.Assembly

A .NET library for automatically instrumenting assemblies with OpenTelemetry traces. This package enables automatic instrumentation of controllers and services within a specified assembly, tracing method calls and capturing method parameters.

Features

• Automatically traces ASP.NET Core controller actions
• Automatically wraps and traces interface implementations
• Captures method arguments as trace attributes
• Traces exceptions and adds them to spans
• Works with both standard and keyed services in ASP.NET Core dependency injection

Installation

Install the package from NuGet:

dotnet add package Intility.OpenTelemetry.Instrumentation.Assembly

Usage

Basic Configuration

Add the following packages to your .csproj:

<ItemGroup>
    <PackageReference Include="Intility.OpenTelemetry.Instrumentation.Assembly" Version="0.1.2" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.11.2" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.11.2" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.11.2" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.11.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.SqlClient" Version="1.11.0-beta.2" />
</ItemGroup>

Add assembly instrumentation to your OpenTelemetry configuration:

using OpenTelemetry.Trace;

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry
var otel = builder.Services.AddOpenTelemetry();


otel.ConfigureResource(r => r
    .AddService(serviceName: "MyService")

    // Optional, add serviceVersion and environment
    // .AddAttributes(new Dictionary<string, string>(){
    //     { "deployment.environment.name", "Development" },
    //     { "service.version", "1.0.0" }
    // } )
);

// Configure tracing
otel.WithTracing(tracing =>
{
    // Add standard instrumentations
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();

    // Optional, dependent om your system
    // tracing.AddEntityFrameworkCoreInstrumentation();
    // tracing.AddRedisInstrumentation();


    // Add exporter of your choice
    tracing.AddConsoleExporter();
    // or
    tracing.AddOtlpExporter(otlpOptions =>
    {
        otlpOptions.Endpoint = new Uri("https://<url>/v1/traces");
        // Enable Http for default tracing to logfire. When using port 4317,grpc is default. 
        otlpOptions.Protocol = OtlpExportProtocol.HttpProtobuf;

        // Set the token if authentication is required
        //otlpOptions.Headers = "Authorization=<Token>";
    });
});

// Register your services
builder.Services.AddSingleton<IMyService, MyService>();
builder.Services.AddControllers();

// Add assembly instrumentation LAST
otel.AddAssemblyInstrumentation(typeof(Program).Assembly.FullName!);

Important Notes

1. Always add the assembly instrumentation after registering all services you want to instrument.

2. The assembly instrumentation will automatically:

   • Add trace spans for controller actions in the specified assembly
   • Wrap interfaces defined or implemented in the specified assembly with a tracing proxy
   • Capture method parameters as span attributes

3. The assembly name parameter should be the fully qualified assembly name:

   typeof(Program).Assembly.FullName!
   

How It Works

The library works by:

1. Adding an ActionFilter to trace ASP.NET Core controller actions
2. Using the .NET DispatchProxy class to create dynamic proxies for interface implementations
3. Creating spans for method calls and capturing method arguments as span attributes
4. Handling exceptions and adding them to spans

Example

In the sample application, you can see how the library automatically instruments:

• Controller actions in WeatherForecastController
• Service method calls in WeatherForecastService

Each method call becomes a span in the trace, with method parameters captured as attributes.

Requirements

• .NET 9.0 or higher
• OpenTelemetry SDK 1.11.0 or higher
• OpenTelemetry.Extensions.Hosting
• ASP.NET Core for Web API scenarios

License

This project is licensed under the terms specified in the repository.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.