.NET-Einblick mit OpenTelemetry

Wenn Sie eine Anwendung ausführen, möchten Sie wissen, wie gut die App funktioniert, und potenzielle Probleme erkennen, bevor sie größer werden. Sie können dies tun, indem Sie Telemetriedaten wie Protokolle oder Metriken von Ihrer App aus senden und diese Daten dann überwachen und analysieren.

Was bedeutet Einblick?

Einblick im Kontext eines verteilten Systems ist die Fähigkeit, Telemetriedaten über den Zustand jeder Komponente zu überwachen und zu analysieren, Leistungsänderungen zu beobachten und zu diagnostizieren, warum diese Änderungen auftreten. Im Gegensatz zum Debuggen, das invasiv ist und sich auf den Betrieb der Anwendung auswirken kann, soll der Einblick für den primären Vorgang transparent sein und einen ausreichend geringen Einfluss auf die Leistung haben, damit er kontinuierlich verwendet werden kann.

Einblick erfolgt in der Regel mit einer Kombination aus:

• Protokolliert, welche einzelne Vorgänge, z. B. eine eingehende Anforderung, einen Fehler in einer bestimmten Komponente oder eine Bestellung aufzeichnen, die aufgegeben wird.
• Metriken, die Indikatoren und Messgeräte messen, z. B. Anzahl der abgeschlossenen Anforderungen, aktive Anforderungen, Widgets, die verkauft wurden, oder ein Histogramm der Anforderungslatenz.
• Verteilte Ablaufverfolgung, die Anforderungen und Aktivitäten über Komponenten in einem verteilten System nachverfolgt, sodass Sie sehen können, wo Zeit aufgewendet wird, und bestimmte Fehler nachzuverfolgen.

Zusammen werden Protokolle, Metriken und verteilte Ablaufverfolgung manchmal als die drei Säulen der Observability bezeichnet.

Jede Säule kann Telemetriedaten aus folgenden Daten enthalten:

• Die .NET-Runtime, z. B. der Garbage Collector oder der JIT-Compiler.
• Bibliotheken, z. B. von Kestrel (der ASP.NET-Webserver) und HttpClient.
• Anwendungsspezifische Telemetriedaten, die von Ihrem Code ausgegeben werden.

Ansätze für Einblick in .NET

Es gibt verschiedene Möglichkeiten, Einblick in .NET-Anwendungen zu erreichen:

• Explizit im Code, indem auf eine Bibliothek wie OpenTelemetry verwiesen und diese verwendet wird. Wenn Sie Zugriff auf den Quellcode haben und die App neu erstellen können, ist dies der leistungsstärkste und konfigurierbarste Mechanismus.
• Out-of-Process mit EventPipe. Tools wie dotnet-monitor können Protokolle und Metriken überwachen und diese dann ohne Auswirkungen auf Code verarbeiten.
• Mithilfe eines Starthooks können Assemblys in den Prozess eingefügt werden, der dann Instrumentierung sammeln kann. Ein Beispiel für diesen Ansatz ist die automatische .NET-Instrumentierung von OpenTelemetry.

Was ist OpenTelemetry?

OpenTelemetry (OTel) ist ein plattformübergreifender, offener Standard zum Sammeln und Ausgeben von Telemetriedaten. OpenTelemetry umfasst Folgendes:

• APIs für Bibliotheken, die zum Aufzeichnen von Telemetriedaten während der Codeausführung verwendet werden sollen.
• APIs, die App-Entwickler verwenden, um zu konfigurieren, welcher Teil der aufgezeichneten Daten über das Netzwerk gesendet wird, wohin sie gesendet werden und wie sie gefiltert, gepuffert, angereichert und transformiert werden können.
• Semantische Konventionen bieten Anleitungen für die Benennung und den Inhalt von Telemetriedaten. Es ist wichtig, dass die Apps, die Telemetriedaten erzeugen, und die Tools, die die Daten empfangen, vereinbart werden, was verschiedene Arten von Daten bedeutet, und welche Arten von Daten nützlich sind, damit die Tools eine effektive Analyse ermöglichen können.
• Eine Schnittstelle für Exporter. Exporter sind Plug-Ins, mit denen Telemetriedaten in bestimmten Formaten an verschiedene Telemetrie-Back-Ends übertragen werden können.
• Das OTLP-Wire-Protokoll ist eine anbieterneutrale Netzwerkprotokolloption für die Übertragung von Telemetriedaten. Einige Tools und Anbieter unterstützen dieses Protokoll zusätzlich zu bereits vorhandenen proprietären Protokollen, über die sie möglicherweise verfügen.

