Utiliser OpenTelemetry avec OTLP et le Aspire tableau de bord

Cet article explique comment instrumenter une API web .NET avec OpenTelemetry et envoyer ses journaux, métriques et traces au Aspire tableau de bord en utilisant OTLP. Vous ajoutez les packages OpenTelemetry, configurez des métriques et des traces personnalisées et affichez les résultats dans le tableau de bord.

Le Aspire tableau de bord est une partie standard de Aspire, mais il est également disponible en tant que conteneur Docker autonome qui fournit un point de terminaison OTLP pour l’envoi de données de télémétrie. Le tableau de bord visualise les logs, les métriques 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 envoie des données de télémétrie à l’aide d’OTLP. Il fonctionne également bien pour les applications écrites dans Java, Go ou Python, à condition qu’elles puissent envoyer leurs données de télémétrie à un point de terminaison OTLP.

Le Aspire tableau de bord nécessite moins de configuration et moins d’étapes de configuration que les solutions open source telles que Prometheus, Grafana et Jaeger. Mais contrairement à ces outils, le Aspire tableau de bord est un outil de visualisation de développeur, et non un outil de supervision de 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. Faites référence aux packages OpenTelemetry

Pour ajouter les packages OpenTelemetry, utilisez le Gestionnaire de package NuGet ou exécutez les commandes suivantes dotnet add package :

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http

Vous pouvez également ajouter les éléments suivants PackageReference directement au fichier projet :

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

3. Ajouter des directives using

Ajoutez les directives suivantes using en haut du fichier :

using System.Diagnostics;
using System.Diagnostics.Metrics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

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

Le code suivant définit une nouvelle métrique (greetings.count) qui compte le nombre de fois où un client appelle l’API et une nouvelle source d’activité (Otel.Example). Insérez ce code avant builder.Build:

// 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");

5. Configurer OpenTelemetry avec les fournisseurs appropriés

Insérez le code suivant avant builder.Build :

// Configure the shared OTLP connection used by logs, metrics, and traces.
var otlpEndpoint = new Uri(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]!);
Action<OtlpExporterOptions> configureOtlp = options =>
{
    options.Endpoint = otlpEndpoint;
    options.Protocol = OtlpExportProtocol.Grpc;
    options.Headers = builder.Configuration["OTEL_EXPORTER_OTLP_HEADERS"]; // To secure endpoint (not in this example)
};

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

var otel = builder.Services.AddOpenTelemetry();

// Identify this application as a single service in the Aspire dashboard.
otel.ConfigureResource(resource => resource.AddService(builder.Configuration["OTEL_SERVICE_NAME"]!));

// 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 provided by ASP.NET Core in .NET
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");

    // Export the metrics via OTLP
    metrics.AddOtlpExporter(configureOtlp);
});

// 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);
    tracing.AddOtlpExporter(configureOtlp);
});

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

• Il ajoute un fournisseur OTel sur ILogger collecter les enregistrements de journal.
• Il configure des métriques, en inscrivant des fournisseurs d’instrumentation et des compteurs pour ASP.NET et le compteur personnalisé.
• Il met en place le traçage en enregistrant les fournisseurs d’instrumentation et l’élément personnalisé ActivitySource.

Il inscrit ensuite l’exportateur OTLP à l’aide de variables d’environnement pour sa configuration.

6. Configurer les paramètres OTLP

Vous pouvez configurer l’exportateur OTLP via des API dans le code, les variables d’environnement ou la configuration de l’application. Pour cet exemple, ajoutez les paramètres OTLP à la racine de appsettings.Development.json, après la Logging section :

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
  "OTEL_SERVICE_NAME": "OTLP-Example"
}

Ajoutez d’autres paramètres pour l’exportateur OTLP .NET ou des paramètres OTel courants tels que OTEL_RESOURCE_ATTRIBUTES pour définir des attributs de ressource.

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

Insérez 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!";
}

