Ajouter, modifier et filtrer OpenTelemetry

  • Article

Cet article explique comment ajouter, modifier et filtrer OpenTelemetry pour les applications à l’aide d’Azure Monitor Application Insights.

Pour en savoir plus sur les concepts OpenTelemetry, consultez la vue d’ensemble d’OpenTelemetry ou les questions fréquentes (FAQ).

Collecte automatique des données

Les distributions collectent automatiquement les données en intégrant les bibliothèques d’instrumentation OpenTelemetry.

Bibliothèques d’instrumentation incluses

Demandes

Dépendances

Logging

  • ILogger

Pour plus d’informations sur ILogger, consultez Journalisation dans C# et .NET et les exemples de code.

Notes de bas de page

  • ¹ : prend en charge la création de rapports automatiques d’exceptions non gérées/non capturées
  • ² : prend en charge les métriques OpenTelemetry
  • ³ : par défaut, la journalisation est uniquement collectée au niveau d’INFO ou supérieur. Pour modifier ce paramètre, consultez les options de configuration.
  • ⁴ : par défaut, la journalisation est uniquement collectée lorsqu’elle est réalisée au niveau d'avertissement ou à un niveau supérieur.

Remarque

Les Distributions Azure Monitor OpenTelemetry incluent un mappage et une logique personnalisés pour émettre automatiquement des métriques standard Application Insights.

Conseil

Toutes les métriques OpenTelemetry collectées automatiquement à partir de bibliothèques d’instrumentation ou manuellement collectées à partir du codage personnalisé sont actuellement considérées comme des « métriques personnalisées » d’Application Insights à des fins de facturation. Plus d’informations

Ajouter une bibliothèque d’instrumentation de communauté

Vous pouvez collecter automatiquement davantage de données lorsque vous incluez des bibliothèques d’instrumentation de la communauté OpenTelemetry.

Attention

Nous ne prenons pas en charge et ne garantissons la qualité des bibliothèques d’instrumentation de la communauté. Pour en suggérer une pour notre distribution, publier ou voter dans nos commentaires de la communauté. N’oubliez pas que certaines sont basées sur des spécifications OpenTelemetry expérimentales et peuvent introduire des changements cassants futurs.

Pour ajouter une bibliothèque de communauté, utilisez les méthodes ConfigureOpenTelemetryMeterProvider ou ConfigureOpenTelemetryTracerProvider, après avoir ajouté le package NuGet pour la bibliothèque.

L'exemple suivant montre comment l'instrumentation du temps d'exécution peut être ajoutée pour collecter des données supplémentaires :

dotnet add package OpenTelemetry.Instrumentation.Runtime 

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add runtime instrumentation.
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddRuntimeInstrumentation());

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Collecter des données de télémétrie personnalisées

Cette section explique comment collecter des données de télémétrie personnalisées à partir de votre application.

Selon votre langage et votre type de signal, il existe différentes façons de collecter des données de télémétrie personnalisées, notamment :

  • API OpenTelemetry
  • Bibliothèques de métriques/journalisation spécifiques au langage
  • API classique Application Insights

Le tableau suivant représente les types de télémétrie personnalisés actuellement pris en charge :

Langage Événements personnalisés Métriques personnalisées Les dépendances Exceptions Affichages de pages Demandes Traces
ASP.NET Core
   API OpenTelemetry Oui Oui Oui Oui
   ILogger API Oui
   API IA classique
Java
   API OpenTelemetry Oui Oui Oui Oui
   Logback, Log4j, JUL Oui Oui
   Mesures Micrometer Oui
   API IA classique Oui Oui Oui Oui Oui Oui Oui
Node.JS
   API OpenTelemetry Oui Oui Oui Oui
Python
   API OpenTelemetry Oui Oui Oui Oui
   Module de journalisation Python Oui
   Extension d’événements Oui Oui

Notes

Application Insights Java 3.x écoute les données de télémétrie envoyées à l’API classique Application Insights. De même, Application Insights Node.js 3.x collecte les événements créés avec l’API classique Application Insights. Cela facilite la mise à niveau et comble un écart important dans notre prise en charge de la télémétrie personnalisée jusqu’à ce que tous les types de télémétrie personnalisés soient pris en charge via l’API OpenTelemetry.

Ajouter des métriques personnalisées

Dans ce contexte, le terme « métriques personnalisées » fait référence à l’instrumentation manuelle de votre code pour collecter des métriques supplémentaires au-delà de ce que les bibliothèques d’instrumentation OpenTelemetry collectent automatiquement.

L’API OpenTelemetry propose six « instruments » de métriques pour couvrir différents scénarios de métriques et vous devez choisir le « Type d’agrégation » correct lors de la visualisation des métriques dans Metrics Explorer. Cette exigence est vraie lors de l’utilisation de l’API de métrique OpenTelemetry pour envoyer des métriques et lors de l’utilisation d’une bibliothèque d’instrumentation.

