Exemple : Utilisez OpenTelemetry avec OTLP et le tableau de bord Aspire autonome

Cet article est l’une des séries d’exemples qui illustrent l’observabilité .NET avec OpenTelemetry.

En plus d’être une partie standard d’Aspire, le tableau de bord Aspire est disponible en tant que conteneur Docker autonome, qui fournit un point de terminaison OTLP auquel les données de télémétrie peuvent être envoyées. Le tableau de bord visualise les logs, les indicateurs et les traces. L’utilisation du tableau de bord de cette façon n’a aucune dépendance sur Aspire, et elle visualise les données de télémétrie à partir de n’importe quelle application qui l’envoie par le biais d’OTLP. Il fonctionne également bien pour les applications écrites en Java, GoLang ou Python, à condition qu’elles puissent envoyer leurs données de télémétrie à un point de terminaison OTLP.

L’utilisation du tableau de bord Aspire nécessite moins de configuration et d’étapes de mise en place que l’utilisation de solutions Open Source telles que Prometheus, Grafana et Jaeger. Mais contrairement à ces outils, le tableau de bord Aspire est destiné à être un outil de visualisation des développeurs, et non à la surveillance de la production.

1. Créer le projet

Créez un projet d’API web simple en utilisant le modèle ASP.NET Core vide dans Visual Studio ou la commande CLI .NET suivante :

dotnet new web

2. Ajouter des métriques et des définitions d’activité

Le code suivant définit une nouvelle métrique (greetings.count) correspondant au nombre de fois où l’API a été appelée et une nouvelle source d’activité (Otel.Example).

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. Créer un point de terminaison d’API

Insérer le code suivant entre builder.Build(); et app.Run()

app.MapGet("/", SendGreeting);

Insérez la fonction suivante en bas du fichier :

async Task<string> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

4. Référencer les packages OpenTelemetry

Utilisez le Gestionnaire de package NuGet ou la ligne de commande pour ajouter les packages NuGet suivants :

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

5. Configurer OpenTelemetry avec les fournisseurs appropriés

Insérez le code suivant avant builder.Build(); :

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

Ce code configure OpenTelemetry avec les différentes sources de télémétrie :

• Il ajoute un fournisseur OTel à ILogger pour collecter les enregistrements de journaux.
• Il configure les métriques, en enregistrant les fournisseurs d’instrumentation et les Meters pour ASP.NET ainsi que notre Meter personnalisé.
• Il configure la traçabilité, en enregistrant les fournisseurs d’instrumentation et notre ActivitySource personnalisé.

Il enregistre ensuite l’exportateur OTLP en utilisant des variables d’environnement pour sa configuration.

6. Configurer les variables d’environnement OTLP

L’exportateur OTLP peut être configuré via des API dans le code, mais il est plus courant de le configurer via des variables d’environnement. Ajoutez ce qui suit à AppSettings.Development.json

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

Vous pouvez ajouter des variables d’environnement supplémentaires pour l’exportateur OTLP .NET ou des variables OTel courantes telles que OTEL_RESOURCE_ATTRIBUTES pour définir les attributs de ressource.

7. Démarrer le conteneur Aspire Dashboard

Utilisez docker pour télécharger et exécuter le conteneur du tableau de bord.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

Les données affichées dans le tableau de bord peuvent être sensibles. Par défaut, le tableau de bord est sécurisé avec l’authentification qui nécessite un jeton pour se connecter. Le jeton est affiché dans le résultat de sortie lors de l’exécution du conteneur.

Copiez l’URL affichée, puis remplacez 0.0.0.0localhostpar , par exemple, http://localhost:18888/login?t=123456780abcdef123456780et ouvrez-la dans votre navigateur. Vous pouvez également coller la clé après que la boîte de dialogue de connexion soit affichée. Le jeton change chaque fois que vous démarrez le conteneur.

8. Exécuter le projet

Exécutez le projet, puis accédez à l’API avec le navigateur ou curl.

curl -k http://localhost:7275

Chaque fois que vous demandez la page, elle incrémente le nombre de salutations effectuées.

8.1 Sortie du journal

Les instructions de journalisation du code sont générées à l’aide de ILogger. Par défaut, le Fournisseur Console est activé afin que la sortie soit dirigée vers la console.

Il existe quelques options pour la façon dont les journaux d’activité peuvent être sortants de .NET :

• Les sorties stdout et stderr sont redirigées vers des fichiers journaux par des systèmes de conteneur tels que Kubernetes.
• Utilisation de bibliothèques de journalisation qui s’intègrent à ILogger. Ces bibliothèques incluent Serilog et NLog.
• Utilisation de fournisseurs de journalisation pour OTel tels que OTLP. La section journalisation dans le code de l’étape 5 ajoute le fournisseur OTel.

Les journaux sont affichés dans le tableau de bord sous forme de journaux structurés - toutes les propriétés que vous définissez dans le message de journal sont extraites comme champs dans l’enregistrement de journal.

8.2 Affichage des métriques

Le tableau de bord Aspire affiche les métriques sur une base par ressource (une ressource étant la façon OTel de parler des sources de télémétrie, telles qu’un processus). Lorsqu’une ressource est sélectionnée, le tableau de bord énumère chaque métrique envoyée à son point de terminaison OTLP par la ressource. La liste des métriques est dynamique et est mise à jour à mesure que de nouvelles métriques sont reçues.

La vue des métriques dépend du type de métrique utilisé :

• Les compteurs sont affichés directement.
• Les histogrammes qui effectuent le suivi d’une valeur par requête, comme un intervalle de temps ou des octets envoyés par requête, sont collectés dans une série de compartiments. Le tableau de bord affiche sous forme de graphique les percentiles P50, P90 et P99. Les résultats des histogrammes peuvent inclure des exemplaires, qui sont des points de données individuels avec l’ID de trace/span pour cette requête. Celles-ci sont affichées sous forme de points sur le graphique. La sélection d’un élément navigue vers la trace correspondante afin que vous puissiez voir ce qui s’est passé pour engendrer ce résultat. Cela est utile pour diagnostiquer les valeurs aberrantes.
• Les métriques peuvent inclure des dimensions, qui sont des paires clé/valeur associées à des valeurs individuelles. Les valeurs sont agrégées par dimension. Dans le menu déroulant de l'affichage, vous pouvez filtrer les résultats pour examiner des dimensions spécifiques, telles que les seules requêtes GET, ou celles d'une route d'URL spécifique dans ASP.NET.

8.3 Affichage de la traçabilité

L’affichage de suivi affiche une liste de traces. Chaque trace est un ensemble d’activités qui partagent le même traceId. Le travail est suivi avec des plages, qui servent d'unité de travail. Le traitement d’une requête ASP.NET crée un intervalle. La création d’une requête HttpClient est une étendue. En suivant le parent de l’étendue, une hiérarchie d’étendues peut être visualisées. En collectant les traces à partir de chaque ressource (processus), vous pouvez suivre l'activité qui se déroule dans une série de services. Les requêtes HTTP ont un en-tête utilisé pour passer l'identifiant de trace et l'identifiant de segment parent au service suivant. Chaque ressource doit collecter la télémétrie et l’envoyer au même collecteur. Il agrégera ensuite et présentera une hiérarchie des spans.

Le tableau de bord affiche une liste de traces avec des informations récapitulatives. Chaque fois que des tranches avec un nouveau traceId sont détectées, elles obtiennent une ligne dans la table. Le fait de cliquer sur "voir" montre toutes les étendues de la trace.

La sélection d’une étendue affiche ses détails, y compris les propriétés de l’étendue, telles que la balise que vous définissez à l’étape greeting3.