Gedistribueerde tracering in System.Net bibliotheken

gedistribueerde tracering is een diagnostische techniek waarmee technici fouten en prestatieproblemen in toepassingen kunnen lokaliseren, met name die over meerdere machines of processen worden gedistribueerd. Met deze techniek worden aanvragen door een toepassing gevolgd, waarbij het werk dat door verschillende onderdelen wordt uitgevoerd wordt gerelateerd en gescheiden van ander werk dat de toepassing mogelijk uitvoert voor gelijktijdige aanvragen. Een aanvraag voor een typische webservice kan bijvoorbeeld eerst worden ontvangen door een load balancer en vervolgens worden doorgestuurd naar een webserverproces, waardoor vervolgens verschillende query's naar een database worden uitgevoerd. Met gedistribueerde tracering kunnen technici onderscheiden of een van deze stappen is mislukt en hoe lang elke stap duurde. Het kan ook berichten vastleggen die door elke stap worden geproduceerd terwijl ze worden uitgevoerd.

Het traceringssysteem in .NET is ontworpen om te werken met OpenTelemetry (OTel) en gebruikt OTel om de gegevens te exporteren naar bewakingssystemen. Tracering in .NET wordt geïmplementeerd met behulp van de System.Diagnostics API's, waarbij een werkeenheid wordt vertegenwoordigd door de System.Diagnostics.Activity klasse, die overeenkomt met een OTel-span. OpenTelemetry definieert een industriebreed standaardnaamgevingsschema voor spans (activiteiten) samen met hun kenmerken (tags), ook wel bekend als semantische conventies. De .NET-telemetrie maakt waar mogelijk gebruik van bestaande semantische conventies.

Instrumentatie

Als u traceringen wilt verzenden, worden de System.Net bibliotheken geïnstrueerd met ingebouwde ActivitySource bronnen, waarmee Activity objecten worden gemaakt om het uitgevoerde werk bij te houden. Activiteiten worden alleen gemaakt als er listeners zijn geabonneerd op de ActivitySource.

De ingebouwde instrumentatie is ontwikkeld met .NET-versies.

• Op .NET 8 en eerder is de instrumentatie beperkt tot het maken van een lege HTTP-clientaanvraagactiviteit. Dit betekent dat gebruikers moeten vertrouwen op de OpenTelemetry.Instrumentation.Http-bibliotheek om de activiteit te vullen met de informatie (bijvoorbeeld tags) die nodig zijn om nuttige traceringen te verzenden.
• .NET 9 heeft de instrumentatie uitgebreid door de naam, status, uitzonderingsinformatie en de belangrijkste tags uit te zenden volgens de semantische conventies van de OTel HTTP-client voor de HTTP-clientaanvraagactiviteit. Dit betekent dat op .NET 9+ de OpenTelemetry.Instrumentation.Http afhankelijkheid kan worden weggelaten, tenzij meer geavanceerde functies zoals verrijking vereist zijn.
• .NET 9 heeft ook experimentele verbindingstraceringgeïntroduceerd, waardoor nieuwe activiteiten in de System.Net bibliotheken worden toegevoegd ter ondersteuning van het diagnosticeren van verbindingsproblemen.

Traceringen voor System.Net verzamelen

Op het laagste niveauwordt traceringverzameling ondersteund via de methode AddActivityListener, waarmee ActivityListener objecten met door de gebruiker gedefinieerde logica worden geregistreerd.

Als ontwikkelaar van toepassingen zou u waarschijnlijk echter liever vertrouwen op het uitgebreide ecosysteem dat is gebaseerd op de functies van de OpenTelemetry .NET SDK om traceringen te verzamelen, exporteren en bewaken.

• Raadpleeg onze handleiding over het verzamelen van traces met OTel voor een fundamenteel begrip van het verzamelen van traces met behulp van OpenTelemetry.
• Voor productietijd traceringsverzameling en -bewaking kunt u OpenTelemetry gebruiken met Prometheus-, Grafana- en Jaeger- of met Azure Monitor- en Application Insights-. Deze hulpprogramma's zijn echter behoorlijk complex en kunnen onhandig zijn om tijdens de ontwikkeling te gebruiken.
• Voor ontwikkelingstijd traceringsverzameling en -bewaking raden we u aan .NET Aspire- te gebruiken. Dit biedt een eenvoudige maar uitbreidbare manier om gedistribueerde tracering in uw toepassing te starten en lokaal problemen te diagnosticeren.
• Het is ook mogelijk om het Aspire Service Defaults project te hergebruiken zonder de Aspire-orchestratie. Dit is een handige manier om OpenTelemetry-tracering en metrische gegevens in uw ASP.NET projecten te introduceren en te configureren.

