Activer OpenTelemetry pour les applications .NET, Node.js, Python et Java

Remarque

Pour les applications .NET, Node.jset Python :

• Nouvelle application ou adoption d’OpenTelemetry pour la première fois : Utilisez Microsoft OpenTelemetry Distro.
• Vous utilisez déjà Azure Monitor OpenTelemetry Distro : aucune action n’est nécessaire.
• À l’aide d’Application Insights .NET SDK 2.x :Mettez à niveau vers la version 3.x pour réduire la réinstrumentation, ou repartir de zéro avec le Microsoft OpenTelemetry Distro.

Pour les applications Java, utilisez la Azure Monitor OpenTelemetry Distro.

Pour obtenir des conseils sur l’instrumentation assistée par l’IA, consultez la compétence Instrumentation Application Insights. Pour obtenir une configuration guidée et une analyse de l’instrumentation Application Insights existante, consultez les outils Azure MCP Server pour Azure Monitor.

Ce guide explique comment ajouter l’observabilité à votre application avec Microsoft OpenTelemetry Distro. La distribution collecte automatiquement les traces, les métriques et les journaux avec des instrumentations intégrées et exporte les données de télémétrie vers Azure Monitor, tout point de terminaison OTLP (OpenTelemetry Protocol) ou Microsoft Agent 365.

Pour obtenir d’autres options de collecte et d’exportation, consultez OpenTelemetry avec Azure Monitor.

Statut de publication d’OpenTelemetry

Pour les détails du package et les notes de publication, consultez Prochaines étapes.

Remarque

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

Activer OpenTelemetry avec Application Insights

Suivez les étapes de cette section pour instrumenter votre application avec OpenTelemetry. Sélectionnez un onglet pour obtenir des instructions spécifiques à la langue.

Les identificateurs du package OpenTelemetry Distro de Microsoft et les commandes d’installation sont les suivantes :

Language	Package	Commande d'installation
Python	microsoft-opentelemetry	pip install microsoft-opentelemetry
Node.js	@microsoft/opentelemetry	npm install @microsoft/opentelemetry
.NET	Microsoft.OpenTelemetry	dotnet add package Microsoft.OpenTelemetry

Pour Java, utilisez l’intégration de l’agent ou de l’image native décrite dans les onglets Java et Java native.

Utilisez l’onglet ASP.NET Core pour les applications web et l’onglet .NET pour la console et d’autres applications non hébergées.

Prérequis

• abonnement Azure : Créer un abonnement Azure gratuitement
• Ressource Application Insights : Créer une ressource Application Insights

ASP.NET Core

• application ASP.NET Core à l’aide d’une version officiellement prise en charge de .NET

Conseil

Si vous effectuez une mise à niveau à partir d'Application Insights .NET SDK 2.x, suivez les instructions de migration du SDK 3.x. Cette mise à niveau ne nécessite pas de basculer vers la distribution OpenTelemetry Microsoft.

.NET

• Application utilisant une version prise en charge de .NET. Pour les autres frameworks cibles, vérifiez la compatibilité du package Microsoft.OpenTelemetry.

Conseil

Si vous effectuez une mise à niveau à partir d'Application Insights .NET SDK 2.x, suivez les instructions de migration du SDK 3.x. Cette mise à niveau ne nécessite pas de basculer vers Microsoft OpenTelemetry Distro.

Java

• Application Java à l’aide de Java 8+

Java natif

• Application Java à l’aide de GraalVM 17+

Node.js

• Application utilisant Node.js 22 ou version ultérieure. Pour connaître les exigences de démarrage, consultez la documentation de Microsoft OpenTelemetry Distro for Node.js.

Conseil

Si vous effectuez une migration à partir d’un SDK Application Insights plus ancien, consultez le guide de migration Node.js pour choisir entre une mise à niveau du SDK et une nouvelle installation de la distribution.

Python

• application Python à l’aide de Python 3.10+

Conseil