Die Verwendung von OTel ermöglicht den Einsatz einer Vielzahl von APM-Systemen, darunter Open-Source-Systeme wie Prometheus und Grafana, Azure Monitor – das APM-Produkt von Microsoft in Azure oder von den vielen APM-Anbietern, die mit OpenTelemetry zusammenarbeiten.

Es gibt OpenTelemetry-Implementierungen für die meisten Sprachen und Plattformen, einschließlich .NET.

.NET-Implementierung von OpenTelemetry

Die .NET OpenTelemetry-Implementierung unterscheidet sich etwas von anderen Plattformen, da .NET Protokollierungs-, Metrik- und Aktivitäts-APIs im Framework bereitstellt. Das bedeutet, dass OTel keine APIs für Bibliotheksautoren bereitstellen muss. Die .NET OTel-Implementierung verwendet die folgenden Plattform-APIs für die Instrumentierung:

• Microsoft.Extensions.Logging.ILogger<TCategoryName> für die Protokollierung
• System.Diagnostics.Metrics.Meter für Metriken
• System.Diagnostics.ActivitySource und System.Diagnostics.Activity für verteilte Ablaufverfolgung

OTel kommt dort ins Spiel, wo Telemetriedaten von diesen APIs und anderen Quellen (über Instrumentierungsbibliotheken) gesammelt und dann zur Speicherung und Analyse in ein APM-System (Application Performance Monitoring) exportiert werden. Der Vorteil, den OTel als Branchenstandard bietet, ist ein gemeinsamer Mechanismus für die Sammlung, allgemeine Schemas und Semantik für Telemetriedaten und eine API für die Integration von APMs in OTel. Die Verwendung von OTel bedeutet, dass Anwendungen keine APM-spezifischen APIs oder Datenstrukturen verwenden müssen. Sie arbeiten mit dem OTel-Standard. APMs können entweder eine APM-spezifische Exporterkomponente implementieren oder OTLP verwenden, einen neuen Übertragungsstandard für den Export von Telemetriedaten in die APM-Systeme.

OpenTelemetry-Pakete

OpenTelemetry in .NET wird als eine Reihe von NuGet-Paketen implementiert, die mehrere Kategorien bilden:

• Core-API
• Instrumentierung: Diese Pakete sammeln die Instrumentierung aus der Runtime und gängigen Bibliotheken.
• Exporteure: Diese bilden eine Schnittstelle mit APM-Systemen wie Prometheus, Jaeger und OTLP.

In folgender Tabelle werden die SMTP-Einstellungen beschrieben.

Paketname	BESCHREIBUNG
OpenTelemetry	Hauptbibliothek, die die OTEL-Kernfunktionen bereitstellt
OpenTelemetry.Instrumentation.AspNetCore	Instrumentierung für ASP.NET Core und Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Instrumentierung für den gRPC-Client zum Nachverfolgen ausgehender gRPC-Aufrufe
OpenTelemetry.Instrumentation.Http	Instrumentierung für HttpClient und HttpWebRequest zum Nachverfolgen ausgehender HTTP-Aufrufe
OpenTelemetry.Instrumentation.SqlClient	Instrumentierung für SqlClient zum Nachverfolgen von Datenbankvorgängen
OpenTelemetry.Exporter.Console	Exporter für die Konsole, der häufig verwendet wird, um zu diagnostizieren, welche Telemetriedaten exportiert werden
OpenTelemetry.Exporter.OpenTelemetryProtocol	Exporter mit dem OTLP-Protokoll
OpenTelemetry.Exporter.Prometheus.AspNetCore	Exporter für Prometheus, der mithilfe eines ASP.NET Core-Endpunkts implementiert wurde
OpenTelemetry.Exporter.Zipkin	Exporter für Zipkin-Ablaufverfolgung

Beispiele

