Partager via

Utiliser OpenTelemetry avec Azure Functions

Cet article explique comment configurer votre application de fonction pour exporter les données de journal et de trace dans un format OpenTelemetry. Azure Functions génère des données de télémétrie sur vos exécutions de fonction à partir du processus hôte Functions et du processus Worker propre au langage dans lequel votre code de fonction s’exécute. Par défaut, ces données de télémétrie sont envoyées à Application Insights à l’aide du Kit de développement logiciel (SDK) Application Insights. Toutefois, vous pouvez choisir d’exporter ces données à l’aide de la sémantique OpenTelemetry. Bien que vous puissiez toujours utiliser un format OpenTelemetry pour envoyer vos données à Application Insights, vous pouvez désormais exporter les mêmes données vers tout autre point de terminaison conforme à OpenTelemetry.

Vous pouvez obtenir ces avantages en activant OpenTelemetry dans votre application de fonction :

  • Met en corrélation les données entre les traces et les journaux générées à la fois sur l’hôte et dans le code de votre application.
  • Permet une génération cohérente basée sur des normes de données de télémétrie exportables.
  • Intégration à d’autres fournisseurs qui peuvent consommer des données conformes à OpenTelemetry.

Gardez à l’esprit ces considérations lors de l’utilisation de cet article :

  • Essayez le didacticiel OpenTelemetry, qui est conçu pour vous aider à commencer rapidement avec OpenTelemetry et Azure Functions. Cet article utilise Azure Developer CLI (azd) pour créer et déployer une application de fonction qui utilise l’intégration d’OpenTelemetry pour le suivi distribué.

  • N’oubliez pas de choisir le langage de votre choix en haut de l’article, afin que cet article cible le langage de développement approprié.

  • OpenTelemetry est activé au niveau de l’application de fonction, à la fois dans la configuration de l’hôte (host.json) et dans votre projet de code. Functions fournit également une expérience cliente optimisée pour l’exportation des données OpenTelemetry à partir de votre code de fonction qui s’exécute dans un processus Worker propre au langage.

Activer OpenTelemetry dans l’hôte Functions

Lorsque vous activez la sortie OpenTelemetry dans le fichier host.json de l’application de fonction, votre hôte exporte la sortie OpenTelemetry, quelle que soit la pile de langage utilisée par votre application.

Pour activer la sortie OpenTelemetry à partir de l’hôte Functions, mettez à jour le fichier host.json dans votre projet de code de façon à ajouter un élément "telemetryMode": "OpenTelemetry" à la collection racine. Avec OpenTelemetry activé, votre fichier host.json peut ressembler à ceci :

{
    "version": "2.0",
    "telemetryMode": "OpenTelemetry",
    ...
}

Configurer les paramètres de l’application

Lorsque vous activez OpenTelemetry dans le host.json fichier, les variables d’environnement de l’application déterminent les points de terminaison pour l’envoi de données en fonction des paramètres d’application pris en charge par OpenTelemetry.

Créez des paramètres d’application spécifiques dans votre application de fonction en fonction de la destination de sortie OpenTelemetry. Lorsque vous fournissez des paramètres de connexion pour Application Insights et un exportateur OTLP (OpenTelemetry Protocol), les données OpenTelemetry sont envoyées aux deux points de terminaison.

APPLICATIONINSIGHTS_CONNECTION_STRING : chaîne de connexion pour un espace de travail Application Insights. Lorsque ce paramètre existe, les données OpenTelemetry sont envoyées à cet espace de travail. Utilisez le même paramètre pour vous connecter à Application Insights sans OpenTelemetry activé. Si votre application n’a pas encore ce paramètre, vous devrez peut-être activer l’intégration d’Application Insights.

JAVA_APPLICATIONINSIGHTS_ENABLE_TELEMETRY : définissez sur true pour que l’hôte Functions autorise le processus de travail Java à diffuser en continu les journaux OpenTelemetry directement, ce qui empêche les entrées au niveau de l’hôte en double.

PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY : définissez sur true pour que l’hôte Functions autorise le processus de travail Python à diffuser en continu les journaux OpenTelemetry directement, ce qui empêche les entrées au niveau de l’hôte en double.

Activer OpenTelemetry dans votre application

Après avoir configuré l’hôte Functions pour utiliser OpenTelemetry, mettez à jour le code de votre application pour générer des données OpenTelemetry. Lorsque vous activez OpenTelemetry dans l’hôte et le code de votre application, vous obtenez une meilleure corrélation entre les traces et les journaux qu’émettent le processus hôte Functions et le processus Worker de langage.

La façon dont vous instrumentez votre application pour utiliser OpenTelemetry dépend de votre point de terminaison OpenTelemetry cible :

