Distribuerad spårning i System.Net bibliotek

Distribuerad spårning är en diagnostikteknik som hjälper tekniker att lokalisera fel och prestandaproblem i program, särskilt de som distribueras över flera datorer eller processer. Den här tekniken spårar begäranden via ett program genom att korrelera arbete som utförs av olika komponenter och separera det från annat arbete som programmet kan utföra för samtidiga begäranden. En begäran till en vanlig webbtjänst kan till exempel först tas emot av en lastbalanserare och sedan vidarebefordras till en webbserverprocess, som sedan skickar flera frågor till en databas. Distribuerad spårning gör det möjligt för tekniker att skilja på om något av dessa steg misslyckades och hur lång tid varje steg tog. Den kan också logga meddelanden som skapas av varje steg medan det körs.

Spårningssystemet i .NET är utformat för att fungera med OpenTelemetry (OTel) och använder OTel för att exportera data till övervakningssystem. Spårning i .NET implementeras med hjälp av System.Diagnostics-API:er, där en arbetsenhet representeras av klassen System.Diagnostics.Activity, vilket motsvarar en OTel--spann. OpenTelemetry definierar ett branschomfattande standardnamnschema för intervall (aktiviteter) tillsammans med deras attribut (taggar), som kallas semantiska konventioner. .NET-telemetrin använder befintliga semantiska konventioner där det är möjligt.

Notera

Termerna sträcker sig över och aktivitet är synonyma i den här artikeln. I kontexten för .NET-kod refererar de till en System.Diagnostics.Activity instans. Blanda inte ihop OTel-spannet med System.Span<T>.

Tips

En omfattande lista över alla inbyggda aktiviteter tillsammans med deras taggar/attribut finns i inbyggda aktiviteter i .NET.

Instrumentation

För att generera spårningar System.Net biblioteken instrumenterade med inbyggda ActivitySource källor, som skapar Activity objekt för att spåra det utförda arbetet. Aktiviteter skapas bara om det finns lyssnare som prenumererar på ActivitySource.

Den inbyggda instrumentationen utvecklades med .NET-versioner.

• På .NET 8 och tidigare är instrumentationen begränsad till att skapa en tom HTTP-klientbegärandeaktivitet. Det innebär att användarna måste förlita sig på OpenTelemetry.Instrumentation.Http-biblioteket för att fylla i aktiviteten med den information (till exempel taggar) som behövs för att generera användbara spårningar.
• .NET 9 utökade instrumentationen genom att generera namn, status, undantagsinformation och de viktigaste taggarna enligt OTel-HTTP-klientsemantikkonventioner på HTTP-klientbegärandeaktiviteten. Det innebär att beroendet OpenTelemetry.Instrumentation.Http för .NET 9+ kan utelämnas, såvida inte mer avancerade funktioner som berikning krävs.
• .NET 9 introducerade också experimentell spårning av anslutningaroch lade till nya aktiviteter i System.Net biblioteken för att underlätta diagnostik av anslutningsproblem.

Samla in System.Net spårningar

På den lägsta nivånstöds spårningsinsamling via metoden AddActivityListener, som registrerar ActivityListener objekt som innehåller användardefinierad logik.

Men som programutvecklare föredrar du förmodligen att förlita dig på det omfattande ekosystemet som bygger på de funktioner som tillhandahålls av OpenTelemetry .NET SDK för att samla in, exportera och övervaka spårningar.

• Om du vill få en grundläggande förståelse för hur man med hjälp av OTel samlar in spårningar kan du läsa vår guide om insamling av spår med hjälp av OpenTelemetry.
• För produktionstid spårningsinsamling och övervakning kan du använda OpenTelemetry med Prometheus, Grafana och Jaeger eller med Azure Monitor och Application Insights. Dessa verktyg är dock ganska komplexa och kan vara obekväma att använda vid utvecklingstillfället.
• För spårningsinsamling och övervakning rekommenderar vi att du använder .NET Aspire- som ger ett enkelt men utökningsbart sätt att starta distribuerad spårning i din applikation och diagnostisera problem lokalt.
• Det går också att återanvända projektet Aspire Service Defaults utan att använda Aspire-orkestrering. Det här är ett praktiskt sätt att introducera och konfigurera OpenTelemetry-spårning och mått i dina ASP.NET projekt.

Samla in spårningar med .NET Aspire

Ett enkelt sätt att samla in spårningar och mått i ASP.NET program är att använda .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 ServiceDefaults projekt. Varje tjänst i .NET Aspire-lösningen har en referens till servicestandardprojektet. Tjänsterna använder den för att konfigurera OTel.