Si vous effectuez une migration à partir d'OpenCensus, passez en revue les instructions de migration, puis utilisez le package de distribution OpenTelemetry Microsoft et le code d'initialisation dans cet article.

Installer la bibliothèque de client

ASP.NET Core

Remarque

Ces étapes d’installation concernent les applications qui utilisent la distribution OpenTelemetry Microsoft. Ils ne constituent pas une exigence de mise à niveau pour les utilisateurs existants d’Azure Monitor OpenTelemetry Distro. N’initialisez pas les deux distros dans la même application. Les packages d’exportation Azure Monitor autonomes conservent leurs noms existants.

Installez le package NuGet Microsoft.OpenTelemetry :

dotnet add package Microsoft.OpenTelemetry

.NET

Remarque

Ces étapes d’installation concernent les applications qui utilisent la distribution OpenTelemetry Microsoft. Ils ne constituent pas une exigence de mise à niveau pour les utilisateurs existants d’Azure Monitor OpenTelemetry Distro. N’initialisez pas les deux distros dans la même application. Les packages d’exportation Azure Monitor autonomes conservent leurs noms existants.

Installez le package NuGet Microsoft.OpenTelemetry :

dotnet add package Microsoft.OpenTelemetry

Java

Téléchargez le dernier fichier applicationinsights-agent-3.7.9.jar .

Avertissement

Si vous effectuez une mise à niveau à partir d’une version 3.x antérieure, vous pouvez être affecté par la modification des valeurs par défaut ou de légères différences dans les données que nous collectons. Pour plus d’informations, consultez la section migration dans les notes de publication. 3.5.0, 3.4.0, 3.3.0, 3.2.0 et 3.1.0

Java natif

Pour les applications natives Spring Boot :

• Importez la nomenclature d’OpenTelemetry.
• Ajoutez la dépendance Spring Cloud Azure Starter Monitor.
• Suivez ces instructions pour les fichiers JAR (Java Archive) Kit de développement logiciel (SDK) Azure.

Pour les applications natives de Quarkus :

• Ajoutez la dépendance Quarkus OpenTelemetry Exporter for Azure.

Remarque

La communauté de Quarkus soutient et gère les extensions de Dockerus. Pour obtenir de l’aide, utilisez les canaux de support de la communauté Quarkus. Microsoft ne fournit pas de support technique pour cette intégration.

Node.js

Remarque

Ces étapes d’installation concernent les applications qui utilisent la distribution OpenTelemetry Microsoft. Ils ne constituent pas une exigence de mise à niveau pour les utilisateurs existants d’Azure Monitor OpenTelemetry Distro. N’initialisez pas les deux distros dans la même application. Les packages d’exportation Azure Monitor autonomes conservent leurs noms existants.

Installez le package npm @microsoft/opentelemetry :

npm install @microsoft/opentelemetry

Python

Remarque

Ces étapes d’installation concernent les applications qui utilisent la distribution OpenTelemetry Microsoft. Ils ne sont pas une exigence de mise à niveau pour les utilisateurs existants de la distribution OpenTelemetry Azure Monitor. N’initialisez pas les deux distros dans la même application. Les packages d’exportation Azure Monitor autonomes conservent leurs noms existants.

Installez le package PyPI microsoft-opentelemetry :

pip install microsoft-opentelemetry

Modifier votre application

Initialisez Microsoft OpenTelemetry Distro avant que votre application commence à gérer le travail. Les exemples suivants sélectionnent Azure Monitor comme destination et lisent le chaîne de connexion à partir de la variable d’environnementAPPLICATIONINSIGHTS_CONNECTION_STRING. Définissez cette variable avant de démarrer votre application, comme décrit plus loin dans cet article.

Vous pouvez également définir la chaîne de connexion dans le code. Pour .NET, utilisez options.AzureMonitor.ConnectionString à l’intérieur de UseMicrosoftOpenTelemetry(). Pour toutes les langues prises en charge, consultez la configuration de la chaîne de connexion.

ASP.NET Core

