Share via

.NET-waarneembaarheid met OpenTelemetry

Wanneer u een toepassing uitvoert, wilt u weten hoe goed de app presteert en potentiële problemen detecteren voordat ze groter worden. U kunt dit doen door telemetriegegevens zoals logboeken of metrische gegevens uit uw app te verzenden en die gegevens vervolgens te bewaken en analyseren.

Wat is waarneembaarheid?

Waarneembaarheid in de context van een gedistribueerd systeem is de mogelijkheid om telemetriegegevens over de status van elk onderdeel te bewaken en te analyseren, om wijzigingen in prestaties te kunnen observeren en te diagnosticeren waarom deze wijzigingen optreden. In tegenstelling tot foutopsporing, wat invasief is en van invloed kan zijn op de werking van de toepassing, is de waarneembaarheid bedoeld om transparant te zijn voor de primaire bewerking en een klein genoeg prestatie-impact te hebben die deze continu kan worden gebruikt.

Waarneembaarheid wordt meestal uitgevoerd met behulp van een combinatie van:

  • Logboeken, waarin afzonderlijke bewerkingen worden vastgelegd, zoals een binnenkomende aanvraag, een fout in een specifiek onderdeel of een bestelling die wordt geplaatst.
  • Metrieken, zoals meetwaarden en meters als het aantal voltooide aanvragen, actieve aanvragen, verkochte widgets; of een histogram van de aanvraaglatentie.
  • Gedistribueerde tracering, waarmee aanvragen en activiteiten in onderdelen in een gedistribueerd systeem worden bijgehouden, zodat u kunt zien waar de tijd wordt besteed en specifieke fouten kunt opsporen.

Samen worden logboeken, metrische gegevens en gedistribueerde tracering ook wel de drie pijlers van waarneembaarheid genoemd.

Elke pijler kan telemetriegegevens bevatten uit:

  • De .NET-runtime, zoals de geheugenbeheerder of JIT-compiler.
  • Bibliotheken, zoals die van Kestrel (de ASP.NET webserver) en HttpClient.
  • Toepassingsspecifieke telemetrie die wordt verzonden door uw code.

Waarneembaarheidsmethoden in .NET

Er zijn verschillende manieren om waarneembaarheid in .NET-toepassingen te bereiken:

  • Door expliciet in code te verwijzen naar en gebruik te maken van een bibliotheek zoals OpenTelemetry. Als u toegang hebt tot de broncode en de app opnieuw kunt bouwen, is dit het krachtigste en configureerbare mechanisme.
  • Buiten het proces met EventPipe. Hulpprogramma's zoals dotnet-monitor kunnen luisteren naar logboeken en metrische gegevens en deze vervolgens verwerken zonder dat dit van invloed is op code.
  • Met behulp van een opstarthook kunnen assembly's worden geïnjecteerd in het proces dat vervolgens instrumentatie kan verzamelen. Een voorbeeld van deze benadering is OpenTelemetry .NET Automatic Instrumentation.

Wat is OpenTelemetry?

OpenTelemetry (OTel) is een platformoverschrijdende, open standaard voor het verzamelen en verzenden van telemetriegegevens. OpenTelemetry omvat:

  • API's voor bibliotheken die moeten worden gebruikt om telemetriegegevens vast te leggen terwijl code wordt uitgevoerd.
  • API's die app-ontwikkelaars gebruiken om te configureren welk gedeelte van de opgenomen gegevens via het netwerk worden verzonden, waar ze naartoe worden verzonden en hoe deze kunnen worden gefilterd, gebufferd, verrijkt en getransformeerd.
  • Semantische conventies bieden richtlijnen voor naamgeving en inhoud van telemetriegegevens. Het is belangrijk voor de apps die telemetriegegevens produceren en de hulpprogramma's die de gegevens ontvangen om akkoord te gaan met wat verschillende soorten gegevens betekent en welke soorten gegevens nuttig zijn, zodat de hulpprogramma's effectieve analyse kunnen bieden.
  • Een interface voor exporteurs. Exporteurs zijn plug-ins waarmee telemetriegegevens in specifieke indelingen naar verschillende telemetrie-back-ends kunnen worden verzonden.
  • OTLP-wireprotocol is een leveranciersneutraal netwerkprotocol voor het verzenden van telemetrische gegevens. Sommige hulpprogramma's en leveranciers ondersteunen dit protocol naast bestaande eigen protocollen die ze mogelijk hebben.

Het gebruik van OTel maakt het gebruik van een groot aantal APM-systemen mogelijk, waaronder opensourcesystemen zoals Prometheus en Grafana, Azure Monitor - het APM-product van Microsoft in Azure of van de vele APM-leveranciers die samenwerken met OpenTelemetry.

Er zijn OpenTelemetry-implementaties voor de meeste talen en platforms, waaronder .NET.

.NET-implementatie van OpenTelemetry

De .NET OpenTelemetry-implementatie verschilt enigszins van andere platforms, omdat .NET logboekregistratie, metrische gegevens en activiteit-API's in het framework biedt. Dat betekent dat OTel geen API's nodig heeft die ontwikkelaars moeten gebruiken. De .NET OTel-implementatie maakt gebruik van deze platform-API's voor instrumentatie:

.NET OTel-architectuur

