Observabilité .NET avec OpenTelemetry

Lorsque vous exécutez une application, vous voulez connaître les performances de l’application et détecter les problèmes éventuels avant qu’ils ne prennent de l’ampleur. Vous pouvez le faire en émettant des données télémétriques telles que des journaux ou des métriques à partir de votre application, puis en surveillant et en analysant ces données.

Qu’est-ce que l’observabilité ?

L’observabilité dans le contexte d’un système distribué est la possibilité de surveiller et d’analyser la télémétrie sur l’état de chaque composant, d’être en mesure d’observer les variations des performances et de diagnostiquer la raison pour laquelle celles-ci se produisent. Contrairement au débogage, qui est envahissant et peut affecter le fonctionnement de l’application, l’observabilité est destinée à être transparente pour l’opération principale et à avoir un impact sur les performances suffisamment faible pour pouvoir être utilisée en continu.

L’observabilité est généralement effectuée à l’aide d’une combinaison des éléments suivants :

• Journaux, qui enregistrent des opérations individuelles, telles qu’une demande entrante, un échec dans un composant spécifique ou une commande passée.
• Métriques, qui mesurent les compteurs et les jauges, telles que le nombre de requêtes terminées, les requêtes actives, les widgets vendus ou un histogramme de la latence de la requête.
• Suivi distribué, qui effectue le suivi des demandes et des activités entre les composants d’un système distribué afin de voir où le temps est passé et de suivre les défaillances spécifiques.

Ensemble, les journaux, les métriques et le suivi distribué sont parfois appelés trois piliers de l’observabilité.

Il est possible que chaque pilier inclue des données de télémétrie des éléments suivants :

• Le runtime .NET, tel que le récupérateur de mémoire ou le compilateur JIT.
• Des bibliothèques, telles que Kestrel (le serveur web ASP.NET) et HttpClient.
• Une télémétrie spécifique à l’application émise par votre code.

Approches d’observabilité dans .NET

Il existe plusieurs façons d’atteindre l’observabilité dans des applications .NET :

• Explicitement dans le code, en référençant et en utilisant une bibliothèque comme OpenTelemetry. Si vous avez accès au code source et que vous pouvez régénérer l’application, il s’agit du mécanisme le plus puissant et le plus configurable.
• Out-of-process (hors processus) en utilisant EventPipe. *Des outils tels que dotnet-monitor peuvent écouter des journaux et des métriques, puis les traiter sans affecter de code.
• En tirant parti d’un crochet de démarrage, des assemblys peuvent être injectés dans le processus qui peut ensuite collecter une instrumentation. L’Instrumentation automatique dans .NET OpenTelemetry est un exemple de cette approche.

Qu’est-ce qu’OpenTelemetry ?

OpenTelemetry (OTel) est une norme ouverte multiplateforme destinée à la collecte et l’émission de données de télémétrie. OpenTelemetry comprend :

• Des API pour des bibliothèques à utiliser pour enregistrer des données de télémétrie pendant l’exécution du code.
• Des API que les développeurs d’applications utilisent pour configurer la partie des données enregistrées qui sera envoyée sur le réseau, l’emplacement vers lequel elle est envoyée et la manière dont elle peut être filtrée, mise en mémoire tampon, enrichie et transformée.
• Les conventions sémantiques fournissent des conseils sur l’attribution de noms et le contenu des données de télémétrie. Il est important que les applications qui produisent des données de télémétrie et les outils recevant celles-ci s’entendent sur la définition des différents types de données et les types de données utiles afin que les outils puissent fournir une analyse efficace.
• Interface pour des exporters. Les exporters sont des plug-ins qui permettent de transmettre des données de télémétrie dans des formats spécifiques à différents back-ends de télémétrie.
• La couche physique OTLP est une option de protocole réseau indépendant du fournisseur pour transmettre des données de télémétrie. Certains outils et fournisseurs prennent en charge ce protocole, outre les protocoles propriétaires préexistants qu’ils peuvent avoir.

L’utilisation d’OTel permet d’utiliser un large éventail de systèmes de monitoring des performances (APM), notamment des systèmes open source tels que Prometheus et Grafana, Azure Monitor, le produit APM de Microsoft dans Azure, ou de nombreux fournisseurs APM partenaires d’OpenTelemetry.

Il existe des implémentations OpenTelemetry pour la plupart des langages et plateformes, notamment .NET.

Implémentation de .NET d’OpenTelemetry

L’implémentation de .NET OpenTelemetry est légèrement différente des autres plateformes, car .NET fournit une journalisation, des métriques et des API d’activité dans l’infrastructure. Cela signifie qu’OTel n’a pas besoin de fournir des API que des créateurs de bibliothèque doivent utiliser. L’implémentation de .NET d’OTel utilise ces API de plateforme pour l’instrumentation :

• Microsoft.Extensions.Logging.ILogger<TCategoryName> pour la journalisation
• System.Diagnostics.Metrics.Meter pour les métriques
• System.Diagnostics.ActivitySource et System.Diagnostics.Activity pour le suivi distribué