Dans Program.cs, configurez le générateur d’applications pour utiliser la distribution OpenTelemetry Microsoft :

// Import the distro API.
using Microsoft.OpenTelemetry;

// Create the application builder.
var builder = WebApplication.CreateBuilder(args);

// Initialize the Microsoft OpenTelemetry Distro with Azure Monitor export.
builder.UseMicrosoftOpenTelemetry(options =>
{
    options.Exporters = ExportTarget.AzureMonitor;
});

// Build and run the application.
var app = builder.Build();
app.Run();

.NET

Pour la console et d’autres applications non hébergées, créez une instance du Kit de développement logiciel (SDK) OpenTelemetry avant le code de votre application :

// Import the distro and SDK APIs.
using Microsoft.OpenTelemetry;
using OpenTelemetry;

// Create the Microsoft OpenTelemetry Distro and keep the SDK alive until shutdown.
using var sdk = OpenTelemetrySdk.Create(telemetry =>
{
    // Select Azure Monitor as the export destination.
    telemetry.UseMicrosoftOpenTelemetry(options =>
    {
        options.Exporters = ExportTarget.AzureMonitor;
    });
});

Gardez sdk actif pendant toute la durée de vie de votre application. Libérez-le uniquement lors de l’arrêt pour vider les données de télémétrie en attente et arrêter les providers.

Java

L’instrumentation automatique est activée par le biais de modifications de configuration. Aucune modification du code n’est requise.

Pointez le Java machine virtuelle (JVM) vers le fichier jar en ajoutant -javaagent:"path/to/applicationinsights-agent-3.7.9.jar" aux arguments JVM de votre application.

Remarque

L’échantillonnage est activé par défaut à un taux de cinq demandes par seconde, ce qui aide à la gestion des coûts. Les données de télémétrie peuvent être manquantes dans les scénarios dépassant ce taux. Pour plus d’informations sur la modification de la configuration d’échantillonnage, consultez paramètres de substitution pour l’échantillonnage. Si vous voyez des frais inattendus ou des coûts élevés dans Application Insights, ce guide peut vous aider. Il couvre les causes courantes telles que le volume de télémétrie élevé, les pics d’ingestion de données et l’échantillonnage mal configuré. Il est particulièrement utile si vous résolvez des problèmes liés aux pics de coûts, au volume de télémétrie, à l’échantillonnage qui ne fonctionne pas, aux limites de données, à l’ingestion élevée ou à la facturation inattendue. Pour commencer, consultez Résoudre les problèmes d’ingestion de données élevées dans Application Insights.

Conseil

Pour obtenir des conseils spécifiques au scénario, consultez Prise en main (supplément).

Conseil

Si vous développez une application Spring Boot, vous pouvez éventuellement remplacer l’argument JVM par une configuration programmatique. Pour plus d’informations, consultez Utilisation Azure Monitor Application Insights avec Spring Boot.

Java natif

L’instrumentation automatique est activée par le biais de modifications de configuration. Aucune modification du code n’est requise.

Node.js

Pour les applications CommonJS, initialisez Microsoft OpenTelemetry Distro avant de charger les bibliothèques que vous souhaitez instrumenter :

// Import the distro API.
const { useMicrosoftOpenTelemetry } = require("@microsoft/opentelemetry");

// Initialize the distro before loading application libraries.
useMicrosoftOpenTelemetry({
    azureMonitor: {
        azureMonitorExporterOptions: {
            // Read the Azure Monitor connection string from the environment.
            connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
        },
    },
});

Pour les modules ECMAScript (ESM), créez un telemetry.mjs fichier de démarrage :

// Register instrumentation hooks before loading application modules.
import "@microsoft/opentelemetry/loader";
import { useMicrosoftOpenTelemetry } from "@microsoft/opentelemetry";

// Initialize the Microsoft OpenTelemetry Distro with Azure Monitor export.
useMicrosoftOpenTelemetry({
    azureMonitor: {
        azureMonitorExporterOptions: {
            // Read the connection string from the environment.
            connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
        },
    },
});

