Configurer Azure Monitor OpenTelemetry

Ce guide explique comment configurer OpenTelemetry (OTel) dans Azure Monitor Application Insights à l’aide de la distribution Azure Monitor OpenTelemetry. Une configuration appropriée garantit une collecte cohérente des données de télémétrie entre .NET, Java, Node.jset les applications Python, ce qui permet une surveillance et des diagnostics plus fiables.

Remarque

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

Chaîne de connexion

Dans Application Insights, un chaîne de connexion définit l’emplacement cible pour l’envoi de données de télémétrie.

Utilisez l’une des trois méthodes suivantes pour configurer la chaîne de connexion :

  • Ajoutez UseAzureMonitor() à votre fichier program.cs.

        var builder = WebApplication.CreateBuilder(args);

    // Add the OpenTelemetry telemetry service to the application.
    // This service will collect and send telemetry data to Azure Monitor.
    builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
        options.ConnectionString = "<YOUR-CONNECTION-STRING>";
    });

    var app = builder.Build();

    app.Run();

  • Définissez une variable d’environnement.

    APPLICATIONINSIGHTS_CONNECTION_STRING=<YOUR-CONNECTION-STRING>

  • Ajoutez la section suivante au fichier config appsettings.json.

      {
    "AzureMonitor": {
        "ConnectionString": "<YOUR-CONNECTION-STRING>"
    }
  }

Remarque

Si vous définissez la chaîne de connexion à plusieurs endroits, l’ordre de priorité suivant s’applique :

  1. Code
  2. Variable d’environnement
  3. Fichier de configuration

Définir le nom du rôle cloud et l’instance de rôle cloud

Pour les langues prises en charge, Azure Monitor OpenTelemetry Distro détecte automatiquement le contexte de la ressource et fournit des valeurs par défaut pour les propriétés de Cloud Role Name et Cloud Role Instance de votre composant. Toutefois, vous pouvez remplacer les valeurs par défaut par un élément logique pour votre équipe. La valeur du nom du rôle cloud s’affiche sur la cartographie d’applications en tant que nom sous un nœud.

Définissez le nom du rôle cloud et l’instance de rôle cloud via les attributs de ressource . Le nom de rôle cloud utilise les attributs service.namespace et service.name, mais se replie sur service.name si service.namespace n'est pas défini. L’instance de rôle cloud utilise la valeur d’attribut service.instance.id. Pour plus d’informations sur les attributs standard pour les ressources, consultez Conventions sémantiques OpenTelemetry.

// Setting role name and role instance

// Create a dictionary of resource attributes.
var resourceAttributes = new Dictionary<string, object> {
    { "service.name", "my-service" },
    { "service.namespace", "my-namespace" },
    { "service.instance.id", "my-instance" }};

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry()
    .UseAzureMonitor()
    // Configure the ResourceBuilder to add the custom resource attributes to all signals.
    // Custom resource attributes should be added AFTER AzureMonitor to override the default ResourceDetectors.
    .ConfigureResource(resourceBuilder => resourceBuilder.AddAttributes(resourceAttributes));

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

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

Définir des attributs de ressource

L'instrumentation automatique et les distributions d'Azure Monitor activent la détection des ressources lors de l'exécution dans les environnements Azure pris en charge. Pour plus d’informations, consultez Collecte de données et détecteurs de ressources automatiques pour Azure Monitor OpenTelemetry.

Pour les configurations manuelles, définissez des attributs de ressource directement à l’aide des options OpenTelemetry standard :

# Applies to .NET (ASP.NET/ASP.NET Core), Java, Node.js, and Python
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Sur Windows PowerShell :

$Env:OTEL_SERVICE_NAME="my-service"
$Env:OTEL_RESOURCE_ATTRIBUTES="cloud.provider=azure,cloud.region=westus,cloud.resource_id=/subscriptions/<SUB>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<APP>"

Activer l’échantillonnage