Les exemples de cet article supposent que votre application utilise IHostApplicationBuilder, qui est disponible dans la version 2.x et ultérieure de Microsoft.Azure.Functions.Worker. Pour plus d’informations, consultez Version 2.x dans le guide du modèle worker isolé C#.

  1. Exécutez ces commandes pour installer les assemblys requis dans votre application :

    dotnet add package Microsoft.Azure.Functions.Worker.OpenTelemetry
dotnet add package OpenTelemetry.Extensions.Hosting 
dotnet add package Azure.Monitor.OpenTelemetry.Exporter

  2. Dans votre fichier projet Program.cs, ajoutez cette instruction using :

    using Azure.Monitor.OpenTelemetry.Exporter;

  3. Configurez OpenTelemetry selon que le démarrage de votre projet utilise IHostBuilder ou IHostApplicationBuilder. Ce dernier a été introduit dans la version 2.x de l’extension de modèle Worker isolé .NET.

    Dans program.cs, ajoutez cette ligne de code après ConfigureFunctionsWebApplication :

    builder.Services.AddOpenTelemetry()
    .UseFunctionsWorkerDefaults()
    .UseAzureMonitorExporter();

    Vous pouvez exporter vers les deux points de terminaison OpenTelemetry à partir de la même application.

  1. Ajoutez les bibliothèques requises à votre application. La façon dont vous ajoutez des bibliothèques varie selon que vous déployez à l’aide de Maven ou de Kotlin et que vous souhaitez également envoyer des données à Application Insights.

    <dependency>
  <groupId>com.microsoft.azure.functions</groupId>
  <artifactId>azure-functions-java-opentelemetry</artifactId>
  <version>1.0.0</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
  <version>1.2.0</version>
</dependency>

  2. (Facultatif) Ajoutez ce code pour créer des étendues personnalisées :

    import com.microsoft.azure.functions.opentelemetry.FunctionsOpenTelemetry;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.context.Scope;

Span span = FunctionsOpenTelemetry.startSpan(
        "com.contoso.PaymentFunction",  // tracer name
        "validateCharge",               // span name
        null,                           // parent = current context
        SpanKind.INTERNAL);

try (Scope ignored = span.makeCurrent()) {
    // business logic here
} finally {
    span.end();
}

  1. Installez ces packages npm dans votre projet :

    npm install @opentelemetry/api 
npm install @opentelemetry/auto-instrumentations-node 
npm install @azure/monitor-opentelemetry-exporter 
npm install @azure/functions-opentelemetry-instrumentation

  1. Créez un fichier de code dans votre projet, copiez et collez le code suivant dans ce nouveau fichier, puis enregistrez le fichier sous src/index.js :

    const { AzureFunctionsInstrumentation } = require('@azure/functions-opentelemetry-instrumentation');