Préchargez le fichier de démarrage afin que les hooks d’instrumentation s’inscrivent avant le chargement des modules de votre application :

node --import ./telemetry.mjs "<AppEntryPoint>"

Python

Utilisez Microsoft OpenTelemetry Distro pour activer l’exportation vers Azure Monitor et sélectionner un journaliseur d’application nommé. En utilisant un logger nommé, vous évitez de collecter les propres messages de journal du Kit de développement logiciel (SDK) :

# Import the logging and distro APIs.
import logging
from microsoft.opentelemetry import use_microsoft_opentelemetry

# Select an application logger to avoid collecting the SDK's own logs.
loggerName = "<LoggerName>"

# Enable Azure Monitor export using the connection string environment variable.
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    logger_name=loggerName,
)

# Collect application log records at INFO level and above.
logger = logging.getLogger(loggerName)
logger.setLevel(logging.INFO)

Copier le chaîne de connexion à partir de votre ressource Application Insights

Le chaîne de connexion identifie la ressource Application Insights qui reçoit vos données de télémétrie.

Conseil

Si vous n’avez pas encore de ressource Application Insights, créez-en un suivant ce guide. Nous vous recommandons de créer une ressource plutôt que d’utiliser une ressource existante.

Pour copier le chaîne de connexion :

1. Accédez au volet Vue d’ensemble de votre ressource Application Insights.
2. Recherchez votre chaîne de connexion.
3. Pointez sur la chaîne de connexion et sélectionnez l’icône Copier dans le Presse-papiers.

Collez la chaîne de connexion dans votre environnement

Pour coller votre chaîne de connexion, utilisez l’une des méthodes suivantes :

Méthode	Langues prises en charge	Recommandé pour
Variable d’environnement	Tous	Production
Fichier de configuration (applicationinsights.json)	Java uniquement	Production (Java)
Code	.NET, Node.js, Python	Développement/test local uniquement

Important

Nous vous recommandons de définir le chaîne de connexion via du code uniquement dans les environnements de développement et de test locaux.

Pour la production, utilisez une variable d’environnement ou un fichier de configuration (Java uniquement).

• Définissez la chaîne de connexion Application Insights comme variable d’environnement (recommandé pour la production)

  Dans Bash :

  export APPLICATIONINSIGHTS_CONNECTION_STRING="<ConnectionString>"
  

  Dans PowerShell :

  $env:APPLICATIONINSIGHTS_CONNECTION_STRING = "<ConnectionString>"
  

• Set l’chaîne de connexion Application Insights dans un fichier de configuration - Java uniquement

  Créez un fichier de configuration nommé applicationinsights.json, puis placez-le dans le même répertoire que applicationinsights-agent-3.7.9.jar, avec le contenu suivant :

      {
          "connectionString": "<ConnectionString>"
      }
  

• Définissez la chaîne de connexion Application Insights dans le code - .NET, Node.js et Python uniquement

  Pour les options de Microsoft OpenTelemetry Distro, consultez la documentation .NET, Node.js ou Python.

Confirmer que les données circulent

Après avoir configuré la distro et défini la chaîne de connexion, exécutez votre application et générez du trafic ou des messages de journalisation. Ouvrez votre ressource Application Insights dans le portail Azure pour vérifier que les données de télémétrie s’affichent. L’affichage des données peut prendre quelques minutes.

Application Insights est maintenant activé pour votre application. Les étapes suivantes sont facultatives et permettent une personnalisation supplémentaire.

Remarque

Dans le cadre de l’utilisation de l’instrumentation Application Insights, nous collectons et envoyons des données de diagnostic à Microsoft. Ces données nous permettent d’exécuter et d’améliorer Application Insights. Pour plus d’informations, consultez le FAQ Application Insights.

Important

Si vous avez deux services ou plus qui émettent des données de télémétrie vers la même ressource Application Insights, vous devez définir les noms de rôles cloud pour les représenter correctement sur la carte d’application.

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