Le tableau suivant présente les types d’agrégation recommandés pour chacun des instruments de métriques OpenTelemetry.

Instrumentation OpenTelemetry Type d’agrégation Azure Monitor
Compteur Sum
Compteur asynchrone Sum
Histogramme Min, Max, Moyenne, Somme et Nb
Jauge asynchrone Moyenne
UpDownCounter Sum
UpDownCounter asynchrone Sum

Attention

Les types d’agrégation au-delà des éléments affichés dans le tableau ne sont généralement pas significatifs.

La Spécification OpenTelemetry décrit les instruments et fournit des exemples de cas où vous pouvez utiliser chacun d’eux.

Conseil

L’histogramme est l’équivalent le plus versatile et le plus proche de l’API classique Application Insights GetMetric. Azure Monitor aplatit actuellement l’instrumentation de l’histogramme dans nos cinq types d’agrégation pris en charge. La prise en charge des centiles est en cours. Bien que moins polyvalents, les autres instruments OpenTelemetry ont un impact moindre sur les performances de votre application.

Exemple d’histogramme

Le start-up de l’application doit s’abonner à un compteur par nom :

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter doit être initialisé à l’aide de ce même nom :

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new histogram metric named "FruitSalePrice".
Histogram<long> myFruitSalePrice = meter.CreateHistogram<long>("FruitSalePrice");

// Create a new Random object.
var rand = new Random();

// Record a few random sale prices for apples and lemons, with different colors.
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "green"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "apple"), new("color", "red"));
myFruitSalePrice.Record(rand.Next(1, 1000), new("name", "lemon"), new("color", "yellow"));

Exemple de compteur

Le start-up de l’application doit s’abonner à un compteur par nom :

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter doit être initialisé à l’aide de ce même nom :

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new counter metric named "MyFruitCounter".
Counter<long> myFruitCounter = meter.CreateCounter<long>("MyFruitCounter");