const { AzureMonitorLogExporter, AzureMonitorTraceExporter } = require('@azure/monitor-opentelemetry-exporter');
const { getNodeAutoInstrumentations, getResourceDetectors } = require('@opentelemetry/auto-instrumentations-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { detectResourcesSync } = require('@opentelemetry/resources');
const { LoggerProvider, SimpleLogRecordProcessor } = require('@opentelemetry/sdk-logs');
const { NodeTracerProvider, SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-node');

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Mettez à jour le main champ dans votre fichier package.json pour inclure le nouveau src/index.js fichier. Par exemple:

    "main": "src/{index.js,functions/*.js}"

  1. Créez un fichier de code dans votre projet, copiez et collez le code suivant dans ce nouveau fichier, puis enregistrez le fichier sous src/index.ts :

    import { AzureFunctionsInstrumentation } from '@azure/functions-opentelemetry-instrumentation';
import { AzureMonitorLogExporter, AzureMonitorTraceExporter } from '@azure/monitor-opentelemetry-exporter';
import { getNodeAutoInstrumentations, getResourceDetectors } from '@opentelemetry/auto-instrumentations-node';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { detectResourcesSync } from '@opentelemetry/resources';
import { LoggerProvider, SimpleLogRecordProcessor } from '@opentelemetry/sdk-logs';
import { NodeTracerProvider, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';

const resource = detectResourcesSync({ detectors: getResourceDetectors() });

const tracerProvider = new NodeTracerProvider({ resource });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(new AzureMonitorTraceExporter()));
tracerProvider.register();

const loggerProvider = new LoggerProvider({ resource });
loggerProvider.addLogRecordProcessor(new SimpleLogRecordProcessor(new AzureMonitorLogExporter()));

registerInstrumentations({
    tracerProvider,
    loggerProvider,
    instrumentations: [getNodeAutoInstrumentations(), new AzureFunctionsInstrumentation()],
});

  2. Mettez à jour le champ main dans votre fichier package.json de façon à inclure la sortie de ce nouveau fichier src/index.ts, qui peut ressembler à ceci :

    "main": "dist/src/{index.js,functions/*.js}"

Important

La sortie OpenTelemetry vers Application Insights à partir du Worker de langage n’est actuellement pas prise en charge pour les applications PowerShell. À la place, vous souhaiterez peut-être utiliser un point de terminaison d’exportateur OTLP. Lorsque vous configurez votre hôte pour envoyer la sortie OpenTelemetry vers Application Insights, les journaux générés par le processus Worker PowerShell sont toujours transférés, mais le suivi distribué n’est pas pris en charge pour le moment.

Ces instructions s’appliquent uniquement à un exportateur OTLP :

  1. Ajoutez un paramètre d’application nommé OTEL_FUNCTIONS_WORKER_ENABLED avec la valeur True.

  2. Créez un dossier Modules au niveau de l’application à la racine de votre application, et exécutez la commande suivante :

    Save-Module -Name AzureFunctions.PowerShell.OpenTelemetry.SDK

    Cette commande installe le module requis AzureFunctions.PowerShell.OpenTelemetry.SDK directement dans votre application. Vous ne pouvez pas utiliser le fichier requirements.psd1 pour installer automatiquement cette dépendance, car les dépendances managées ne sont actuellement pas prises en charge dans la préversion du plan Consommation flexible.

  3. Ajoutez ce code à votre fichier profile.ps1 :

    Import-Module AzureFunctions.PowerShell.OpenTelemetry.SDK -Force -ErrorAction Stop 
Initialize-FunctionsOpenTelemetry

  1. Vérifiez que ces bibliothèques se trouvent dans votre fichier requirements.txt, qu’il s’agisse de décompresser ou d’ajouter vous-même :

    azure-monitor-opentelemetry

  2. Ajoutez ce code à votre fichier de point d’entrée principal function_app.py :

    Si vous avez déjà ajouté PYTHON_APPLICATIONINSIGHTS_ENABLE_TELEMETRY=true aux paramètres de votre application, vous pouvez ignorer cette étape. Pour activer manuellement la collection Application Insights sans instrumentation automatique, ajoutez ce code à votre application :

    from azure.monitor.opentelemetry import configure_azure_monitor 
configure_azure_monitor()

  3. Consultez la documentation sur l’utilisation de la distribution Azure Monitor pour obtenir des options sur la façon de configurer davantage le SDK.

Considérations relatives à OpenTelemetry

Lorsque vous exportez vos données à l’aide d’OpenTelemetry, gardez à l’esprit ces considérations.

  • Le portail Azure prend en charge les traces Recent function invocation uniquement si les données de télémétrie sont envoyées à Azure Monitor.

  • Lorsque vous configurez l’hôte pour utiliser OpenTelemetry, le portail Azure ne prend pas en charge la journalisation en continu.

  • Si vous définissez telemetryMode à OpenTelemetry, la section logging.applicationInsights dans host.json ne s’applique pas.

  • Les étendues personnalisées incluent automatiquement tous les attributs de ressource et utilisent les exportateurs configurés dans votre application.

  • Lorsque votre application s’exécute en dehors d’Azure, notamment pendant le développement local, le détecteur de ressources définit l’attribut service.namejava-function-app par défaut.

  • Utilisez ces indicateurs JVM (Java Virtual Machine) pour couper tous les événements de télémétrie lors de l’exécution locale pendant les tests unitaires :

    • -Dotel.traces.exporter=none
    • -Dotel.metrics.exporter=none
    • -Dotel.logs.exporter=none
  • Vous n’avez pas besoin d’inscrire manuellement le middleware ; le worker Java détecte automatiquement OpenTelemetryInvocationMiddleware.

Résolution des problèmes

Lorsque vous exportez vos données à l’aide d’OpenTelemetry, gardez à l’esprit ces problèmes courants et solutions.

Filtrage des journaux

Pour configurer correctement le filtrage des log dans votre application de Fonction, vous devez comprendre la différence entre le processus hôte et le processus de travail.

Le processus hôte est le runtime Azure Functions qui gère les déclencheurs, la mise à l’échelle et émet des données de télémétrie au niveau du système, telles que les journaux d’initialisation, les traces de requête et les informations d’intégrité du runtime.

Le processus de travail est spécifique au langage, exécute votre code de fonction et produit des journaux d’application et des données de télémétrie indépendamment.

Important

Les filtres définis dans host.json s’appliquent uniquement aux journaux générés par le processus hôte. Pour filtrer les journaux du processus Worker, vous devez utiliser des paramètres OpenTelemetry spécifiques à la langue.

Exemple : Filtrer les journaux d’activité de l’hôte pour tous les fournisseurs dans host.json

Utilisez cette approche pour définir un niveau de journal global sur tous les fournisseurs gérés par l’hôte :

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "logLevel": {
      "default": "Warning"
    }
  }
}

