Muster: OpenTelemetry

Version: 1.0
.NET Version: .NET 8.0 oder höher

OpenTelemetry ist ein moderner, offener Standard für Protokolle zur Erzeugung und Übertragung von Telemetriedaten wie Logs, Traces und Metriken. Dieses Muster beschreibt, wie Schleupen.CS-Web APIs dazu befähigt werden können, Telemetriedaten per OpenTelemetry an einen konfigurierbaren Collector zu übertragen.

Design

Das Design ist trivial: Es sind zwei Extension Methods für den WebApplicationBuilder anzuschließen.

Implementierung

Eine Schleupen.CS Web-API kann über das NuGet-Package Schleupen.CS.PI.SB.WebApi.OpenTelemetry.Net (.NET, nicht verfügbar für .NET Framework) dazu befähigt werden, Telemetriedaten per OpenTelemetry zu versenden. Für die Integration mit dem Package existieren zwei Optionen:

Option 1: Package direkt referenzieren

Das Package Schleupen.CS.PI.SB.WebApi.OpenTelemetry.Net muss wie üblich in die Dateien paket.dependencies und paket.references innerhalb des C#-Projekts der Web-API-Fassade eingetragen werden. Anschließend kann das Package mittels des Cmdlets Update-DependenciesWithPaket in der Solution installiert werden.

Danach müssen die erforderlichen OpenTelemetry-Settings und -Services im Host Builder der Web-API registriert werden, indem die bereitgestellten Extension Methods AddSchleupenOpenTelemetrySettings() und AddSchleupenOpenTelemetry() aufgerufen werden:

using Schleupen.CS.PI.SB.WebApi.OpenTelemetry;
...
{
    ...
    var builder = WebApplication.CreateBuilder(args);
    builder.Configuration.AddSchleupenOpenTelemetrySettings();
    builder.Services.AddSchleupenOpenTelemetry("Schleupen-AS-MT-BIB");
    ...
}

Option 2: Nutzung der Hosting API

Diese Option befindet sich derzeit noch in der Umsetzung und steht erst demnächst zur Verfügung.

Das Package Schleupen.CS.PI.SB.WebApi.OpenTelemetry.Net ist in die Hosting API bereits integriert und muss nicht mehr explizit referenziert werden, wenn die Web-API basierend auf dem NuGet-Package Schleupen.CS.PI.SB.WebApi.Application.Castle6.Net implementiert wird. Die expliziten Aufrufe der Extension Methods AddSchleupenOpenTelemetrySettings() und AddSchleupenOpenTelemetry() aus Option 1 entfallen dann ebenfalls.

Testen mit der WebApplicationFactory

Microsoft stellt mit dem Package Microsoft.AspNetCore.Mvc.Testing ein Framework für integrative Tests von ASP.NET Core Web-Anwendungen bereit. Analog zur ServiceTestFixture aus dem PI.Framework ist darin die Klasse WebApplicationFactory enthalten, um die zu testende Web-Anwendung In-Memory während der Tests zu hosten. Dieses Testing Framework ist hier ausführlicher dokumentiert.

Sofern die WebApplicationFactory innerhalb einer Solution genutzt wird, muss das Tracing per OpenTelemetry für die entsprechenden Tests deaktiviert werden. Ansonsten können keine Endpunkte der durch die Factory gehosteten Anwendung aufgerufen werden und Clients laufen in einen Timeout. Der folgende Snippet zeigt, wie das Tracing in der WebApplicationFactory deaktiviert werden kann. Weitere Details zur Konfiguration sind im Abschnitt Konfiguration beschrieben.

Wichtig! Das Tracing sollte nur im Test und nicht global für die eigentliche Web-Anwendung abgeschaltet werden! Ansonsten können zur Laufzeit beim Kunden die Traces nicht erfasst werden!

Wenn das Cmdlet Set-CSDiagnosticsConfiguration zur Konfiguration verwendet wird, dann darf das Tracing für die Komponente, in welcher die WebApplicationFactory genutzt wird, nicht aktiviert werden. Die Nutzung des Cmdlets ist hier im Detail beschrieben.

public class MyWebApplicationFactory : WebApplicationFactory<Program>
{
    ...

    protected override void ConfigureWebHost(IWebHostBuilder builder)
    {
        builder.ConfigureAppConfiguration((_, config) =>
        {
            config.AddInMemoryCollection(new Dictionary<string, string?>
            {
                ["OTEL_TRACES_SAMPLER"] = "always_off"
            });
        });

        ...
    }

    ...
}

Stärken und Schwächen

Die in diesem Abschnitt beschriebenen Stärken und Schwächen sollen eine Entscheidungshilfe an die Hand geben, wann dieses Muster eingesetzt werden kann.

Stärken

• Triviale Anbindung

Schwächen

• Keine