Suivi distribué dans les bibliothèques System.Net

Traçage distribué est une technique de diagnostic qui aide les ingénieurs à localiser les défaillances et les problèmes de performances au sein des applications, notamment celles qui sont distribuées sur plusieurs ordinateurs ou processus. Cette technique effectue le suivi des requêtes par le biais d’une application en corrélant le travail effectué par différents composants et en le séparant d’autres tâches que l’application peut effectuer pour les requêtes simultanées. Par exemple, une demande adressée à un service web classique peut d’abord être reçue par un équilibreur de charge, puis transférée à un processus de serveur web, ce qui effectue ensuite plusieurs requêtes vers une base de données. Le suivi distribué permet aux ingénieurs de distinguer si l’une de ces étapes a échoué et combien de temps chaque étape a pris. Il peut également consigner les messages générés par chaque étape lors de son exécution.

Le système de suivi dans .NET est conçu pour fonctionner avec OpenTelemetry (OTel) et utilise OTel pour exporter les données vers des systèmes de surveillance. Le suivi dans .NET est implémenté à l’aide des API System.Diagnostics, où une unité de travail est représentée par la classe System.Diagnostics.Activity, qui correspond à une étendue de OTel. OpenTelemetry définit un système de dénomination normalisé à l’échelle du secteur pour les étendues (activités) ainsi que leurs attributs (balises), connus sous le nom de conventions sémantiques. La télémétrie .NET utilise des conventions sémantiques existantes dans la mesure du possible.

Remarque

Dans cet article, les termes étendues et activité sont synonymes. Dans le contexte du code .NET, ils font référence à une instance de System.Diagnostics.Activity. Ne confondez pas l’étendue OTel avec System.Span<T>.

Conseil

Pour obtenir la liste complète de toutes les activités intégrées avec leurs balises/attributs, consultez activités intégrées dans .NET.

Instrumentation

Pour émettre des traces, les bibliothèques System.Net sont instrumentées avec des sources intégrées ActivitySource, qui créent des objets Activity pour suivre le travail effectué. Les activités sont créées uniquement s’il existe des auditeurs abonnés à la ActivitySource.

L’instrumentation intégrée a évolué avec les versions de .NET.

• Sur .NET 8 et versions antérieures, l’instrumentation est limitée à la création d’une activité de requête client HTTP vide . Cela signifie que les utilisateurs doivent s’appuyer sur la bibliothèque de OpenTelemetry.Instrumentation.Http pour remplir l’activité avec les informations (par exemple, les balises) nécessaires pour émettre des traces utiles.
• .NET 9 a étendu l'instrumentation en émettant le nom, l'état, les informations d'exception et les balises les plus importantes selon les conventions sémantiques OTel pour le client HTTP, concernant l'activité de requête du client HTTP. Cela signifie que sur .NET 9+, la dépendance OpenTelemetry.Instrumentation.Http peut être omise, sauf si des fonctionnalités plus avancées telles que 'enrichissement sont requises.
• .NET 9 a également introduit un suivi de connexion expérimental , en ajoutant de nouvelles activités dans les bibliothèques System.Net pour faciliter le diagnostic des problèmes de connexion.

Collecter des traces System.Net

Au niveau le plus bas, la collection de traces est prise en charge via la méthode AddActivityListener, qui enregistre ActivityListener objets contenant une logique définie par l'utilisateur.

Toutefois, en tant que développeur d’applications, vous préféreriez probablement vous appuyer sur l’écosystème riche basé sur les fonctionnalités fournies par le kit de développement logiciel (SDK) OpenTelemetry .NET pour collecter, exporter et surveiller les traces.