Projektmallen Service Defaults innehåller paketen OTel SDK, ASP.NET, HttpClient och Runtime Instrumentation. Dessa instrumentationskomponenter konfigureras i filen Extensions.cs. För att stödja telemetrivisualisering i Aspire-instrumentpanelen innehåller servicestandardprojektet även OTLP-exportören som standard.

Aspire Dashboard är utformad för att ge telemetriobservation till den lokala felsökningscykeln, vilket gör det möjligt för utvecklare att se till att programmen producerar telemetri. Telemetrivisualiseringen hjälper också till att diagnostisera dessa program lokalt. Att kunna observera anropen mellan tjänster är lika användbart vid felsökning som i produktion. .NET Aspire-instrumentpanelen startas automatiskt när du F5 det AppHost-projektet från Visual Studio eller dotnet runAppHost-projektet från kommandoraden.

Mer information om .NET Aspire finns i:

• Översikt av Aspire
• Telemetri i Aspire
• Aspire Dashboard

Återanvända standardinställningar för tjänster i projektet utan .NET Aspire Orchestration

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

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

1. Lägg till projektet ServiceDefaults i lösningen med hjälp av Lägg till nytt projekt i Visual Studio eller använd dotnet new:

   dotnet new aspire-servicedefaults --output ServiceDefaults
   

2. Referera till projektet ServiceDefaults från ditt ASP.NET-program. I Visual Studio väljer du Lägg till>projektreferens och väljer projektet ServiceDefaults"

3. Anropa installationsfunktionen OpenTelemetry ConfigureOpenTelemetry() som en del av programverktygets initiering.

   var builder = WebApplication.CreateBuilder(args)
   builder.ConfigureOpenTelemetry(); // Extension method from ServiceDefaults.
   var app = builder.Build();
   app.MapGet("/", () => "Hello World!");
   app.Run();
   

En fullständig genomgång finns i Exempel: Använd OpenTelemetry med OTLP och den fristående Aspire-instrumentpanelen.

Spårning av experimentella anslutningar

När du felsöker HttpClient problem eller flaskhalsar kan det vara viktigt att se var tiden spenderas när HTTP-begäranden skickas. Ofta uppstår problemet under HTTP-anslutningsetableringen, som vanligtvis delas upp till DNS-sökning, TCP-anslutning och TLS-handskakning.

.NET 9 introducerade experimentell anslutningsspårning och lade till ett HTTP connection setup spann med tre underordnade intervall som representerar DNS-, TCP- och TLS-faserna för anslutningsetableringen. HTTP-delen av anslutningsspårningen implementeras inom SocketsHttpHandler, vilket innebär att aktivitetsmodellen måste respektera det underliggande beteendet för anslutningspooler.

Obs

I SocketsHttpHandlerhar anslutningar och begäranden oberoende livscykeler. En poolanslutning kan leva länge och hantera många begäranden. Om det inte finns någon anslutning omedelbart tillgänglig i anslutningspoolen läggs begäran till i en begärandekö för att vänta på en tillgänglig anslutning. Det finns ingen direkt relation mellan väntande begäranden och anslutningar. Anslutningsprocessen kan ha startats när en annan anslutning blev tillgänglig för användning, i vilket fall den frigjorda anslutningen används. Därför är HTTP connection setup-spannet inte modellerat som ett barn till HTTP client request-spannet; i stället används spann-länkar.

.NET 9 introducerade följande intervall för att möjliggöra insamling av detaljerad anslutningsinformation:

Namn	ActivitySource	Beskrivning
HTTP wait_for_connection	Experimental.System.Net.Http.Connections	Ett underordnat intervall för HTTP client request som representerar det tidsintervall som begäran väntar på en tillgänglig anslutning i begärandekön.
HTTP connection_setup	Experimental.System.Net.Http.Connections	Representerar etableringen av HTTP-anslutningen. Ett separat spårningsrotsnitt med egen TraceId. HTTP client request intervall kan innehålla länkar till HTTP connection_setup.
DNS lookup	Experimental.System.Net.NameResolution	DNS-sökning som utförs av klassen Dns.
socket connect	Experimental.System.Net.Sockets	Upprätta en Socket-förbindelse.
TLS handshake	Experimental.System.Net.Security	TLS-klient- eller serverhandskakning utförd av SslStream.

Notera

Motsvarande ActivitySource namn börjar med prefixet Experimental, eftersom dessa intervall kan ändras i framtida versioner när vi lär oss mer om hur väl de fungerar i produktion.

Dessa intervall är för utförliga för användning 24x7 i produktionsscenarier med höga arbetsbelastningar – de är bullriga och den här nivån av instrumentation behövs normalt inte. Men om du försöker diagnostisera anslutningsproblem eller få en djupare förståelse för hur nätverks- och anslutningsfördröjning påverkar dina tjänster ger de insikter som är svåra att samla in på annat sätt.

