README.md

OpenTelemetry.Extensions.Hosting

Installation

dotnet add package OpenTelemetry.Extensions.Hosting

Overview

The OpenTelemetry.Extensions.Hosting package provides extension methods for automatically starting (and stopping) OpenTelemetry tracing (TracerProvider) and metrics (MeterProvider) in ASP.NET Core and .NET Generic hosts. These are completely optional extensions meant to simplify the management of the OpenTelemetry SDK lifecycle.

Extension method reference

Targeting Microsoft.Extensions.DependencyInjection.IServiceCollection:

• AddOpenTelemetry: Registers an IHostedService to automatically start tracing and/or metric services in the supplied IServiceCollection and then returns an OpenTelemetryBuilder class.

  [!NOTE] AddOpenTelemetry should be called by application host code only. Library authors see: Registration extension method guidance for library authors.

  [!NOTE] Multiple calls to AddOpenTelemetry will NOT result in multiple providers. Only a single TracerProvider and/or MeterProvider will be created in the target IServiceCollection. To establish multiple providers use the Sdk.CreateTracerProviderBuilder() and/or Sdk.CreateMeterProviderBuilder() methods. See TracerProvider configuration and Building a MeterProvider for more details.

  OpenTelemetryBuilder methods:

  • ConfigureResource: Registers a callback action to configure the ResourceBuilder for tracing and metric providers.

  • WithTracing: Enables tracing and optionally configures the TracerProvider.

  • WithMetrics: Enables metrics and optionally configures the MeterProvider.

Targeting Microsoft.Extensions.Hosting.IHostApplicationBuilder:

• AddOpenTelemetry: Does everything the IServiceCollection method above does, using IHostApplicationBuilder.Services, and additionally:

  • Seeds service.name from IHostEnvironment.ApplicationName and deployment.environment.name from IHostEnvironment.EnvironmentName as low-priority resource defaults. Both are superseded by the OTEL_SERVICE_NAME / OTEL_RESOURCE_ATTRIBUTES environment variables or by any explicit ConfigureResource call.

  • Makes the host's Configuration available to OpenTelemetry extensions during setup. It also registers that configuration as an IConfigurationManager singleton when the application has not already registered one.

  It returns the same OpenTelemetryBuilder class, so the only change to an existing setup is the first line:

  var builder = Host.CreateApplicationBuilder(args);
  
  builder.AddOpenTelemetry()
      .WithTracing(tracing => tracing.AddSource("MyApp"));

  [!NOTE] A host registers IConfiguration as a factory so that the container owns its disposal, which leaves the underlying configuration unreachable while the application is still being built. Registering it makes the application's configuration available to OpenTelemetry extensions that only receive an IServiceCollection, so they can contribute configuration sources during setup rather than replacing the IConfiguration registration afterwards. An IConfigurationManager already registered by the application is left in place.

Usage

The following example shows how to register OpenTelemetry tracing & metrics in an ASP.NET Core host using the OpenTelemetry.Extensions.Hosting extensions.

using Microsoft.AspNetCore.Builder;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

var appBuilder = WebApplication.CreateBuilder(args);

appBuilder.AddOpenTelemetry()
    .WithTracing(builder => builder.AddConsoleExporter())
    .WithMetrics(builder => builder.AddConsoleExporter());

var app = appBuilder.Build();

app.Run();

A fully functional example can be found here.

Important

Applications that do not support hosted services, such as Blazor, should resolve the ITelemetryHostInitializer service from the service provider to manually initialize the OpenTelemetry SDK as part of application startup.

For example:

app.Services.GetRequiredService<ITelemetryHostInitializer>().Initialize();

Resources

To dynamically add resources at startup from the dependency injection you can provide an IResourceDetector. To make use of it add it to the dependency injection and then you can use the IServiceProvider to add it to OpenTelemetry:

public class MyResourceDetector : IResourceDetector
{
    private readonly IWebHostEnvironment webHostEnvironment;

    public MyResourceDetector(IWebHostEnvironment webHostEnvironment)
    {
        this.webHostEnvironment = webHostEnvironment;
    }

    public Resource Detect()
    {
        return ResourceBuilder.CreateEmpty()
            .AddService(serviceName: this.webHostEnvironment.ApplicationName)
            .AddAttributes(new Dictionary<string, object> { ["host.environment"] = this.webHostEnvironment.EnvironmentName })
            .Build();
    }
}

services.AddSingleton<MyResourceDetector>();

services.AddOpenTelemetry()
    .ConfigureResource(builder =>
        builder.AddDetector(sp => sp.GetRequiredService<MyResourceDetector>()))
    .WithTracing(builder => builder.AddConsoleExporter())
    .WithMetrics(builder => builder.AddConsoleExporter());

Migrating from pre-release versions of OpenTelemetry.Extensions.Hosting

Pre-release versions (all versions prior to 1.4.0) of OpenTelemetry.Extensions.Hosting contained signal-specific methods for configuring tracing and metrics:

• AddOpenTelemetryTracing: Configure OpenTelemetry and register an IHostedService to automatically start tracing services in the supplied IServiceCollection.

• AddOpenTelemetryMetrics: Configure OpenTelemetry and register an IHostedService to automatically start metric services in the supplied IServiceCollection.

These methods were marked obsolete and later removed. You should migrate your code to the new AddOpenTelemetry method documented above. Refer the old and new versions of the example application to assist you in your migration.

Hosted Service Ordering and Telemetry Capture

TBD

References

• OpenTelemetry Project