Freigeben über

.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:

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

Protokolle, Metriken und verteilte Rückverfolgung werden manchmal zusammen als die drei Säulen der Transparenz 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:

.NET OTel-Architektur

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 Beispiel-Walkthroughs für die Verwendung von OpenTelemetry in .NET fortgesetzt:

OpenTelemetry in .NET Aspire

.NET Aspire ist eine Reihe von Erweiterungen für .NET, die die Erstellung und Arbeit mit verteilten Anwendungen vereinfachen. Einer der Vorteile von .NET Aspire ist, dass Telemetrie integriert ist und die OpenTelemetry-Bibliotheken für .NET verwendet werden. Die Standardprojektvorlagen für .NET Aspire enthalten ein ServiceDefaults-Projekt, das auch das Setup und die Konfiguration von OTel umfasst. Das Service Defaults-Projekt wird von jedem Dienst in einer .NET Aspire-Lösung referenziert und initialisiert.

Die Service Defaults-Projektvorlage umfasst die Instrumentalisierungspakete für OTel SDK, ASP.NET, HttpClient und Runtime. Diese werden in der Extensions.cs-Datei konfiguriert. Für den Export von Telemetriedaten enthält .NET Aspire standardmäßig den OTLP-Exporter, sodass Telemetrie-Visualisierungen über das Aspire-Dashboard bereitgestellt werden können.

Das Aspire Dashboard ist so konzipiert, dass es die Telemetriebeobachtung in den lokalen Debug-Zyklus einbringt, wodurch Entwickler nicht nur sicherstellen können, dass die Anwendungen Telemetrie produzieren, sondern diese Telemetrie auch zur lokalen Diagnose dieser Anwendungen nutzen können. Die Möglichkeit, die Aufrufe zwischen den Diensten zu beobachten, erweist sich bei der Fehlerbehebung als ebenso nützlich wie in der Produktion. Das .NET Aspire-Dashboard wird automatisch gestartet, wenn Sie beim AppHost-Projekt aus dem Visual Studio oder dotnet run beim AppHost-Projekt auf F5 drücken.

Aspire-Dashboard

Weitere Details zu .NET Aspire:

Wiederverwendung des Aspire Service Defaults Projekts ohne .NET Aspire Orchestrierung

Die wahrscheinlich einfachste Möglichkeit, OTel für ASP.NET-Projekte zu konfigurieren, ist die Verwendung des Aspire Service Defaults-Projekts, auch wenn der Rest von .NET Aspire, wie z. B. der AppHost für die Orchestrierung, nicht verwendet wird. Das Service Defaults-Projekt ist als eine Projektvorlage über Visual Studio oder dotnet new verfügbar. Damit wird OTel konfiguriert und der OTLP-Exporter eingerichtet. Sie können dann die OTel-Umgebungsvariablen verwenden, um den OTLP-Endpunkt zum Senden der Telemetrie und den Bereitstellen der Eigenschaften für die Anwendung zu konfigurieren.

Die Schritte zum Verwenden von ServiceDefaults außerhalb von .NET Aspire sind wie folgt:

  • Fügen Sie das ServiceDefaults-Projekt mit Neues Projekt hinzufügen in Visual Studio zur Lösung hinzu, oder verwenden Sie dotnet new aspire-servicedefaults --output ServiceDefaults
  • Referenzieren Sie das ServiceDefaults-Projekt aus Ihrer ASP.NET-Anwendung. Verwenden Sie in Visual Studio die Funktion „ ->-Projektreferenz hinzufügen“, und wählen Sie das ServiceDefaults-Projekt aus
  • Rufen Sie die OpenTelemetry-Setup-Funktion als Teil der Initialisierung Ihres Anwendungsgenerators auf.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Service Defaults kann bei Bedarf die folgenden zusätzlichen Funktionen über AddServiceDefaults() oder die spezifischen Funktionen einrichten:

  • Integritätsprüfungen mit /health- und /alive-Endpunkten
  • Diensterkennung, die ohne den Rest von .NET Aspire eine Nulloperation sein wird
  • Konfigurieren der Resilienz für HttpClient, der die Anfrage im Falle eines Fehlers erneut sendet