• Pour obtenir une compréhension fondamentale de la collecte de traces avec OTel, consultez notre guide sur la collecte de traces à l’aide d’OpenTelemetry.
• Pour la collecte et le suivi au moment de la production, vous pouvez utiliser OpenTelemetry avec Prometheus, Grafana et Jaeger ou avec Azure Monitor et Application Insights. Toutefois, ces outils sont assez complexes et peuvent être peu pratiques à utiliser au moment du développement.
• Pour la collecte et la surveillance de traces en temps de développement , nous vous recommandons d’utiliser .NET Aspire qui fournit un moyen simple mais extensible de lancer le suivi distribué dans votre application et de diagnostiquer les problèmes localement.
• Il est également possible de réutiliser le projet de défaut de service Aspire sans l’orchestration d’Aspire. Il s’agit d’un moyen pratique d’introduire et de configurer le suivi et les métriques OpenTelemetry dans vos projets ASP.NET.

Collecter des traces avec .NET Aspire

Un moyen simple de collecter des traces et des métriques dans ASP.NET applications consiste à utiliser .NET Aspire . .NET Aspire est un ensemble d’extensions à .NET pour faciliter la création et l’utilisation d’applications distribuées. L’un des avantages de l’utilisation de .NET Aspire est que la télémétrie est intégrée, à l’aide des bibliothèques OpenTelemetry pour .NET.

Les modèles de projet par défaut pour .NET Aspire contiennent un projet ServiceDefaults. Chaque service de la solution .NET Aspire a une référence au projet Service Defaults. Les services l’utilisent pour paramétrer et configurer OTel.

Le modèle de projet Service Defaults inclut les packages OTel SDK, ASP.NET, HttpClient et Runtime Instrumentation. Ces composants d’instrumentation sont configurés dans le fichier Extensions.cs. Pour prendre en charge la visualisation de télémétrie dans le Tableau de bord Aspire, le projet Service Defaults inclut également l'exportateur OTLP par défaut.

Le tableau de bord Aspire est conçu pour apporter une observation de télémétrie au cycle de débogage local, ce qui permet aux développeurs de s’assurer que les applications produisent des données de télémétrie. La visualisation de télémétrie permet également de diagnostiquer ces applications localement. La possibilité d’observer les appels entre les services est aussi utile au moment du débogage qu’en production. Le tableau de bord Aspire .NET est lancé automatiquement lorsque vous F5 le projet AppHost à partir de Visual Studio ou dotnet run le projet AppHost à partir de la ligne de commande.

Pour plus d’informations sur .NET Aspire, consultez :

• Vue d’ensemble d’Aspire
• Télémétrie dans Aspire
• Tableau de bord Aspire

Réutiliser le projet de défaut de service sans l’orchestration .NET Aspire

Le projet défaut de service Aspire offre un moyen simple de configurer OTel pour les projets ASP.NET, même sans utiliser le reste de .NET Aspire comme AppHost pour l’orchestration. Le projet Service Defaults est disponible en tant que modèle de projet via Visual Studio ou dotnet new. Il configure OTel et configure l’exportateur OTLP. Vous pouvez ensuite utiliser les variables d’environnement OTel pour configurer le point de terminaison OTLP pour envoyer des données de télémétrie et fournir les propriétés de ressource de l’application.

Les étapes à suivre pour utiliser ServiceDefaults en dehors de .NET Aspire sont les suivantes :

1. Ajoutez le projet ServiceDefaults à la solution à l’aide d’Ajouter un nouveau projet dans Visual Studio ou utilisez dotnet new:

   dotnet new aspire-servicedefaults --output ServiceDefaults
   

2. Référencez le projet ServiceDefaults à partir de votre application ASP.NET. Dans Visual Studio, sélectionnez Ajouter> de référence de projet, puis sélectionnez le projet ServiceDefaults »

3. Appelez la fonction de configuration OpenTelemetry ConfigureOpenTelemetry() dans le cadre de l’initialisation de votre générateur d’applications.

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

Pour obtenir une procédure pas à pas complète, consultez Exemple : Utiliser OpenTelemetry avec OTLP et le tableau de bord Aspire autonome.

Suivi de connexion expérimentale