Traceringen verzamelen met .NET Aspire

Een eenvoudige manier om traceringen en metrische gegevens te verzamelen in ASP.NET toepassingen is het gebruik van .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. Elke service in de .NET Aspire-oplossing heeft een verwijzing naar het servicestandaardproject. De services gebruiken deze om OTel in te stellen en te configureren.

De servicestandaardprojectsjabloon bevat de OTel SDK-, ASP.NET-, HttpClient- en Runtime Instrumentation-pakketten. Deze instrumentatieonderdelen worden geconfigureerd in het Extensions.cs-bestand. Ter ondersteuning van telemetrievisualisatie in Aspire Dashboard bevat het project Service Defaults standaard ook de OTLP-exporteur.

Aspire Dashboard is ontworpen om telemetrieobservatie naar de lokale foutopsporingscyclus te brengen, waardoor ontwikkelaars ervoor kunnen zorgen dat de toepassingen telemetrie produceren. De telemetrievisualisatie helpt ook om deze toepassingen lokaal te diagnosticeren. Het observeren van de aanroepen tussen services is net zo nuttig tijdens foutopsporingstijd als in productie. Het .NET Aspire-dashboard wordt automatisch gestart wanneer u F5 het AppHost project vanuit Visual Studio start of dotnet run het AppHost project vanaf de commandoregel.

Zie voor meer informatie over .NET Aspire:

• Overzicht van Aspire
• Telemetrie in Aspire
• Aspire Dashboard

Hergebruik Standaardinstellingen van het project zonder .NET Aspire Orchestration

Het project Aspire Service Defaults biedt een eenvoudige manier om OTel te configureren voor ASP.NET projecten, zelfs als de rest van .NET Aspire zoals de AppHost voor orchestration niet wordt gebruikt. 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 .NET Aspire zijn:

1. Voeg het ServiceDefaults--project toe aan de oplossing met behulp van Nieuw project toevoegen in Visual Studio of gebruik dotnet new:

   dotnet new aspire-servicedefaults --output ServiceDefaults
   

2. Raadpleeg de ServiceDefaults project vanuit uw ASP.NET toepassing. Selecteer in Visual Studio Voeg>projectreferentie toe en selecteer het ServiceDefaults project.

3. Roep de functie Voor het instellen van OpenTelemetry ConfigureOpenTelemetry() aan als onderdeel van de initialisatie van de opbouwfunctie voor toepassingen.

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

Zie Voorbeeld: OpenTelemetry gebruiken met OTLP en het zelfstandige Aspire Dashboardvoor een volledig overzicht.

Experimentele verbindingstracering

Bij het oplossen van HttpClient problemen of knelpunten kan het van cruciaal belang zijn om te zien waar tijd wordt besteed aan het verzenden van HTTP-aanvragen. Vaak treedt het probleem op tijdens het tot stand brengen van een HTTP-verbinding, wat doorgaans opsplitst in DNS-zoekopdracht, TCP-verbinding en TLS-handshake.

.NET 9 heeft experimentele verbindingstracering geïntroduceerd, waarbij een HTTP connection setup span wordt toegevoegd met drie onderliggende spanten die de DNS-, TCP- en TLS-fasen van de verbindingsinstelling vertegenwoordigen. Het HTTP-deel van de verbindingstracering wordt geïmplementeerd binnen SocketsHttpHandler, wat betekent dat het activiteitenmodel het onderliggende gedrag van de groepsgewijze verbinding moet respecteren.

.NET 9 heeft de volgende periodes geïntroduceerd om gedetailleerde verbindingsgegevens te verzamelen:

Deze reeksen zijn te uitgebreid voor gebruik van 24x7 in productiescenario's met hoge werkbelastingen. Ze zijn luidruchtig en dit instrumentatieniveau is normaal gesproken niet nodig. Als u echter verbindingsproblemen probeert te diagnosticeren of meer inzicht wilt krijgen in hoe de netwerk- en verbindingslatentie van invloed is op uw services, bieden ze inzicht dat moeilijk te verzamelen is op andere manieren.

Wanneer de Experimental.System.Net.Http.Connections ActivitySource is geactiveerd, bevat het HTTP client request bereik een koppeling naar het HTTP connection_setup bereik dat overeenkomt met de verbinding die de aanvraagafhandelt. Omdat een HTTP-verbinding lang kan duren, kan dit leiden tot veel koppelingen naar de verbindingsspanne van elk van de aanvraagactiviteiten. Sommige APM-bewakingshulpprogramma's volgen agressief koppelingen tussen tracesegmenten om hun rapportages op te stellen, en dus kan dit problemen veroorzaken wanneer de hulpprogramma's niet ontworpen zijn voor grote aantallen koppelingen.

