OpenTelemetry.Extensions.Hosting 1.12.0

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.

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 Microsoft.Extensions.DependencyInjection;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

var appBuilder = WebApplication.CreateBuilder(args);

appBuilder.Services.AddOpenTelemetry()
    .ConfigureResource(builder => builder.AddService(serviceName: "MyService"))
    .WithTracing(builder => builder.AddConsoleExporter())
    .WithMetrics(builder => builder.AddConsoleExporter());

var app = appBuilder.Build();

app.Run();

A fully functional example can be found here.

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