Waar OTel in het spel komt is dat het telemetriegegevens verzamelt van die API's en andere bronnen (via instrumentatiebibliotheken) en deze vervolgens exporteert naar een APM-systeem (Application Performance Monitoring) voor opslag en analyse. Het voordeel dat OTel als industriestandaard biedt, is een gemeenschappelijk mechanisme voor het verzamelen, algemene schema's en semantiek voor telemetriegegevens en een API voor hoe API's kunnen worden geïntegreerd met OTel. Het gebruik van OTel betekent dat toepassingen geen APM-specifieke API's of gegevensstructuren hoeven te gebruiken; ze werken tegen de OTel-standaard. APM's kunnen een specifiek APM-onderdeel voor exporteurs implementeren of OTLP gebruiken. Dit is een nieuwe draadstandaard voor het exporteren van telemetriegegevens naar de APM-systemen.

OpenTelemetry-pakketten

OpenTelemetry in .NET wordt geïmplementeerd als een reeks NuGet-pakketten die een aantal categorieën vormen:

  • Kern-API
  • Instrumentatie: deze pakketten verzamelen instrumentatie uit de runtime en gemeenschappelijke bibliotheken.
  • Exporteurs - deze interfacen met APM-systemen zoals Prometheus, Jaeger en OTLP.

In de volgende tabel worden de belangrijkste pakketten beschreven.

Pakketnaam Beschrijving
OpenTelemetry Hoofdbibliotheek die de kernfunctionaliteit van OTEL biedt
OpenTelemetry.Instrumentation.AspNetCore Instrumentatie voor ASP.NET Core en Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient Instrumentatie voor gRPC-client voor het bijhouden van uitgaande gRPC-aanroepen
OpenTelemetry.Instrumentation.Http Instrumentatie voor HttpClient en HttpWebRequest om uitgaande HTTP-aanroepen bij te houden
OpenTelemetry.Instrumentation.SqlClient Instrumentatie voor SqlClient het traceren van databasebewerkingen
OpenTelemetry.Exporter.Console Exporteur voor de console, die vaak wordt gebruikt om te diagnosticeren welke telemetrie wordt geëxporteerd
OpenTelemetry.Exporter.OpenTelemetryProtocol Exporteur die gebruikmaakt van het OTLP-protocol
OpenTelemetry.Exporter.Prometheus.AspNetCore Exporteur voor Prometheus geïmplementeerd met behulp van een ASP.NET Core-eindpunt
OpenTelemetry.Exporter.Zipkin Exporteur van Zipkin-tracegegevens

Voorbeelden

Dit onderwerp wordt voortgezet met een aantal voorbeeldscenario's voor het gebruik van OpenTelemetry in .NET:

OpenTelemetry in Aspire

Aspire is een set extensies voor .NET, zodat u eenvoudig gedistribueerde toepassingen kunt maken en ermee kunt werken. Een van de voordelen van het gebruik van Aspire is dat telemetrie is ingebouwd met behulp van de OpenTelemetry-bibliotheken voor .NET. De standaardprojectsjablonen voor Aspire bevatten een ServiceDefaults project, waarvan een deel bestaat uit het instellen en configureren van OTel. Naar het project met standaards voor diensten wordt verwezen en het wordt geïnitialiseerd door elke service in een Aspire-oplossing.

De servicestandaardprojectsjabloon bevat de OTel SDK- ASP.NET-, HttpClient- en Runtime Instrumentation-pakketten en deze zijn geconfigureerd in het Extensions.cs bestand. Voor het exporteren van telemetrie omvat Aspire standaard de OTLP-exporteur, zodat deze telemetrievisualisatie kan bieden met behulp van het Aspire Dashboard.

Het Aspire Dashboard is ontworpen om telemetrieobservatie naar de lokale foutopsporingscyclus te brengen, waardoor ontwikkelaars niet alleen ervoor kunnen zorgen dat de toepassingen telemetrie produceren, maar ook die telemetrie gebruiken om deze toepassingen lokaal te diagnosticeren. Het kunnen observeren van de aanroepen tussen services blijkt net zo nuttig te zijn tijdens het debuggen als in de productie. Het Aspire-dashboard wordt automatisch gestart wanneer u F5 gebruikt om het AppHost project vanuit Visual Studio of het dotnet run project te starten.

Ambidashboard

Zie voor meer informatie over Aspire:

Het project Service Defaults hergebruiken zonder Aspire Orchestration

Waarschijnlijk de eenvoudigste manier om OTel te configureren voor ASP.NET projecten is door het project Aspire Service Defaults te gebruiken, zelfs als de rest van Aspire niet wordt gebruikt, zoals de AppHost voor orchestration. Het servicestandaardproject is beschikbaar als een projectsjabloon via Visual Studio of dotnet new. Het configureert OTel en stelt de OTLP-exporteur in. Vervolgens kunt u de omgevingsvariabelen van OTel gebruiken om het OTLP-eindpunt te configureren voor het verzenden van telemetrie naar en de resource-eigenschappen voor de toepassing op te geven.

De stappen voor het gebruik van ServiceDefaults buiten Aspire zijn:

  • Voeg het ServiceDefaults-project toe aan de oplossing met behulp van Nieuw project toevoegen in Visual Studio of gebruik dotnet new aspire-servicedefaults --output ServiceDefaults.
  • Raadpleeg de ServiceDefaults project vanuit uw ASP.NET toepassing. In Visual Studio, gebruik toevoegen>projectreferentie en selecteer het project ServiceDefaults.
  • Roep de functie voor het instellen van OpenTelemetry aan als onderdeel van de initialisatie van uw toepassingsbouwer.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Service-Standaardinstellingen kunnen de volgende aanvullende functionaliteit configureren, als dat nodig is, via AddServiceDefaults() of specifieke functies.

  • Gezondheidscontroles met /health en /alive eindpunten.
  • Servicedetectie, dat zonder de rest van Aspire geen effect zal hebben.
  • Configuratie van de veerkracht voor HttpClient, die aanvragen opnieuw probeert bij fouten.
  • Last updated on