L’échantillonnage réduit le volume et le coût d’ingestion de télémétrie. La distribution OpenTelemetry d’Azure Monitor prend en charge deux stratégies d’échantillonnage pour les traces et (éventuellement) vous permet d’aligner les journaux d’application sur vos décisions d’échantillonnage de trace. L’échantillonneur attache le ratio d’échantillonnage ou le taux sélectionné aux étendues exportées afin que Application Insights puisse ajuster le nombre d’expériences avec précision. Pour obtenir une vue d’ensemble conceptuelle, consultez En savoir plus sur l’échantillonnage.

Important

  • Les décisions d’échantillonnage s’appliquent aux traces (étendues).
  • Les journaux d’activité appartenant à des traces non échantillonnées sont supprimés par défaut, mais il est possible de désactiver l’échantillonnage basé sur les traces pour les journaux d’activité.
  • Les métriques ne sont jamais échantillonées.

Remarque

Si vous voyez des frais inattendus ou des coûts élevés dans Application Insights, les causes courantes incluent un volume élevé de télémétrie, des pics d’ingestion de données et un échantillonnage mal configuré. Pour démarrer la résolution des problèmes, consultez Résoudre les problèmes d’ingestion élevée des données dans Application Insights.

Configurer l’échantillonnage à l’aide de variables d’environnement

Utilisez des variables d’environnement OpenTelemetry standard pour sélectionner l’échantillonneur et fournir son argument. Pour plus d’informations sur les types d’échantillonneur OpenTelemetry, consultez OTEL_TRACES_SAMPLER.

  • OTEL_TRACES_SAMPLER Type d’échantillonneur â€"

    • microsoft.fixed_percentage Échantillonner une fraction de traces.
    • microsoft.rate_limited — nombre de traces par seconde.

  • OTEL_TRACES_SAMPLER_ARG — argument d’exemple

    • Pour microsoft.fixed_percentage: valeur dans 0,0â€"1.0 (par exemple, 0.1 = ~10%).
    • Pour microsoft.rate_limited: nombre maximal de traces par seconde (par exemple, 1.5).

Les exemples suivants montrent comment configurer l’échantillonnage à l’aide de variables d’environnement.

Remarque

Les exemples suivants ne sont pas valides pour Java. Pour connaître les variables d’environnement appropriées, consultez l’onglet Java précédent.

Échantillonnage à pourcentage fixe (~10%)

export OTEL_TRACES_SAMPLER="microsoft.fixed_percentage"
export OTEL_TRACES_SAMPLER_ARG=0.1

Échantillonnage limité par le débit (environ 1,5 traces/s)

export OTEL_TRACES_SAMPLER="microsoft.rate_limited"
export OTEL_TRACES_SAMPLER_ARG=1.5

Configurer l’échantillonnage dans le code

Remarque

Lorsque les options au niveau du code et les variables d’environnement sont configurées, les variables d’environnement sont prioritaires. Le comportement de l’échantillonneur par défaut peut différer selon la langue.

Échantillonnage de pourcentage fixe

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.SamplingRatio = 0.1F; // ~10%
});
var app = builder.Build();
app.Run();

Échantillonnage à fréquence limitée

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.TracesPerSecond = 1.5; // ~1.5 traces/sec
});
var app = builder.Build();
app.Run();

Remarque

Si vous ne définissez pas d'échantillonneur dans du code ou via des variables d'environnement, Azure Monitor utilise ApplicationInsightsSampler par défaut.

Conseil

Lorsque vous utilisez l’échantillonnage à pourcentage fixe et que vous ne savez pas quelle valeur définir pour le taux d’échantillonnage, commencez à 5% (0.05). Ajustez le taux en fonction de la précision des opérations affichées dans les volets des défaillances et des performances. Tout échantillonnage réduit la précision, c'est pourquoi il est conseillé de surveiller les métriques OpenTelemetry, qui ne sont pas affectées par l'échantillonnage.

Configurer l’échantillonnage dans le fichier de configuration

La configuration de l'échantillonnage dans un fichier de configuration n'est pas prise en charge pour ASP.NET Core. Pour configurer l’échantillonnage, utilisez plutôt des variables de code ou d’environnement.