Dieses Thema wird mit einigen exemplarischen Vorgehensweisen für die Verwendung von OpenTelemetry in .NET fortgesetzt:

• Beispiel: Verwenden von OTLP und dem eigenständigen Aspire Dashboard
• Beispiel: Verwenden von OpenTelemetry mit Azure Monitor und Application Insights
• Beispiel: Verwenden von OpenTelemetry mit Prometheus, Grafana und Jaeger

OpenTelemetry in .NET Aspire

.NET Aspire ist eine Reihe von Erweiterungen für .NET, um das Erstellen und Arbeiten mit verteilten Anwendungen zu vereinfachen. Einer der Vorteile der Verwendung von .NET Aspire besteht darin, dass Telemetrie integriert ist, indem die OpenTelemetry-Bibliotheken für .NET verwendet werden. Die Standardprojektvorlagen für .NET Aspire enthalten ein ServiceDefaults Projekt, dessen Teil das Einrichten und Konfigurieren von OTel ist. Das Projekt "Service Defaults" wird von jedem Dienst in einer .NET Aspire-Lösung referenziert und initialisiert.

Die Projektvorlage "Dienststandard" enthält das OTel-SDK, ASP.NET-, HttpClient- und Laufzeitinstrumentationspakete und die in der Extensions.cs Datei konfigurierten. Für den Export der Telemetrie .NET Aspire ist standardmäßig der OTLP-Exporter enthalten, sodass er telemetrievisualisierung über das Aspire Dashboard bereitstellen kann.

Das Aspire Dashboard wurde entwickelt, um Telemetriebeobachtung in den lokalen Debugzyklus zu bringen, wodurch Entwickler nicht nur sicherstellen können, dass die Anwendungen Telemetrie erzeugen, sondern auch diese Telemetrie verwenden, um diese Anwendungen lokal zu diagnostizieren. Die Beobachtung der Aufrufe zwischen Diensten erweist sich als ebenso nützlich bei der Debugzeit wie in der Produktion. Das .NET Aspire-Dashboard wird automatisch gestartet, wenn Sie das AppHost Projekt aus Visual Studio oder dotnet run dem Projekt F5 ausführen AppHost .

Weitere Details zu .NET Aspire finden Sie unter:

• Aspire Übersicht
• Telemetrie in Aspire
• Aspire Dashboard

Erneutes Verwenden des Dienststandardprojekts ohne .NET Aspire Orchestration

Wahrscheinlich die einfachste Möglichkeit, OTel für ASP.NET Projekte zu konfigurieren, besteht darin, das Projekt "Aspire Service Defaults" zu verwenden, auch wenn der Rest von .NET Aspire nicht verwendet wird, z. B. appHost für die Orchestrierung. Das Dienststandardprojekt ist als Projektvorlage über Visual Studio oder dotnet new. Er konfiguriert OTel und richtet den OTLP-Exporter ein. Anschließend können Sie die OTel-Umgebungsvariablen verwenden, um den OTLP-Endpunkt so zu konfigurieren, dass telemetrie an sie gesendet wird, und die Ressourceneigenschaften für die Anwendung bereitstellen.

Die Schritte zur Verwendung von ServiceDefaults außerhalb von .NET Aspire sind:

• Hinzufügen des ServiceDefaults-Projekts zur Projektmappe mithilfe von "Neues Projekt hinzufügen" in Visual Studio oder Verwenden dotnet new aspire-servicedefaults --output ServiceDefaults
• Verweisen Sie auf das ServiceDefaults-Projekt aus Ihrer ASP.NET Anwendung. Verwenden Sie in Visual Studio "Hinzufügen –> Projektreferenz" und wählen Sie das ServiceDefaults-Projekt aus.
• Rufen Sie die OpenTelemetry-Setupfunktion als Teil der Initialisierung des Anwendungs-Generators auf.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Dienststandardwerte können die folgenden zusätzlichen Funktionen einrichten, falls erforderlich über AddServiceDefaults() oder die spezifischen Funktionen:

• Integritätsprüfungen mit /health und /alive Endpunkten
• Dienstermittlung, die ohne den Rest von .NET Aspire ein No-Op sein wird
• Konfigurieren der Resilienz für HttpClient, die die Anforderung bei Fehlern erneut versuchen wird