Dela via

.NET-observerbarhet med OpenTelemetry

  • Artikel

När du kör ett program vill du veta hur bra appen presterar och identifiera potentiella problem innan de blir större. Du kan göra detta genom att generera telemetridata, till exempel loggar eller mått från din app, och sedan övervaka och analysera dessa data.

Vad är observerbarhet?

Observerbarhet i ett distribuerat system är möjligheten att övervaka och analysera telemetri om tillståndet för varje komponent, att kunna observera prestandaändringar och diagnostisera varför dessa ändringar sker. Till skillnad från felsökning, som är invasivt och kan påverka programmets funktion, är observerbarhet avsedd att vara transparent för den primära åtgärden och ha en tillräckligt liten prestandapåverkan att den kan användas kontinuerligt.

Observerbarhet görs ofta med hjälp av en kombination av:

  • Loggar som registrerar enskilda åtgärder, till exempel en inkommande begäran, ett fel i en specifik komponent eller en beställning som görs.
  • Mått som mäter räknare och mätare, till exempel antal slutförda begäranden, aktiva begäranden, widgetar som har sålts eller ett histogram över svarstiden för begäran.
  • Distribuerad spårning, som spårar begäranden och aktiviteter mellan komponenter i ett distribuerat system så att du kan se var tiden spenderas och spåra specifika fel.

Tillsammans kallas loggar, mått och distribuerad spårning ibland för de tre grundpelarna för observerbarhet.

Varje pelare kan innehålla telemetridata från:

  • .NET-körningen, till exempel skräpinsamlaren eller JIT-kompilatorn.
  • Bibliotek, till exempel från Kestrel (ASP.NET-webbservern) och HttpClient.
  • Programspecifik telemetri som genereras av din kod.

Observerbarhetsmetoder i .NET

Det finns några olika sätt att uppnå observerbarhet i .NET-program:

  • Explicit i kod genom att referera till och använda ett bibliotek som OpenTelemetry. Om du har åtkomst till källkoden och kan återskapa appen är detta den mest kraftfulla och konfigurerbara mekanismen.
  • Out-of-process med EventPipe. Verktyg som dotnet-monitor kan lyssna på loggar och mått och sedan bearbeta dem utan att påverka någon kod.
  • Med hjälp av en startkrok kan sammansättningar matas in i processen som sedan kan samla in instrumentation. Ett exempel på den här metoden är OpenTelemetry .NET Automatic Instrumentation.

Vad är OpenTelemetry?

OpenTelemetry (OTel) är en plattformsoberoende, öppen standard för insamling och sändning av telemetridata. OpenTelemetry innehåller:

  • API:er för bibliotek som ska användas för att registrera telemetridata när kod körs.
  • API:er som apputvecklare använder för att konfigurera vilken del av de registrerade data som ska skickas över nätverket, var de skickas till och hur de kan filtreras, buffras, berikas och transformeras.
  • Semantiska konventioner ger vägledning om namngivning och innehåll av telemetridata. Det är viktigt för de appar som producerar telemetridata och de verktyg som tar emot data att komma överens om vad olika typer av data innebär och vilka typer av data som är användbara så att verktygen kan tillhandahålla effektiv analys.
  • Ett gränssnitt för exportörer. Exportörer är plugin-program som gör att telemetridata kan överföras i specifika format till olika telemetri-serverdelar.
  • OTLP-trådprotokoll är ett leverantörsneutralt nätverksprotokollalternativ för överföring av telemetridata. Vissa verktyg och leverantörer stöder det här protokollet utöver befintliga patentskyddade protokoll som de kan ha.

Med OTel kan du använda en mängd olika APM-system, inklusive system med öppen källkod, till exempel Prometheus och Grafana, Azure Monitor – Microsofts APM-produkt i Azure eller från de många APM-leverantörer som samarbetar med OpenTelemetry.

Det finns OpenTelemetry-implementeringar för de flesta språk och plattformar, inklusive .NET.

.NET-implementering av OpenTelemetry

Implementeringen av .NET OpenTelemetry skiljer sig lite från andra plattformar eftersom .NET tillhandahåller loggning, mått och aktivitets-API:er i ramverket. Det innebär att OTel inte behöver tillhandahålla API:er som biblioteksförfattare kan använda. .NET OTel-implementeringen använder dessa plattforms-API:er för instrumentation:

.NET OTel-arkitektur

Där OTel spelar in är att det samlar in telemetri från dessa API:er och andra källor (via instrumentationsbibliotek) och sedan exporterar dem till ett APM-system (Application Performance Monitoring) för lagring och analys. Fördelen som OTel medför som branschstandard är en vanlig mekanism för insamling, vanliga scheman och semantik för telemetridata och ett API för hur API:er kan integreras med OTel. Att använda OTel innebär att program inte behöver använda APM-specifika API:er eller datastrukturer. de arbetar mot OTel-standarden. API:er kan antingen implementera en APM-specifik exportörskomponent eller använda OTLP, vilket är en ny trådstandard för att exportera telemetridata till APM-systemen.