Configurer l’échantillonnage basé sur la trace pour les journaux de logs

Lorsque vous activez cette fonctionnalité, le système supprime les enregistrements de journal qui appartiennent à des traces non échantillonnées afin que vos journaux restent alignés sur l’échantillonnage de traces.

  • Un enregistrement de journal fait partie d’une trace lorsqu’il a une valeur valide SpanId.
  • Si la trace associée est indiquée comme TraceFlags, la fonctionnalité supprime l’enregistrement du journal.
  • Les enregistrements de journal sans contexte de trace ne sont pas affectés.
  • La fonctionnalité est activée par défaut.

Utilisez les paramètres ci-dessous pour configurer l’échantillonnage des journaux d’activité basé sur les traces :

builder.Services.AddOpenTelemetry().UseAzureMonitor(o =>
{
    o.EnableTraceBasedLogsSampler = true;
});

Mesures actives

Mesures actives : fournissent un tableau de bord d’analyse en temps réel pour obtenir un aperçu de l’activité et de la performance de l’application.

Important

Consultez les conditions d’utilisation Supplemental pour les préversions Microsoft Azure pour connaître 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 dans la disponibilité générale.

Cette fonctionnalité est activée par défaut.

Les utilisateurs peuvent désactiver les mesures actives lors de la configuration de la distribution.

builder.Services.AddOpenTelemetry().UseAzureMonitor(options => {
	// Disable the Live Metrics feature.
    options.EnableLiveMetrics = false;
});

Activer l’authentification Microsoft Entra ID (anciennement Azure AD)

Pour créer une connexion plus sécurisée à Azure, activez l’authentification Microsoft Entra. Cette méthode d’authentification empêche l’ingestion de données de télémétrie non autorisées dans votre abonnement.

Pour plus d’informations, consultez la page d’authentification dédiée Microsoft Entra liée pour chaque langue prise en charge.

Pour plus d’informations sur la configuration de l’authentification Entra ID, consultez Microsoft Entra authentification pour Application Insights.

Stockage hors connexion et nouvelles tentatives automatiques

Les offres basées sur OpenTelemetry d'Azure Monitor mettent en cache la télémétrie lorsqu’une application se déconnecte d’Application Insights et réessaient de la renvoyer pendant un maximum de 48 heures. Pour obtenir des recommandations de gestion des données, consultez Exporter et supprimer des données privées. Les applications à charge élevée suppriment occasionnellement les données de télémétrie pour deux raisons : dépassement du temps autorisé ou dépassement de la taille maximale du fichier. Si nécessaire, le produit hiérarchise les événements récents sur les anciens.

Le package Distro inclus AzureMonitorExporter qui utilise l’un des emplacements suivants par défaut pour le stockage hors connexion (répertorié dans l’ordre de priorité) :

  • Windows

    • %LOCALAPPDATA%\Microsoft\AzureMonitor
    • %TEMP%\Microsoft\AzureMonitor

  • Autre que Windows

    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor
    • /tmp/Microsoft/AzureMonitor

Pour remplacer le répertoire par défaut, vous devez définir AzureMonitorOptions.StorageDirectory.

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

// Add the OpenTelemetry telemetry service to the application.
// This service will collect and send telemetry data to Azure Monitor.
builder.Services.AddOpenTelemetry().UseAzureMonitor(options =>
{
    // Set the Azure Monitor storage directory to "C:\\SomeDirectory".
    // This is the directory where the OpenTelemetry SDK will store any telemetry data that can't be sent to Azure Monitor immediately.
    options.StorageDirectory = "C:\\SomeDirectory";
});

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

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

Pour désactiver cette fonctionnalité, définissez AzureMonitorOptions.DisableOfflineStorage = true.

Activer l’exportateur OTLP

Vous souhaiterez peut-être activer l’exportateur OTLP (OpenTelemetry Protocol) en même temps que le Azure Monitor Exporter pour envoyer vos données de télémétrie à deux emplacements.

Remarque

