Delen via

.NET-waarneembaarheid met OpenTelemetry

  • Artikel

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.
  • Metrische gegevens, die meteritems en meters meten, zoals het aantal voltooide aanvragen, actieve aanvragen, widgets die zijn verkocht, of een histogram van de latentie van de aanvraag.
  • 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 garbagecollector of JIT-compiler.
  • Bibliotheken, zoals 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:

  • Expliciet in code door te verwijzen naar en te gebruiken 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.
  • Out-of-process 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 neutrale netwerkprotocoloptie van de leverancier voor het verzenden van telemetriegegevens. 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 hoeft te bieden voor bibliotheekauteurs die moeten worden gebruikt. 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 interface 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 voor Zipkin-tracering

Voorbeelden

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

OpenTelemetry in .NET Aspire

.NET 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 .NET Aspire is dat telemetrie is ingebouwd met behulp van de OpenTelemetry-bibliotheken voor .NET. De standaardprojectsjablonen voor .NET Aspire bevatten een ServiceDefaults project, waarvan een deel bestaat uit het instellen en configureren van OTel. Er wordt naar het project Service Defaults verwezen en geïnitialiseerd door elke service in een .NET 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 .NET Aspire omvat 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. Als u de aanroepen tussen services kunt observeren, is het net zo nuttig als bij foutopsporingstijd als in productie. Het .NET Aspire-dashboard wordt automatisch gestart wanneer u het AppHost project vanuit Visual Studio of dotnet run het AppHost project F5 gebruikt.

Ambidashboard

Zie voor meer informatie over .NET Aspire:

Standaardproject voor service hergebruiken zonder .NET 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 .NET Aspire niet wordt gebruikt, zoals de AppHost voor orchestration. Het standaardproject van de service is beschikbaar als projectsjabloon via Visual Studio of dotnet new. Het configureert OTel en stelt de OTLP-exporteur in. Vervolgens kunt u de OTel-omgevingsvariabelen gebruiken om het OTLP-eindpunt te configureren om telemetrie te verzenden naar en de resource-eigenschappen voor de toepassing op te geven.

De stappen voor het gebruik van ServiceDefaults buiten .NET 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
  • Verwijs naar het ServiceDefaults-project vanuit uw ASP.NET-toepassing. In Visual Studio gebruikt u 'Add -> Project Reference' en selecteert u 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();

Standaardinstellingen voor services kunnen de volgende aanvullende functionaliteit instellen, indien nodig via AddServiceDefaults() of de specifieke functies:

  • Statuscontroles met /health en /alive eindpunten
  • Servicedetectie die een no-op zal zijn zonder de rest van .NET Aspire
  • Tolerantie voor HttpClient configureren die de aanvraag opnieuw probeert in het geval van fouten