// Record the number of fruits sold, grouped by name and color.
myFruitCounter.Add(1, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(2, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(1, new("name", "lemon"), new("color", "yellow"));
myFruitCounter.Add(2, new("name", "apple"), new("color", "green"));
myFruitCounter.Add(5, new("name", "apple"), new("color", "red"));
myFruitCounter.Add(4, new("name", "lemon"), new("color", "yellow"));

Exemple de jauge

Le start-up de l’application doit s’abonner à un compteur par nom :

// Create a new ASP.NET Core web application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry meter provider to add a meter named "OTel.AzureMonitor.Demo".
builder.Services.ConfigureOpenTelemetryMeterProvider((sp, builder) => builder.AddMeter("OTel.AzureMonitor.Demo"));

// Add the Azure Monitor telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core web application.
var app = builder.Build();

// Start the ASP.NET Core web application.
app.Run();

Meter doit être initialisé à l’aide de ce même nom :

// Get the current process.
var process = Process.GetCurrentProcess();

// Create a new meter named "OTel.AzureMonitor.Demo".
var meter = new Meter("OTel.AzureMonitor.Demo");

// Create a new observable gauge metric named "Thread.State".
// This metric will track the state of each thread in the current process.
ObservableGauge<int> myObservableGauge = meter.CreateObservableGauge("Thread.State", () => GetThreadState(process));

private static IEnumerable<Measurement<int>> GetThreadState(Process process)
{
    // Iterate over all threads in the current process.
    foreach (ProcessThread thread in process.Threads)
    {
        // Create a measurement for each thread, including the thread state, process ID, and thread ID.
        yield return new((int)thread.ThreadState, new("ProcessId", process.Id), new("ThreadId", thread.Id));
    }
}

Ajoutez des exceptions personnalisées

Sélectionnez des bibliothèques d’instrumentation qui signalent automatiquement les exceptions à Application Insights. Toutefois, vous pourriez signaler manuellement des exceptions au-delà du rapport des bibliothèques d’instrumentation. Par exemple, les exceptions interceptées par votre code ne sont généralement pas signalées. Vous pourriez les signaler pour attirer l’attention sur les expériences pertinentes, notamment la section relative aux défaillances et les vues des transactions de bout en bout.

  • Pour enregistrer une exception à l’aide d’une activité :

    // Start a new activity named "ExceptionExample".
using (var activity = activitySource.StartActivity("ExceptionExample"))
{
    // Try to execute some code.
    try
    {
        throw new Exception("Test exception");
    }
    // If an exception is thrown, catch it and set the activity status to "Error".
    catch (Exception ex)
    {
        activity?.SetStatus(ActivityStatusCode.Error);
        activity?.RecordException(ex);
    }
}

  • Pour enregistrer une exception à l’aide de ILogger :

    // Create a logger using the logger factory. The logger category name is used to filter and route log messages.
var logger = loggerFactory.CreateLogger(logCategoryName);

// Try to execute some code.
try
{
    throw new Exception("Test Exception");
}
catch (Exception ex)
{
    // Log an error message with the exception. The log level is set to "Error" and the event ID is set to 0.
    // The log message includes a template and a parameter. The template will be replaced with the value of the parameter when the log message is written.
    logger.Log(
        logLevel: LogLevel.Error,
        eventId: 0,
        exception: ex,
        message: "Hello {name}.",
        args: new object[] { "World" });
}

Ajouter des étendues personnalisées

Vous pourriez ajouter une étendue personnalisée dans deux scénarios. Tout d’abord, lorsqu’une requête de dépendance n’est pas encore collectée par une bibliothèque d’instrumentation. Deuxièmement, lorsque vous souhaitez modéliser un processus d’application en tant qu’étendue sur la vue transactionnelle de bout en bout.

Notes

Les classes Activity et ActivitySource de l’espace de noms System.Diagnostics représentent les concepts OpenTelemetry de Span et Tracer respectivement. Vous créez ActivitySource directement à l’aide de son constructeur à la place de TracerProvider. Chaque classe ActivitySource doit être explicitement connectée àTracerProvider à l’aide de AddSource() . Cela est dû au fait que des parties de l’API de suivi OpenTelemetry sont incorporées directement dans le runtime .NET. Pour plus d’informations, consultez Présentation de l’API de suivi .NET OpenTelemetry.

// Define an activity source named "ActivitySourceName". This activity source will be used to create activities for all requests to the application.
internal static readonly ActivitySource activitySource = new("ActivitySourceName");

// Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a source named "ActivitySourceName". This will ensure that all activities created by the activity source are traced.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Map a GET request to the root path ("/") to the specified action.
app.MapGet("/", () =>
{
    // Start a new activity named "CustomActivity". This activity will be traced and the trace data will be sent to Azure Monitor.
    using (var activity = activitySource.StartActivity("CustomActivity"))
    {
        // your code here
    }

    // Return a response message.
    return $"Hello World!";
});

// Start the ASP.NET Core application.
app.Run();

StartActivity a la valeur par défaut ActivityKind.Internal, mais vous pouvez fournir n’importe quel autre ActivityKind. ActivityKind.Client, ActivityKind.Producer et ActivityKind.Internal sont mappés sur Application Insights dependencies. ActivityKind.Server et ActivityKind.Consumer sont mappés sur Application Insights requests.

Envoyer une télémétrie personnalisée à l’aide de l’API Application Insights Classic

Nous vous recommandons d’utiliser les API OpenTelemetry dans la mesure du possible, mais il peut y avoir certains scénarios dans lesquels vous devez utiliser l’API classique d’Application Insights.

Événements

  1. Ajoutez Microsoft.ApplicationInsights à votre application :

  2. Créez une instance TelemetryClient :

    Remarque

    Il est important de créer une seule instance de TelemetryClient par application.

    var telemetryConfiguration = new TelemetryConfiguration { ConnectionString = "" };
var telemetryClient = new TelemetryClient(telemetryConfiguration);

  3. Utiliser le client pour envoyer des données de télémétrie personnalisées :

    telemetryClient.TrackEvent("testEvent");

Modifier la télémétrie

Cette section explique comment modifier la télémétrie.

Ajouter des attributs d’étendue

Ces attributs peuvent inclure l’ajout d’une propriété personnalisée à votre télémétrie. Vous pouvez également utiliser des attributs pour définir des champs facultatifs dans le schéma Application Insights, comme une adresse IP de client.

Ajoutez une propriété personnalisée à une étendue

Tous les attributs que vous ajoutez aux étendues sont exportés en tant que propriétés personnalisées. Ils remplissent le champ customDimensions dans la table des requêtes, des dépendances, des traces ou des exceptions.

Pour ajouter des attributs span, utilisez l’une des deux méthodes suivantes :

Conseil

L’avantage de l’utilisation des options fournies par les bibliothèques d’instrumentation, lorsqu’elles sont disponibles, est que tout le contexte est disponible. Par conséquent, les utilisateurs peuvent choisir d’ajouter ou de filtrer davantage d’attributs. Par exemple, l’option enrichir de la bibliothèque d’instrumentation HttpClient permet aux utilisateurs d’accéder au HttpRequestMessage et au HttpResponseMessage eux-mêmes. Ils peuvent sélectionner n’importe quoi et le stocker en tant qu’attribut.

  1. De nombreuses bibliothèques d’instrumentation fournissent une option enrichir. Pour obtenir de l’aide, consultez les fichiers Lisez-moi des bibliothèques d’instrumentation individuelles :

  2. Utilisation d’un processeur personnalisé :

    Conseil

    Ajoutez le processeur indiqué ici avant d’ajouter Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityEnrichingProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityEnrichingProcessor()));

// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Ajoutez ActivityEnrichingProcessor.cs à votre projet avec le code ci-dessous :

    public class ActivityEnrichingProcessor : BaseProcessor<Activity>
{
    public override void OnEnd(Activity activity)
    {
        // The updated activity will be available to all processors which are called after this processor.
        activity.DisplayName = "Updated-" + activity.DisplayName;
        activity.SetTag("CustomDimension1", "Value1");
        activity.SetTag("CustomDimension2", "Value2");
    }
}

Définir l’IP utilisateur

Vous pouvez renseigner le champ client_IP pour les requêtes en définissant un attribut sur l’étendue. Application Insights utilise l’adresse IP pour générer des attributs d’emplacement utilisateur, puis la supprime par défaut.

Utilisez l’exemple de propriété personnalisée, mais remplacez les lignes de code suivantes dans ActivityEnrichingProcessor.cs :

// Add the client IP address to the activity as a tag.
// only applicable in case of activity.Kind == Server
activity.SetTag("client.address", "<IP Address>");

Définir manuellement l’ID utilisateur ou l’ID utilisateur authentifié

Vous pouvez remplir le champ user_Id ou user_AuthenticatedId pour les requêtes à l’aide des instructions ci-dessous. L’ID d’utilisateur est un identificateur d’utilisateur anonyme. L’ID d’utilisateur authentifié est un identificateur d’utilisateur connu.

Important

Consultez les lois en vigueur inhérentes à la protection des données personnelles avant de définir l’ID d’utilisateur authentifié.

Utilisez l’exemple de propriété personnalisée :

// Add the user ID to the activity as a tag, but only if the activity is not null.
activity?.SetTag("enduser.id", "<User Id>");

Ajouter des attributs de journal

OpenTelemetry utilise le ILogger de .NET. Vous pouvez joindre des dimensions personnalisées aux journaux à l’aide d’un modèle de message.

Filtrer les données de télémétrie

Vous pouvez utiliser les méthodes suivantes pour filtrer les données de télémétrie avant qu’elles ne quittent votre application.

  1. De nombreuses bibliothèques d’instrumentation fournissent une option de filtre. Pour obtenir de l’aide, consultez les fichiers Lisez-moi des bibliothèques d’instrumentation individuelles :

  2. Utilisation d’un processeur personnalisé :

    Conseil

    Ajoutez le processeur indiqué ici avant d’ajouter Azure Monitor.

    // Create an ASP.NET Core application builder.
var builder = WebApplication.CreateBuilder(args);

// Configure the OpenTelemetry tracer provider to add a new processor named ActivityFilteringProcessor.
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddProcessor(new ActivityFilteringProcessor()));
// Configure the OpenTelemetry tracer provider to add a new source named "ActivitySourceName".
builder.Services.ConfigureOpenTelemetryTracerProvider((sp, builder) => builder.AddSource("ActivitySourceName"));
// Add the Azure Monitor telemetry service to the application. This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor();

// Build the ASP.NET Core application.
var app = builder.Build();

// Start the ASP.NET Core application.
app.Run();

    Ajoutez ActivityFilteringProcessor.cs à votre projet avec le code ci-dessous :

    public class ActivityFilteringProcessor : BaseProcessor<Activity>
{
    // The OnStart method is called when an activity is started. This is the ideal place to filter activities.
    public override void OnStart(Activity activity)
    {
        // prevents all exporters from exporting internal activities
        if (activity.Kind == ActivityKind.Internal)
        {
            activity.IsAllDataRequested = false;
        }
    }
}

  3. Si une source particulière n’est pas explicitement ajoutée à l’aide de AddSource("ActivitySourceName"), alors aucune des activités créées à l’aide de cette source n’est exportée.

Obtenir l’ID de trace ou l’ID d’étendue

Vous pouvez obtenir les Trace ID et Span ID de l’étendue actuellement active en suivant ces étapes.

Notes

Les classes Activity et ActivitySource de l’espace de noms System.Diagnostics représentent les concepts OpenTelemetry de Span et Tracer respectivement. Cela est dû au fait que des parties de l’API de suivi OpenTelemetry sont incorporées directement dans le runtime .NET. Pour plus d’informations, consultez Présentation de l’API de suivi .NET OpenTelemetry.

// Get the current activity.
Activity activity = Activity.Current;
// Get the trace ID of the activity.
string traceId = activity?.TraceId.ToHexString();
// Get the span ID of the activity.
string spanId = activity?.SpanId.ToHexString();

Étapes suivantes