8. Démarrer le Aspire conteneur Tableau de bord

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 nécessite un jeton d’authentification pour se connecter. Le conteneur affiche ce jeton dans sa sortie.

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

9. Exécuter le projet

Exécutez le projet avec dotnet run. La sortie de la console affiche les URL sur laquelle l’application écoute, par exemple :

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5086

Utilisez le port affiché dans votre propre sortie de console, car il peut différer des exemples de cet article. Utilisez un navigateur ou un curl pour accéder à l’API sur ce port :

curl -k http://localhost:5086

Chaque fois que vous demandez la page, le nombre de salutations augmente.

9.1 Sortie du journal

Le code consigne les messages à l’aide de ILogger. Par défaut, .NET active le fournisseur de console, qui dirige la sortie vers la console.

Vous pouvez extraire des journaux d’activité de .NET de plusieurs façons :

• Les systèmes de conteneurs tels que Kubernetes redirigent la sortie de stderr et de stdout vers des fichiers journaux.
• Utilisez des bibliothèques de journalisation qui s’intègrent à ILogger, telles que Serilog et NLog.
• Utilisez des fournisseurs de journalisation pour OTel, tels que OTLP. La section de journalisation du code à l’étape 5 ajoute le fournisseur OTel.

Le tableau de bord affiche les journaux sous forme de journaux structurés. Toutes les propriétés que vous définissez dans le message de journal deviennent des champs dans l’enregistrement du journal.

9.2 Vue des métriques

Le Aspire tableau de bord affiche les métriques par ressource. Une ressource est le terme OTel pour une source de télémétrie, telle qu’un processus. Lorsque vous sélectionnez une ressource, le tableau de bord répertorie chaque métrique que la ressource a envoyée à son point de terminaison OTLP. La liste des métriques est dynamique et elle est mise à jour à mesure que le tableau de bord reçoit de nouvelles métriques.

La vue des métriques dépend du type de métrique que vous utilisez :

• Le tableau de bord affiche directement les compteurs.
• Pour les histogrammes qui suivent une valeur par requête, comme une durée ou le nombre d’octets envoyés par requête, le tableau de bord regroupe les valeurs dans une série de classes et représente graphiquement 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 ou l’ID d’étendue pour cette requête. Le tableau de bord affiche ces points sous forme de points sur le graphique. Sélectionnez-en une pour accéder à la trace respective, afin de voir ce qui a provoqué cette valeur. Cette fonctionnalité vous aide à diagnostiquer les valeurs hors norme.
• Les métriques peuvent inclure des dimensions, qui sont des paires clé/valeur associées à des valeurs individuelles. Le tableau de bord agrège les valeurs par dimension. Utilisez les listes déroulantes de la vue pour filtrer les résultats en fonction de dimensions spécifiques, telles que GET les requêtes uniquement ou un itinéraire d’URL spécifique dans ASP.NET.

9.3 Vue de traçage

La vue de suivi répertorie les traces. Chaque trace est un ensemble d’activités qui partagent le même ID de trace. Les spans assurent le suivi du travail, et chaque span représente une 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 chaque span, vous créez une hiérarchie de spans que vous pouvez visualiser. Lorsque vous collectez des étendues à partir de chaque ressource (processus), vous pouvez suivre le travail sur une série de services. Les requêtes HTTP incluent un en-tête qui transmet l’identifiant de trace et l’identifiant du span parent au service suivant. Chaque ressource doit collecter des données de télémétrie et l’envoyer au même collecteur, qui agrège et présente ensuite une hiérarchie des étendues.

Le tableau de bord affiche une liste de traces avec des informations récapitulatives. Chaque fois que le tableau de bord détecte des spans avec un nouvel identifiant de trace, il ajoute une ligne au tableau. Sélectionnez Affichage pour afficher toutes les étendues de la trace.

Sélectionnez une étendue pour afficher ses détails, y compris les propriétés de l’étendue, telles que la balise que vous définissez à l’étape greeting7.