OTLP Exporter est illustré pour des raisons pratiques uniquement. Microsoft ne prend pas officiellement en charge l'exportateur OTLP ni les composants ou les expériences tierces en aval.

  1. Installez le package OpenTelemetry.Exporter.OpenTelemetryProtocol dans votre projet.

    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol

  2. Ajoutez l’extrait de code suivant : Cet exemple suppose que vous disposez d’un OpenTelemetry Collector avec un récepteur OTLP en cours d’exécution. Pour plus d’informations, consultez le example sur GitHub.

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

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

// Add the OpenTelemetry OTLP exporter to the application.
// This exporter will send telemetry data to an OTLP receiver, such as Prometheus
builder.Services.AddOpenTelemetry().WithTracing(builder => builder.AddOtlpExporter());
builder.Services.AddOpenTelemetry().WithMetrics(builder => builder.AddOtlpExporter());

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

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

Configurations OpenTelemetry

Vous pouvez accéder aux configurations OpenTelemetry suivantes via des variables d’environnement lors de l’utilisation des distributions OpenTelemetry Azure Monitor.

Variable d’environnement Descriptif
APPLICATIONINSIGHTS_CONNECTION_STRING Définissez cette variable sur la chaîne de connexion de votre ressource Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Définissez cette variable à true pour désactiver la collecte de métriques internes.
OTEL_RESOURCE_ATTRIBUTES Paires clé-valeur à utiliser comme attributs de ressource. Pour plus d’informations sur les attributs de ressource, consultez la Spécification du Kit de développement logiciel (SDK) de ressources.
OTEL_SERVICE_NAME Définit la valeur de l’attribut de ressource service.name. Si service.name est également fourni dans OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME prend la priorité.

Éditer les chaînes de requête dans les URL

Pour masquer les chaînes de requête d’URL, désactivez la collecte de chaînes de requête. Ce paramètre est recommandé si vous appelez Azure stockage à l’aide d’un jeton SAP.

Lorsque vous utilisez le Azure. Monitor.OpenTelemetry.AspNetCore package de distribution, il inclut les bibliothèques ASP.NET Core et HttpClient Instrumentation. Le package de distribution désactive par défaut la modification des chaînes de requête.

Pour modifier ce comportement, définissez une variable d’environnement sur true ou false.

  • Instrumentation ASP.NET Core : OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_DISABLE_URL_QUERY_REDACTION la modification de chaîne de requête est désactivée par défaut. Pour l’activer, affectez la valeur false à cette variable d’environnement.

  • Instrumentation HttpClient : OTEL_DOTNET_EXPERIMENTAL_HTTPCLIENT_DISABLE_URL_QUERY_REDACTION Le masquage des chaînes de requête est désactivé par défaut. Pour l’activer, affectez la valeur false à cette variable d’environnement.

Intervalle d’exportation des métriques

Vous pouvez configurer l’intervalle d’exportation de métrique à l’aide de la variable d’environnement OTEL_METRIC_EXPORT_INTERVAL .

OTEL_METRIC_EXPORT_INTERVAL=60000

La valeur par défaut est 60000 millisecondes (60 secondes). Ce paramètre contrôle la fréquence à laquelle le Kit de développement logiciel (SDK) OpenTelemetry exporte les métriques.

Conseil

Azure Monitor Metrics et Azure Monitor Workspace ingèrent des métriques personnalisées à un intervalle fixe de 60 secondes. Les métriques envoyées plus fréquemment sont mises en mémoire tampon et traitées une fois toutes les 60 secondes. Log Analytics enregistre les métriques à l’intervalle qu’elles sont envoyées, ce qui peut augmenter les coûts à des intervalles plus courts et retarder la visibilité à plus longs.

Pour référence, consultez les spécifications OpenTelemetry suivantes :

Résolution des problèmes, commentaires et support

Conseil

Les sections suivantes sont disponibles dans tous les articles de distribution OpenTelemetry.

Résolution des problèmes

Commentaires sur OpenTelemetry

Pour fournir des commentaires :

Support

Sélectionnez un onglet correspondant à la langue de votre choix pour découvrir les options de support.

Étapes suivantes

  • Last updated on