Het volgende diagram illustreert het gedrag van de spanningen en hun relatie.

Overzicht: De experimentele verbindingstracering gebruiken in .NET 9

In dit scenario wordt gebruikgemaakt van een .NET 9 Aspire Starter App om verbindingstracering te demonstreren, maar het moet ook eenvoudig zijn om deze in te stellen met andere bewakingshulpprogramma's. De belangrijkste stap is het inschakelen van de ActivitySources.

1. Maak een .NET Aspire 9 Starter App met behulp van dotnet new:

   dotnet new aspire-starter-9 --output ConnectionTracingDemo
   

   Of in Visual Studio:

   

2. Open Extensions.cs in het ServiceDefaults project en bewerk de ConfigureOpenTelemetry methode om de ActivitySources toe te voegen voor verbinding in de callback van de traceringsconfiguratie:

   .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. Start de oplossing. Hiermee opent u het .NET Aspire Dashboard.

4. Ga naar de pagina Weer van de webfrontend-app om een HttpClient aanvraag te genereren voor apiservice.

5. Ga terug naar het dashboard en ga naar de pagina Traces. Open de webfrontend: GET /weather trace.

   

Wanneer HTTP-aanvragen worden gedaan met de verbindingsinstrumentatie ingeschakeld, ziet u de volgende wijzigingen in de clientaanvragen:

• Als er een verbinding tot stand moet worden gebracht of als de app wacht op een verbinding vanuit de verbindingsgroep, wordt een extra HTTP wait_for_connection bereik weergegeven, wat de vertraging aangeeft voor het wachten op een verbinding. Dit helpt bij het begrijpen van vertragingen tussen de HttpClient aanvraag die in code wordt ingediend en wanneer de verwerking van de aanvraag daadwerkelijk wordt gestart. In de vorige afbeelding:
  • De geselecteerde periode is de HttpClient-aanvraag.
  • De onderstaande periode vertegenwoordigt de tijd die de aanvraag besteedt aan het wachten tot er een verbinding tot stand is gebracht.
  • De laatste gedeelte in geel komt van de bestemming die het verzoek verwerkt.
• De HttpClient-span heeft een koppeling naar de HTTP connection_setup span, die de activiteit vertegenwoordigt voor het maken van de HTTP-verbinding die door de aanvraag wordt gebruikt.

Zoals eerder vermeld, is de HTTP connection_setup een afzonderlijke span met een eigen TraceId, omdat de levensduur onafhankelijk is van elk individueel klantverzoek. Deze span heeft meestal kind-spans DNS lookup, (TCP) socket connecten TLS client handshake.

Verrijking

In sommige gevallen is het nodig om de bestaande System.Net traceringsfunctionaliteit te verbeteren. Dit betekent meestal dat er extra tags/kenmerken worden toegevoegd aan de ingebouwde activiteiten. Dit wordt verrijkinggenoemd.

Verrijkings-API in de OpenTelemetry-instrumentatiebibliotheek

Als u extra tags/kenmerken wilt toevoegen aan de http-clientaanvraagactiviteit, is de eenvoudigste methode om de HttpClient verrijkings-API's te gebruiken van de OpenTelemetry HttpClient- en HttpWebRequest-instrumentatiebibliotheek. Hiervoor moet u afhankelijk zijn van het OpenTelemetry.Instrumentation.Http-pakket.

Handmatige verrijking

Het is mogelijk om de verrijking van de HTTP client request activiteit handmatig te implementeren. Hiervoor moet u toegang krijgen tot Activity.Current in de code die wordt uitgevoerd in het bereik van de aanvraagactiviteit, voordat de activiteit is voltooid. U kunt dit doen door een IObserver<DiagnosticListener> te implementeren en u te abonneren op AllListeners om callbacks op te halen voor wanneer netwerkactiviteit plaatsvindt. In feite is dit hoe de OpenTelemetry HttpClient- en HttpWebRequest-instrumentatiebibliotheek wordt geïmplementeerd. Zie de abonnementscode in DiagnosticSourceSubscriber.cs en de onderliggende implementatie in HttpHandlerDiagnosticListener.cs waar de meldingen worden gedelegeerd voor een codevoorbeeld.

Meer tracering nodig?

Als u suggesties hebt voor andere nuttige informatie die via tracering kan worden weergegeven, maakt u een dotnet/runtime-issue.