Lors de la résolution des problèmes HttpClient ou des goulots d’étranglement, il peut être essentiel de voir où le temps est utilisé lors de l’envoi de requêtes HTTP. Souvent, le problème se produit lors de l'établissement de connexion HTTP, ce qui est généralement décomposé en recherche DNS, connexion TCP et établissement d'une liaison TLS.

.NET 9 a introduit un suivi de connexion expérimental en ajoutant une section HTTP connection setup avec trois sous-sections représentant les phases DNS, TCP et TLS de l’établissement de connexion. La partie HTTP du suivi de connexion est implémentée dans SocketsHttpHandler, ce qui signifie que le modèle d’activité doit respecter le comportement de regroupement de connexions sous-jacent.

Remarque

Dans SocketsHttpHandler, les connexions et les demandes ont des cycles de vie indépendants. Une connexion groupée peut avoir une longue durée de vie et traiter de nombreuses demandes. Lorsque vous effectuez une demande, s’il n’existe aucune connexion immédiatement disponible dans le pool de connexions, la demande est ajoutée à une file d’attente de requêtes pour attendre une connexion disponible. Il n’existe aucune relation directe entre les demandes en attente et les connexions. Le processus de connexion peut avoir démarré lorsqu’une autre connexion est devenue disponible pour être utilisée, auquel cas la connexion libérée est utilisée. Par conséquent, l’étendue HTTP connection setup n’est pas modélisée en tant qu’enfant de l’étendue HTTP client request ; Au lieu de cela, les liens d’étendue sont utilisés.

.NET 9 a introduit les étendues suivantes pour permettre la collecte d’informations de connexion détaillées :

Nom	ActivitySource	Description
HTTP wait_for_connection	Experimental.System.Net.Http.Connections	Étendue enfant de l’étendue HTTP client request qui représente l’intervalle de temps pendant lequel la requête attend une connexion disponible dans la file d’attente des requêtes.
HTTP connection_setup	Experimental.System.Net.Http.Connections	Représente l’établissement de la connexion HTTP. Une étendue racine de trace distincte avec son propre TraceId. Les segments HTTP client request peuvent contenir des liens vers HTTP connection_setup.
DNS lookup	Experimental.System.Net.NameResolution	Recherche DNS effectuée par la classe Dns.
socket connect	Experimental.System.Net.Sockets	Établissement d’une connexion Socket.
TLS handshake	Experimental.System.Net.Security	Négociation TLS client ou serveur effectuée par SslStream.

Remarque

Les noms ActivitySource correspondants commencent par le préfixe Experimental, car ces étendues peuvent être modifiées dans les versions ultérieures, à mesure que nous en apprenons davantage sur leur efficacité en production.

Ces étendues sont trop détaillées pour une utilisation 24 x 7 dans les scénarios de production avec des charges de travail élevées : elles sont bruyantes et ce niveau d’instrumentation n’est généralement pas nécessaire. Toutefois, si vous essayez de diagnostiquer les problèmes de connexion ou d’obtenir une compréhension plus approfondie de la façon dont la latence réseau et de connexion affecte vos services, ils fournissent des informations difficiles à collecter par d’autres moyens.

Lorsque l’ActivitySource Experimental.System.Net.Http.Connections est activée, l’étendue HTTP client request contient un lien vers l’étendue HTTP connection_setup correspondant à la connexion qui sert la requête. Comme une connexion HTTP peut être longue, cela peut entraîner de nombreux liens vers l’étendue de connexion de chacune des activités de requête. Certains outils de surveillance de l’APM explorent agressivement les liens entre les étendues pour construire leurs vues, de sorte que l’inclusion de cette étendue peut poser des problèmes lorsque les outils n’ont pas été conçus pour tenir compte d’un grand nombre de liens.

Le diagramme suivant illustre le comportement des étendues et de leur relation :

Procédure pas à pas : utilisation du suivi de connexion expérimental dans .NET 9

