Partager via

Ajouter et modifier Azure Monitor OpenTelemetry pour les applications .NET, Java, Node.js et Python

Ce guide fournit des instructions sur l’intégration et la personnalisation de l’instrumentation OpenTelemetry (OTel) dans 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).

Remarque

Pour Azure Function Apps, consultez Utiliser OpenTelemetry avec Azure Functions.

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

Journalisation

  • ILogger

Pour réduire ou augmenter le nombre de journaux envoyés à Azure Monitor, configurez la journalisation pour définir le niveau de journal approprié ou appliquer des filtres. Par exemple, vous pouvez choisir d’envoyer uniquement les journaux Warning et Error à OpenTelemetry/Azure Monitor. OpenTelemetry ne contrôle pas le routage ni le filtrage des journaux. Votre configuration ILogger prend ces décisions. Pour plus d’informations sur la configuration ILogger, consultez Configurer la journalisation.

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

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 pour la 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, publiez ou votez dans notre communauté de feedback. 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 spécifiques au langage pour les métriques et la journalisation
  • 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 Interface de Programmation d'Applications (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

Remarque

Application Insights Java 3.x et Application Insights Node.js 3.x collectent les données de télémétrie à partir de l’API Classique Application Insights. Ce comportement simplifie les mises à niveau et prend temporairement en charge les données de télémétrie personnalisées jusqu’à ce que l’API OpenTelemetry inclut tous les types de données de télémétrie personnalisés.

Ajouter des métriques personnalisées

Dans ce contexte, le terme de 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 Somme
Compteur asynchrone Somme
Histogramme Min, Max, Moyenne, Somme et Nombre
Jauge asynchrone Moyenne
UpDownCounter Somme
UpDownCounter asynchrone Somme

Attention

Les autres types d’agrégation ne sont pas significatifs dans la plupart des cas.

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 polyvalent, d’autres instruments OpenTelemetry ont un moindre effet 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"));

Contre-exemple

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 plages personnalisées

Vous pourriez ajouter une période personnalisée dans deux cas. 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.

Remarque

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 les 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 des événements personnalisés

Application Insights stocke des événements personnalisés dans la customEvents table. Une façon d’analyser, de filtrer et de les visualiser consiste à utiliser les expériences d’utilisation d’Application Insights.

Si vous souhaitez automatiser la collection d’événements d’interaction côté client, vous pouvez utiliser le plug-in dans le Kit de développement logiciel (SDK) JavaScript.

Les événements personnalisés sont en préversion publique, et utilisent la version 1.3.0-beta.3 de Azure.Monitor.OpenTelemetry.AspNetCore.

Important

Consultez les Conditions d’utilisation supplémentaires pour les préversions Microsoft Azure pour les conditions légales qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou qui ne sont pas encore publiées en disponibilité générale.

Pour envoyer une CustomEvent en utilisant ILogger, définissez l’attribut "microsoft.custom_event.name" dans le modèle de message.

// Create a logger factory and configure OpenTelemetry with Azure Monitor
var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddOpenTelemetry(options =>
        {
            options.AddAzureMonitorLogExporter();
        });
});

// Create a logger for the specified category
var logger = loggerFactory.CreateLogger(logCategoryName);

// Log a custom event with a custom name and additional attribute
// The 'microsoft.custom_event.name' value will be used as the name of the customEvent
logger.LogInformation("{microsoft.custom_event.name} {additional_attrs}", "test-event-name", "val1");

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 d’enrichissement. Pour obtenir des conseils, consultez les fichiers README 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 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 fichier de log

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

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.

Remarque

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 les 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