ASP.NET Core

Pour des informations de dépannage sur les problèmes, consultez Résoudre les problèmes d'OpenTelemetry dans .NET et Résoudre les problèmes de télémétrie manquante dans Azure Monitor Application Insights.

.NET

Pour des informations de dépannage sur les problèmes, consultez Résoudre les problèmes d'OpenTelemetry dans .NET et Résoudre les problèmes de télémétrie manquante dans Azure Monitor Application Insights.

Java

Pour plus d'informations sur la résolution des problèmes, consultez Résoudre les problèmes OpenTelemetry en Java et Résoudre l'absence de télémétrie des applications dans Azure Monitor Application Insights.

Java natif

Pour obtenir des informations sur la résolution des problèmes, consultez Résoudre les problèmes OpenTelemetry dans les applications d'images natives Spring Boot et Résoudre la télémétrie d'application manquante dans Azure Monitor Application Insights.

Node.js

Pour des informations de dépannage, consultez Dépanner les problèmes OpenTelemetry dans Node.js et Dépanner les télémétries manquantes d'application dans Azure Monitor Application Insights.

Python

Pour plus d’informations sur la résolution des problèmes, consultez Résoudre les problèmes d'OpenTelemetry en Python et Résoudre les problèmes de télémétrie d'application manquante dans Azure Monitor Application Insights.

Commentaires sur OpenTelemetry

Pour fournir des commentaires :

• Remplissez l’enquête sur les commentaires des clients de la communauté OpenTelemetry.
• Parlez de vous à Microsoft en vous joignant à la OpenTelemetry Early Adopter Community.
• Collaborez avec d’autres utilisateurs Azure Monitor dans la communauté tech Microsoft.
• Effectuez une demande de fonctionnalité au Azure Forum de commentaires.

Support

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

ASP.NET Core

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour les problèmes d’OpenTelemetry, contactez la communauté OpenTelemetry .NET communauté directement.
• Pour obtenir la liste des problèmes ouverts liés à Azure Monitor Exporter, consultez la page GitHub Problèmes.

.NET

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour les problèmes d’OpenTelemetry, contactez la communauté OpenTelemetry .NET communauté directement.
• Pour obtenir la liste des problèmes ouverts liés à Azure Monitor Exporter, consultez la page GitHub Problèmes.

Java

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour obtenir de l’aide pour la résolution des problèmes, consultez les étapes de résolution des problèmes.
• Pour les problèmes OpenTelemetry, contactez directement la communauté OpenTelemetry.
• Pour obtenir la liste des problèmes ouverts liés à Azure Monitor Java d'autoinstrumentation, consultez la page GitHub Issues.

Java natif

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour les problèmes OpenTelemetry, contactez directement la communauté OpenTelemetry.
• Pour obtenir la liste des problèmes ouverts liés aux applications natives Spring Boot, consultez la page GitHub Problèmes.
• Pour obtenir la liste des problèmes ouverts liés aux applications natives Quarkus, consultez la page des problèmes GitHub.

Remarque

La communauté de Quarkus soutient et gère les extensions de Dockerus. Pour obtenir de l’aide, utilisez les canaux de support de la communauté Quarkus. Microsoft ne fournit pas de support technique pour cette intégration.

Node.js

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour les problèmes OpenTelemetry, contactez directement la communauté OpenTelemetry JavaScript.
• Pour obtenir la liste des problèmes ouverts liés à Azure Monitor Exporter, consultez la page GitHub Problèmes.

Python

• Pour les problèmes de support Azure, ouvrez un ticket de support Azure.
• Pour les problèmes d’OpenTelemetry, contactez la OpenTelemetry Python communauté directement.
• Pour obtenir la liste des problèmes ouverts liés à la distribution OpenTelemetry Microsoft pour Python, consultez les problèmes de GitHub.

Étapes suivantes

ASP.NET Core

