Configurer OpenTelemetry pour Azure Monitor

  • Article

Cet article décrit les paramètres de configuration de la distribution Azure Monitor OpenTelemetry.

Connection string

Une chaîne de connexion dans Application Insights 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 emplacements, nous respectons la précédence suivante :

  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 ressource et fournit des valeurs par défaut pour les propriétés Nom de rôle cloud et Instance de rôle cloud 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 Ressource. Le nom du rôle cloud utilise les attributs service.namespace et service.name, mais il retourne à la valeur 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(_testResourceAttributes));

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

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

Activer l’échantillonnage

Vous pouvez activer l’échantillonnage pour réduire votre volume d’ingestion de données, ce qui réduit vos coûts. Azure Monitor fournit un échantillonneur à taux fixe personnalisé qui remplit les événements avec un « ratio d’échantillonnage » qu’Application Insights convertit en ItemCount. L’échantillonneur à taux fixe garantit des expériences et des comptes d’événements précis. L’échantillonneur est conçu pour préserver vos traces entre les services, et il est interopérable avec les anciens Kits de développement logiciel (SDK) d’Application Insights. Pour plus d’informations, consultez En savoir plus sur l’échantillonnage.

Notes

Les métriques et journaux ne sont pas affectés par l’échantillonnage.

L’échantillonneur s’attend à un taux d’échantillonnage compris entre 0 et 1 inclus. Un taux de 0,1 signifie qu’environ 10 % de vos traces sont envoyées.

// 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 sampling ratio to 10%. This means that 10% of all traces will be sampled and sent to Azure Monitor.
    options.SamplingRatio = 0.1F;
});

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

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

Conseil

Lorsque vous utilisez un échantillonnage à taux/pourcentage fixe et que vous ne savez pas quelle valeur donner au taux d’échantillonnage, commencez à 5 % (c’est-à-dire 0,05 du taux d’échantillonnage) et ajustez le taux en fonction de la justesse des opérations affichées dans les panneaux d’échecs et de performances. Un taux plus élevé entraîne généralement une plus grande précision. Toutefois, l’échantillonnage ANY affecte la précision. Nous vous recommandons donc de générer des alertes sur les métriques OpenTelemetry, lesquelles ne sont pas affectées par l’échantillonnage.

Métriques temps réel

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

Pour connaître les conditions juridiques qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou plus généralement non encore en disponibilité générale, consultez l’Avenant aux conditions d’utilisation des préversions de Microsoft Azure.

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)

Vous pouvez activer l’authentification Microsoft Entra pour une connexion plus sécurisée à Azure, ce qui empêche l’ingestion de données de télémétrie non autorisées dans votre abonnement.

Nous prenons en charge les classes d’informations d’identification fournies par Identité Azure.

  • Nous vous recommandons DefaultAzureCredential pour le développement local.
  • Nous vous recommandons ManagedIdentityCredential pour les identités managées attribuées par le système et par l'utilisateur.
    • Pour l’affectation par le système, utilisez le constructeur par défaut sans paramètres.
    • Pour la valeur assignée à l’utilisateur, fournissez l’ID client au constructeur.
  • Nous vous recommandons ClientSecretCredential pour les principaux de service.
    • Indiquez l’ID de locataire, l’ID client et la clé secrète client au constructeur.

  1. Installez le dernier package Azure.Identity :

    dotnet add package Azure.Identity

  2. Fournissez la classe d’informations d’identification souhaitée :

    // 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 credential to the DefaultAzureCredential.
    // This credential will use the Azure identity of the current user or
    // the service principal that the application is running as to authenticate
    // to Azure Monitor.
    options.Credential = new DefaultAzureCredential();
});

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

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

Stockage hors connexion et nouvelles tentatives automatiques

Pour améliorer la fiabilité et la résilience, les offres Azure Monitor basées sur OpenTelemetry écrivent dans un stockage hors connexion/local par défaut lorsqu’une application perd sa connexion avec Application Insights. Il enregistre la télémétrie de l’application pendant 48 heures et tente régulièrement de l’envoyer à nouveau. Dans les applications à charge élevée, la télémétrie est parfois supprimée pour deux raisons. Tout d’abord, lorsque la durée autorisée est dépassée, et ensuite, lorsque la taille maximale du fichier est dépassée ou que le kit de développement logiciel (SDK) n’a pas la possibilité d’effacer le fichier. Si nous devons choisir, le produit enregistre les événements les plus récents sur les anciens. En savoir plus

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
  • Non-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 cannot 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é, vous devez définir AzureMonitorOptions.DisableOfflineStorage = true.

Activer l’exportateur OTLP

Vous pouvez activer OpenTelemetry Protocol (OTLP) Exporter en plus du Azure Monitor Exporter pour envoyer vos données de télémétrie à deux emplacements.

Notes

OTLP Exporter est illustré pour des raisons pratiques uniquement. Nous ne prenons pas officiellement en charge OTLP Exporter ni les composants ou les expériences tierces qui en découlent.

  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 l' exemple relatif à 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

Les configurations OpenTelemetry suivantes sont accessibles via des variables d’environnement lors de l’utilisation des distributions Azure Monitor OpenTelemetry.

Variable d’environnement Description
APPLICATIONINSIGHTS_CONNECTION_STRING Copiez-le dans la chaîne de connexion à partir de votre ressource Application Insights.
APPLICATIONINSIGHTS_STATSBEAT_DISABLED Définissez-le sur true pour refuser la collecte de métriques interne.
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 SDK de ressources.
OTEL_SERVICE_NAME Définit la valeur de l’attribut de ressource service.name. Si la valeur service.name est également fournie dans OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME est alors prioritaire.

Masquer les chaînes de requête d’URL

Pour masquer les chaînes de requête d’URL, désactivez la collecte de chaînes de requête. Nous vous recommandons d’utiliser ce paramètre si vous appelez le service Stockage Azure à l’aide d’un jeton SAS.

Quand vous utilisez le package de distribution Azure.Monitor.OpenTelemetry.AspNetCore, les bibliothèques d’instrumentation ASP.NET Core et HttpClient sont incluses. Notre package de distribution désactive le masquage des chaînes de requête par défaut.

Pour changer ce comportement, vous devez affecter la valeur « true » ou « false » à une variable d’environnement.

  • Instrumentation ASP.NET Core : OTEL_DOTNET_EXPERIMENTAL_ASPNETCORE_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.
  • 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.