Exemple : Filtrez uniquement le fournisseur d’enregistreurs d’événements OpenTelemetry dans les journaux

Utilisez cette approche pour cibler uniquement le fournisseur d’enregistreurs d’événements OpenTelemetry tout en laissant d’autres fournisseurs (comme la console ou la journalisation de fichiers) non affectés :

{
  "version": "2.0",
  "telemetryMode": "OpenTelemetry",
  "logging": {
    "OpenTelemetry": {
      "logLevel": {
        "default": "Warning"
      }
    }
  }
}

Écriture dans le journal de la console

L’hôte Functions capture automatiquement tout ce qui est écrit dans stdout ou stderr et le transfère au pipeline de télémétrie. Si vous utilisez également un ConsoleExporter ou que vous écrivez directement dans la console dans votre code, des journaux d’activité dupliqués peuvent apparaitre dans vos données de télémétrie.

Note

Pour éviter les entrées de télémétrie en double, n’ajoutez pas ConsoleExporter ni écrivez dans la console dans le code de production.

Authentification de Microsoft Entra

Lorsque vous utilisez l’authentification Microsoft Entra avec OpenTelemetry, vous devez configurer l’authentification séparément pour le processus hôte et le processus de travail.

Pour configurer l’authentification pour le processus hôte, consultez Exiger l’authentification Microsoft Entra.

Pour configurer l’authentification pour le processus de travail, consultez Activer l’authentification Microsoft Entra.

Prise en charge des attributs de ressource

La prise en charge des attributs de ressources dans Azure Monitor est actuellement en préversion. Pour activer cette fonctionnalité, définissez la variable d’environnement OTEL_DOTNET_AZURE_MONITOR_ENABLE_RESOURCE_METRICS sur true. Ce paramètre ingère les attributs de ressource dans la table de métriques personnalisée.

Données de télémétrie des requêtes en double

Le processus hôte émet automatiquement des données de télémétrie de requête. Si le processus de travail est également instrumenté avec des bibliothèques de suivi des requêtes (par exemple, AspNetCoreInstrumentation dans .NET), la même requête est signalée deux fois.

Note

Étant donné que la distribution Azure Monitor inclut généralement AspNetCoreInstrumentation dans .NET et une instrumentation similaire dans d’autres langages, évitez d’utiliser la distribution Azure Monitor dans le processus de travail pour empêcher les données de télémétrie dupliquées.

Étendues de journalisation non incluses

Par défaut, le processus de travail n’inclut pas les portées dans ses logs. Pour activer les étendues, vous devez configurer ce paramètre explicitement dans le worker. L’exemple suivant montre comment activer des étendues dans .NET isolé :

builder.Logging.AddOpenTelemetry(b => b.IncludeScopes = true);

Données de télémétrie des requêtes manquantes

Les déclencheurs tels que HTTP, Service Bus et Event Hubs dépendent de la propagation de contexte pour le suivi distribué. Avec l’échantillonnage parent comme comportement par défaut, la télémétrie des requêtes n’est pas générée lorsque la requête entrante ou le message n’est pas échantillonné.

OperationId dupliqué

Dans Azure Functions, le OperationId utilisé pour corréler la télémétrie provient directement de la valeur traceparent de la requête ou du message entrant. Si plusieurs appels réutilisent la même valeur traceparent, ces appels obtiennent tous la même OperationId.

Configurer OpenTelemetry avec des variables d’environnement

Vous pouvez configurer le comportement d’OpenTelemetry à l’aide de ses variables d’environnement standard. Ces variables offrent un moyen cohérent de contrôler le comportement entre différents langages et runtimes. Vous pouvez ajuster les stratégies d’échantillonnage, les paramètres d’exportation et les attributs de ressource. Pour plus d’informations sur les variables d’environnement prises en charge, consultez la documentation OpenTelemetry.

Utiliser des diagnostics pour résoudre les problèmes de surveillance

Les diagnostics Azure Functions dans le Portail Azure sont une ressource utile pour détecter et diagnostiquer les problèmes potentiels liés à la surveillance.

Pour accéder aux diagnostics dans votre application :

  1. Dans le portail Azure, accédez à votre ressource d’application de fonction.

  2. Dans le volet gauche, sélectionnez Diagnostiquer et résoudre les problèmes, puis cherchez le flux de travail de télémétrie manquant dans l’application de fonction Application Insights ou OpenTelemetry.

  3. Sélectionnez ce flux de travail, choisissez votre méthode d’ingestion, puis sélectionnez Suivant.

  4. Passez en revue les instructions et les recommandations fournies par l’utilitaire de résolution des problèmes.

Étapes suivantes

En savoir plus sur OpenTelemetry et la surveillance d’Azure Functions :

  • Last updated on