• Pour passer en revue le code source, consultez le Microsoft OpenTelemetry Distro repository for .NET.
• Pour passer en revue un exemple d’application, consultez Microsoft OpenTelemetry Distro for ASP.NET Core.
• Pour installer le package NuGet, rechercher les mises à jour ou afficher les notes de publication, consultez le Microsoft.OpenTelemetry package.
• Pour les applications qui utilisent toujours Azure.Monitor.OpenTelemetry.AspNetCore, consultez la documentation de la distribution Azure Monitor.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le dépôt OpenTelemetry .NET GitHub.
• Pour activer les expériences d’utilisation, activez la surveillance des utilisateurs du web ou du navigateur.

.NET

• Pour passer en revue le code source, consultez le référentiel Microsoft OpenTelemetry Distro pour .NET.
• Pour la configuration non hébergée, consultez Configurer le Microsoft OpenTelemetry Distro pour les applications console et les outils en arrière-plan.
• Pour installer le package NuGet, recherchez les mises à jour ou affichez les notes de publication, consultez le package Microsoft.OpenTelemetry.
• Pour les applications qui utilisent le package autonomeAzure.Monitor.OpenTelemetry.Exporter, consultez la documentation Azure Monitor exporter.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le dépôt OpenTelemetry .NET GitHub.
• Pour activer les expériences d’utilisation, activez la surveillance des utilisateurs du web ou du navigateur.

Java

• Pour passer en revue les options de configuration, consultez options de configuration d'autoinstrumentation Java.
• Pour passer en revue le code source, consultez le dépôt GitHub Azure Monitor Java autoinstrumentation.
• Pour passer en revue les exemples d’applications, consultez Application Insights Java Samples.
• Passez en revue les notes de version sur GitHub.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le référentiel OpenTelemetry Java GitHub.
• Pour permettre les expériences d'utilisation, consultez Activer l'analyse des utilisateurs du Web ou du navigateur.

Java natif

• Pour passer en revue le code source, consultez Azure Monitor OpenTelemetry Distro in Spring Boot native image Java application et Quarkus OpenTelemetry Exporter for Azure.
• Pour consulter un exemple d’application, consultez Télémétrie pour les images natives GraalVM.
• Passez en revue les notes de version sur GitHub.
• En savoir plus sur les fonctionnalités des applications d’image native Spring Boot dans OpenTelemetry SpringBoot starter
• Apprenez-en davantage sur les fonctionnalités des applications natives dans Quarkus OpenTelemetry Exporter pour Azure.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le référentiel OpenTelemetry Java GitHub.

Node.js

• Pour passer en revue le code source, consultez le Microsoft OpenTelemetry Distro repository for Node.js.
• Pour passer en revue les exemples d’applications, consultez Microsoft OpenTelemetry Distro samples for Node.js.
• Pour installer le package npm et rechercher les mises à jour, consultez le package @microsoft/opentelemetry.
• Pour les applications qui utilisent encore @azure/monitor-opentelemetry, consultez la documentation de la distribution Azure Monitor.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le référentiel OpenTelemetry JavaScript GitHub.
• Pour activer les expériences d’utilisation, activez la surveillance des utilisateurs du web ou du navigateur.

Python

• Pour passer en revue le code source et la configuration, consultez le Microsoft OpenTelemetry Distro repository for Python.
• Pour passer en revue les exemples d’applications, consultez Microsoft OpenTelemetry Distro samples for Python.
• Pour installer le package PyPI et rechercher les mises à jour, consultez le package microsoft-opentelemetry.
• Passez en revue les notes de version sur GitHub.
• Pour les applications qui utilisent toujours azure-monitor-opentelemetry, consultez la documentation de la distro Azure Monitor.
• Pour consulter les composants et instrumentations OpenTelemetry disponibles, consultez le référentiel OpenTelemetry Contributor Python GitHub.
• Pour en savoir plus sur OpenTelemetry et sa communauté, consultez le dépôt OpenTelemetry Python GitHub.
• Pour activer les expériences d’utilisation, activez la surveillance des utilisateurs du web ou du navigateur.