OpenTelemetry-paket

OpenTelemetry i .NET implementeras som en serie NuGet-paket som utgör ett par kategorier:

  • Kärn-API
  • Instrumentation – dessa paket samlar in instrumentation från körningsmiljön och vanliga bibliotek.
  • Exportörer – dessa gränssnitt med APM-system som Prometheus, Jaeger och OTLP.

I följande tabell beskrivs huvudpaketen.

Paketnamn beskrivning
OpenTelemetry Huvudbiblioteket som tillhandahåller OTEL-kärnfunktionerna
OpenTelemetry.Instrumentation.AspNetCore Instrumentation för ASP.NET Core och Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient Instrumentation för gRPC-klienten för spårning av utgående gRPC-anrop
OpenTelemetry.Instrumentation.Http Instrumentation för och HttpWebRequest för HttpClient att spåra utgående HTTP-anrop
OpenTelemetry.Instrumentation.SqlClient Instrumentation för SqlClient att spåra databasåtgärder
OpenTelemetry.Exporter.Console Exportör för konsolen, som ofta används för att diagnostisera vilken telemetri som exporteras
OpenTelemetry.Exporter.OpenTelemetryProtocol Exportör med hjälp av OTLP-protokollet
OpenTelemetry.Exporter.Prometheus.AspNetCore Exportör för Prometheus implementerad med hjälp av en ASP.NET Core-slutpunkt
OpenTelemetry.Exporter.Zipkin Exportör för Zipkin-spårning

Exempel

Det här avsnittet fortsätter med ett par exempel på genomgångar för att använda OpenTelemetry i .NET:

OpenTelemetry i .NET Aspire

.NET Aspire är en uppsättning tillägg till .NET för att göra det enkelt att skapa och arbeta med distribuerade program. En av fördelarna med att använda .NET Aspire är att telemetri är inbyggd med hjälp av OpenTelemetry-biblioteken för .NET. Standardprojektmallarna för .NET Aspire innehåller ett projekt, varav en ServiceDefaults del är att konfigurera OTel. Service Defaults-projektet refereras till och initieras av varje tjänst i en .NET Aspire-lösning.

Projektmallen Service Defaults innehåller paketen OTel SDK, ASP.NET, HttpClient och Runtime Instrumentation och de är konfigurerade i Extensions.cs filen. För att exportera telemetri innehåller .NET Aspire OTLP-exportören som standard så att den kan tillhandahålla telemetrivisualisering med hjälp av Aspire-instrumentpanelen.

Aspire-instrumentpanelen är utformad för att ge telemetriobservation till den lokala felsökningscykeln, vilket gör det möjligt för utvecklare att inte bara se till att programmen producerar telemetri, utan även använda den telemetrin för att diagnostisera dessa program lokalt. Att kunna observera anropen mellan tjänster visar sig vara lika användbart vid felsökning som i produktion. .NET Aspire-instrumentpanelen startas automatiskt när du F5 AppHost projektet från Visual Studio eller dotnet run projektet AppHost .

Aspire-instrumentpanel

Mer information om .NET Aspire finns i:

Återanvända servicestandardprojekt utan .NET Aspire Orchestration

Förmodligen är det enklaste sättet att konfigurera OTel för ASP.NET projekt att använda projektet Aspire Service Defaults, även om du inte använder resten av .NET Aspire, till exempel AppHost för orkestrering. Service Defaults-projektet är tillgängligt som en projektmall via Visual Studio eller dotnet new. Den konfigurerar OTel och konfigurerar OTLP-exportören. Du kan sedan använda OTel-miljövariablerna för att konfigurera OTLP-slutpunkten för att skicka telemetri till och ange resursegenskaperna för programmet.

Stegen för att använda ServiceDefaults utanför .NET Aspire är:

  • Lägg till ServiceDefaults-projektet i lösningen med hjälp av Lägg till nytt projekt i Visual Studio eller använddotnet new aspire-servicedefaults --output ServiceDefaults
  • Referera till ServiceDefaults-projektet från ditt ASP.NET-program. I Visual Studio använder du "Lägg till –> projektreferens" och väljer ServiceDefaults-projektet
  • Anropa konfigurationsfunktionen OpenTelemetry som en del av initieringen av application builder.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Standardinställningar för tjänsten kan konfigurera följande ytterligare funktioner om det behövs via AddServiceDefaults() eller de specifika funktionerna:

  • Hälsokontroller med /health och /alive slutpunkter
  • Tjänstidentifiering som kommer att vara en no-op utan resten av .NET Aspire
  • Konfigurera motståndskraft för HttpClient som försöker begära igen vid fel