OTel joue un rôle dans la collecte de télémétrie à partir de ces API et d’autres sources (via des bibliothèques d’instrumentation), puis l’exporte vers un système de monitoring des performances des applications (APM) pour le stockage et l’analyse. L’avantage qu’OTel apporte en tant que norme du secteur d’activité est un mécanisme commun aux collections, schémas et sémantiques courants pour des données de télémétrie et une API pour l’intégration des APM à OTel. L’utilisation d’OTel signifie que les applications n’ont pas besoin d’utiliser des API ou des structures de données spécifiques à APM, elles fonctionnent en fonction de la norme OTel. Les APM peuvent soit implémenter un composant exporter spécifique à APM, soit utiliser OTLP, qui est une nouvelle norme de couche physique pour exporter des données de télémétrie vers des systèmes APM.

Packages OpenTelemetry

L’infrastructure OpenTelemetry dans .NET est implémentée sous la forme d’une série de packages NuGet qui forment deux catégories :

• API Core
• Instrumentation : ces packages collectent une instrumentation à partir du runtime et des bibliothèques courantes.
• Exporters : ces systèmes interagissent avec des systèmes APM tels que Prometheus, Jaeger et OTLP.

Le tableau ci-après décrit les principaux packages.

Nom du package	Description
OpenTelemetry	Bibliothèque principale qui fournit les principales fonctionnalités d’OTEL
OpenTelemetry.Instrumentation.AspNetCore	Instrumentation pour ASP.NET Core et Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Instrumentation pour le client gRPC afin d’effectuer un suivi des appels gRPC sortants
OpenTelemetry.Instrumentation.Http	Instrumentation pour HttpClient et HttpWebRequest afin de suivre des appels HTTP sortants
OpenTelemetry.Instrumentation.SqlClient	Instrumentation utilisée pour SqlClient afin de tracer des opérations de base de données
OpenTelemetry.Exporter.Console	Exporter pour la console, couramment utilisé pour diagnostiquer la télémétrie qui est exportée
OpenTelemetry.Exporter.OpenTelemetryProtocol	Exporter utilisant le protocole OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore	Exporter pour Prometheus implémenté en tirant parti d’un point de terminaison ASP.NET Core
OpenTelemetry.Exporter.Zipkin	Exporter pour un suivi Zipkin

Exemples

Cette rubrique est poursuivie avec quelques exemples de procédures pas à pas pour l’utilisation d’OpenTelemetry dans .NET :

• Exemple : Utiliser OTLP et le tableau de bord Aspire autonome
• Exemple : Utiliser OpenTelemetry avec Azure Monitor et Application Insights
• Exemple : Utiliser OpenTelemetry avec Prometheus, Grafana et Jaeger

OpenTelemetry dans .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 ServiceDefaults projet, qui fait partie de la configuration et de la configuration d’OTel. Le projet Service Defaults est référencé et initialisé par chaque service dans une solution .NET Aspire.

Le modèle de projet Service Defaults inclut le Kit de développement logiciel (SDK) OTel, ASP.NET, les packages HttpClient et Runtime Instrumentation, et ceux-ci sont configurés dans le Extensions.cs fichier. Pour exporter la télémétrie .NET Aspire inclut l’exportateur OTLP par défaut afin qu’il puisse fournir une visualisation de télémétrie à l’aide du tableau de bord Aspire.

Le tableau de bord Aspire est conçu pour faire passer l’observation des données de télémétrie au cycle de débogage local, ce qui permet aux développeurs de s’assurer non seulement que les applications produisent des données de télémétrie, mais également d’utiliser cette télémétrie pour diagnostiquer ces applications localement. Être en mesure d’observer les appels entre les services s’avère aussi utile au moment du débogage qu’en production. Le tableau de bord Aspire .NET est lancé automatiquement lorsque vous F5 le AppHost projet à partir de Visual Studio ou dotnet run du AppHost projet.

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

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

Réutilisation du projet Par défaut du service sans orchestration .NET Aspire

Probablement le moyen le plus simple de configurer OTel pour les projets ASP.NET consiste à utiliser le projet Aspire Service Defaults, même s’il n’utilise pas 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 d’utilisation de ServiceDefaults en dehors de .NET Aspire sont les suivantes :

• Ajouter le projet ServiceDefaults à la solution à l’aide d’Ajouter un nouveau projet dans Visual Studio ou utiliser dotnet new aspire-servicedefaults --output ServiceDefaults
• Référencez le projet ServiceDefaults à partir de votre application ASP.NET. Dans Visual Studio, utilisez « Ajouter -> Référence de projet » et sélectionnez le projet ServiceDefaults »
• Appelez sa fonction de configuration OpenTelemetry dans le cadre de l’initialisation de votre générateur d’applications.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Les valeurs par défaut du service peuvent configurer les fonctionnalités supplémentaires suivantes si nécessaire ou les AddServiceDefaults() fonctions spécifiques :

• Vérifications d’intégrité avec /health et /alive points de terminaison
• Découverte de service qui sera sans opération sans le reste de .NET Aspire
• Configuration de la résilience pour HttpClient qui réessayera la requête en cas d’échecs