När Experimental.System.Net.Http.Connections ActivitySource är aktiverat HTTP client request-intervallet innehåller en länk till det HTTP connection_setup span som motsvarar anslutningen som betjänar begäran. Eftersom en HTTP-anslutning kan vara långlivade kan det resultera i många länkar till anslutningsintervallet från var och en av begärandeaktiviteterna. Vissa APM-övervakningsverktyg följer aggressivt länkar mellan spann för att bygga upp sina vyer, vilket innebär att när detta spann inkluderas kan det orsaka problem när verktygen inte har utformats för att ta hänsyn till ett stort antal länkar.

Följande diagram illustrerar beteendet för spann och deras relation:

Genomgång: Använda den experimentella anslutningsspårningen i .NET 9

Den här handledningen använder en .NET 9 Aspire Starter App för att demonstrera anslutningsspårning, men det bör vara enkelt att sätta upp den med andra övervakningsverktyg också. Det viktigaste steget är att aktivera ActivitySources.

1. Skapa en .NET Aspire 9 Starter App med hjälp av dotnet new:

   dotnet new aspire-starter-9 --output ConnectionTracingDemo
   

   Eller i Visual Studio:

   

2. Öppna Extensions.cs i ServiceDefaults-projektet och redigera ConfigureOpenTelemetry-metoden och lägg till ActivitySources för anslutning i återanropet för spårningskonfiguration:

   .WithTracing(tracing =>
   {
       tracing.AddAspNetCoreInstrumentation()
           // Instead of using .AddHttpClientInstrumentation()
           // .NET 9 allows to add the ActivitySources directly.
           .AddSource("System.Net.Http")
           // Add the experimental connection tracking ActivitySources using a wildcard.
           .AddSource("Experimental.System.Net.*");
   });
   

3. Starta lösningen. Detta bör öppna .NET Aspire-instrumentpanelen.

4. Gå till sidan Väder i appen webfrontend för att generera en HttpClient begäran till apiservice.

5. Gå tillbaka till instrumentpanelen och gå till sidan Traces. Öppna webfrontend: GET /weather spårningen.

   

När HTTP-begäranden görs med anslutningsinstrumentationen aktiverad bör du se följande ändringar i klientbegäransintervall:

• Om en anslutning behöver upprättas, eller om appen väntar på en anslutning från anslutningspoolen, visas ytterligare ett HTTP wait_for_connection spann, vilket representerar fördröjningen för väntan på att en anslutning ska upprättas. Detta hjälper dig att förstå fördröjningarna mellan det att HttpClient-begäran görs i kod och när bearbetningen av begäran faktiskt startar. I föregående bild:
  • Det valda intervallet är HttpClient-begäran.
  • Intervallet nedan representerar den tid som begäran ägnar åt att vänta på att en anslutning upprättas.
  • Den sista sektionen i gult är från destinationen som bearbetar begäran.
• HttpClient-intervallet har en länk till HTTP connection_setup-intervallet, som representerar aktiviteten för att skapa HTTP-anslutningen som används av begäran.

Som tidigare nämntsär HTTP connection_setup spannet ett separat spann med egna TraceIdeftersom dess livslängd är oberoende av varje enskild klientbegäran. Det här intervallet har vanligtvis underordnade intervall DNS lookup, (TCP) socket connectoch TLS client handshake.

Anrikning

I vissa fall är det nödvändigt att utöka befintliga System.Net spårningsfunktioner. Detta innebär vanligtvis att ytterligare taggar/attribut matas in i de inbyggda aktiviteterna. Detta kallas berikning.

Api för berikning i instrumentationsbiblioteket OpenTelemetry

Om du vill lägga till ytterligare taggar/attribut till en HTTP-klientbegärans aktivitet, är det enklaste sättet att använda berikande-API:erna för HttpClient i instrumentationsbiblioteket för OpenTelemetry HttpClient och HttpWebRequest. Detta kräver att du är beroende av OpenTelemetry.Instrumentation.Http-paketet.

Manuell berikning

Det går att implementera berikning av HTTP client request-aktiviteten manuellt. För detta måste du komma åt Activity.Current i koden som körs i omfånget för begärandeaktiviteten innan aktiviteten är klar. Detta kan göras genom att implementera en IObserver<DiagnosticListener> och prenumerera på AllListeners för att få återanrop när nätverksaktivitet äger rum. I själva verket är det så OpenTelemetry HttpClient och HttpWebRequest instrumentationsbiblioteket implementeras. Ett kodexempel finns i prenumerationskoden i DiagnosticSourceSubscriber.cs och den underliggande implementeringen i HttpHandlerDiagnosticListener.cs där meddelandena delegeras till.

Behöver du mer spårning?

Om du har förslag på annan användbar information som kan exponeras via spårning, skapa ett dotnet/runtime-ärende.