Cette procédure utilise une application .NET Aspire 9 Starter pour illustrer le suivi des connexions, mais il doit être facile de la configurer avec d’autres outils de surveillance également. L’étape clé consiste à activer ActivitySources.

1. Créez une application .NET Aspire 9 Starter à l’aide de dotnet new.

   dotnet new aspire-starter-9 --output ConnectionTracingDemo
   

   Ou dans Visual Studio :

   

2. Ouvrez Extensions.cs dans le projet ServiceDefaults, puis modifiez la méthode ConfigureOpenTelemetry en ajoutant ActivitySources pour la connexion dans le rappel de configuration de suivi :

   .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. Démarrez la solution. Cela doit ouvrir le tableau de bord .NET Aspire.

4. Accédez à la page Météo de l’application webfrontend pour générer une demande de HttpClient vers apiservice.

5. Revenez au tableau de bord et accédez à la page Traces. Ouvrez la trace webfrontend: GET /weather.

   

Lorsque les requêtes HTTP sont effectuées avec l’instrumentation de connexion activée, vous devez voir les modifications suivantes apportées aux étendues de requête du client :

• Si une connexion doit être établie ou si l’application attend une connexion à partir du pool de connexions, une étendue de HTTP wait_for_connection supplémentaire est affichée, ce qui représente le délai d’attente d’une connexion. Cela permet de comprendre les retards entre la requête HttpClient effectuée dans le code et le moment où le traitement de la demande démarre réellement. Dans l’image précédente :
  • L’étendue sélectionnée est la requête HttpClient.
  • L’intervalle ci-dessous représente le temps passé par la requête en attente d’établissement d’une connexion.
  • La dernière étendue en jaune provient du traitement de la requête par destination.
• L’étendue HttpClient aura un lien vers l’étendue de HTTP connection_setup, qui représente l’activité de création de la connexion HTTP utilisée par la requête.

Comme mentionné précédemment, l’étendue HTTP connection_setup est une étendue distincte avec sa propre TraceId, car sa durée de vie est indépendante de chaque demande cliente individuelle. Cette étendue comporte généralement des étendues enfants DNS lookup, (TCP) socket connect et TLS client handshake.

Enrichissement

Dans certains cas, il est nécessaire d’augmenter la fonctionnalité de suivi System.Net existante. En règle générale, cela signifie injecter des balises/attributs supplémentaires aux activités intégrées. On appelle cela l’enrichissement .

API d’enrichissement dans la bibliothèque d’instrumentation OpenTelemetry

Pour ajouter des balises/attributs supplémentaires à l’activité de requête client HTTP, l’approche la plus simple consiste à utiliser les API d’enrichissement HttpClient de la bibliothèque d’instrumentation HttpClient OpenTelemetry et HttpWebRequest. Cela nécessite de prendre une dépendance sur le package OpenTelemetry.Instrumentation.Http.

Enrichissement manuel

Il est possible d’implémenter manuellement l’enrichissement de l’activité HTTP client request. Pour cela, vous devez accéder à Activity.Current dans le code qui s'exécute dans le cadre de l'activité de requête, avant que l'activité ne soit terminée. Pour ce faire, implémentez un IObserver<DiagnosticListener>, pour ensuite l’abonner à AllListeners pour recevoir des notifications lorsque l’activité de mise en réseau se produit. En fait, il s’agit de la façon dont la bibliothèque d’instrumentation OpenTelemetry HttpClient et HttpWebRequest est implémentée. Pour obtenir un exemple de code, consultez le code d’abonnement dans DiagnosticSourceSubscriber.cs et l’implémentation sous-jacente dans HttpHandlerDiagnosticListener.cs où les notifications sont déléguées.

Avez-vous besoin de plus de traçage ?

Si vous avez des suggestions pour d’autres informations utiles qui peuvent être exposées via le traçage, créez un problème dotnet/runtime.