Activer le suivi distribué OpenTelemetry avec Durable Task Scheduler

Le suivi distribué offre une visibilité de bout en bout sur l’exécution de l’orchestration. Lorsque vous activez OpenTelemetry avec Durable Task Scheduler, chaque orchestration, activité et sous-orchestration produit des spans liées qui affichent la chronologie, l'ordre et les erreurs dans l'ensemble du flux de travail. Vous pouvez exporter ces traces vers n’importe quel serveur principal compatible OpenTelemetry, comme Azure Monitor Application Insights, Jaeger ou Zipkin.

Durable Functions et les SDK de tâches durables autonomes prennent tous deux en charge le suivi distribué OpenTelemetry lors de l’utilisation du planificateur de tâches durables comme back-end.

Fonctionnement

Les SDK Durable Task instrumentent automatiquement les orchestrations et les activités avec des étendues OpenTelemetry. Le Kit de développement logiciel (SDK) crée une étendue parent pour chaque orchestration et des étendues enfants pour chaque appel d’activité, sous-orchestration et minuteur. Le contexte de trace se propage automatiquement dans toutes ces opérations, de sorte que vous obtenez une trace unique et corrélée pour l’ensemble du flux de travail.

L’arborescence de trace résultante ressemble à ceci :

create_orchestration (client)
  └─ orchestration (server)
       ├─ activity:Step1
       ├─ activity:Step2
       └─ activity:Step3

Vous n’avez pas besoin d’ajouter d’instrumentation personnalisée à votre orchestrateur ou à votre code d’activité. Inscrivez la source d’activité Microsoft.DurableTask avec votre configuration OpenTelemetry, et le SDK gère le reste.

Prerequisites

Projet Azure Functions avec l’extension Durable Functions version 2.13.0 ou ultérieure.
Planificateur de tâches durables configuré comme arrière-plan de stockage pour votre application fonctionnelle.
Un back-end compatible OpenTelemetry pour l’affichage des traces (Application Insights, Jaeger ou un autre collecteur OTLP).

SDK .NET 8 ou version ultérieure.
Packages NuGet Microsoft.DurableTask.Worker.AzureManaged et Microsoft.DurableTask.Client.AzureManaged.
Packages OpenTelemetry, OpenTelemetry.Extensions.Hosting et OpenTelemetry.Exporter.OpenTelemetryProtocol NuGet.

Un back-end compatible avec OpenTelemetry pour visualiser les traces, comme Application Insights pour la production ou Jaeger pour le développement local.

Activer le suivi distribué

Pour activer le suivi distribué dans Durable Functions, mettez à jour votre host.json et configurez un back-end de télémétrie compatible OpenTelemetry.

Mise à jour de host.json

Ajoutez la tracing section sous durableTask, dans votre fichier host.json :

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "tracing": {
        "DistributedTracingEnabled": true,
        "Version": "V2"
      }
    }
  }
}

Configurer Application Insights

Définissez la variable d’environnement APPLICATIONINSIGHTS_CONNECTION_STRING dans votre application de fonction.

Pour le développement local, ajoutez-le à local.settings.json:

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
    "APPLICATIONINSIGHTS_CONNECTION_STRING": "<your-connection-string>"
  }
}

Pour les applications hébergées Azure, ajoutez-la en tant que paramètre d’application sous Configuration dans le portail Azure.

Note

Si vous avez utilisé APPINSIGHTS_INSTRUMENTATIONKEY précédemment, basculez vers APPLICATIONINSIGHTS_CONNECTION_STRING pour bénéficier des fonctionnalités les plus récentes.

Réduire le bruit de télémétrie

Pour empêcher Application Insights d’extraire des données de trace, excluez Request les règles d’échantillonnage dans host.json:

{
  "logging": {
    "applicationInsights": {
      "samplingSettings": {
        "isEnabled": true,
        "excludedTypes": "Request"
      }
    }
  }
}

Inscrivez la source d’activité Microsoft.DurableTask avec votre configuration OpenTelemetry. Le SDK Durable Task crée automatiquement des étendues pour les orchestrations et les activités lorsque vous inscrivez cette source.

Dans le fichier Program.cs de votre worker, ajoutez le suivi OpenTelemetry avec la source d’activité Durable Task :

using Microsoft.DurableTask;
using Microsoft.DurableTask.Worker;
using Microsoft.DurableTask.Worker.AzureManaged;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using OpenTelemetry;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var builder = Host.CreateApplicationBuilder(args);

// Configure OpenTelemetry tracing
builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("durable-worker"))
    .WithTracing(tracing =>
    {
        tracing
            .AddSource("Microsoft.DurableTask")
            .AddOtlpExporter(opts =>
            {
                opts.Endpoint = new Uri(
                    Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT")
                    ?? "http://localhost:4317");
            });
    });

// Build connection string from environment variables
string endpoint = Environment.GetEnvironmentVariable("ENDPOINT") ?? "http://localhost:8080";
string taskHub = Environment.GetEnvironmentVariable("TASKHUB") ?? "default";
string connectionString = endpoint.Contains("localhost")
    ? $"Endpoint={endpoint};TaskHub={taskHub};Authentication=None"
    : $"Endpoint={endpoint};TaskHub={taskHub};Authentication=DefaultAzure";

// Configure Durable Task worker
builder.Services.AddDurableTaskWorker()
    .AddTasks(tasks =>
    {
        tasks.AddOrchestratorFunc<string, string>(
            "OrderProcessingOrchestration", async (ctx, input) =>
        {
            var validated = await ctx.CallActivityAsync<string>("ValidateOrder", input);
            var payment = await ctx.CallActivityAsync<string>("ProcessPayment", validated);
            var shipment = await ctx.CallActivityAsync<string>("ShipOrder", payment);
            var result = await ctx.CallActivityAsync<string>("SendNotification", shipment);
            return result;
        });

        tasks.AddActivityFunc<string, string>("ValidateOrder", (ctx, input) =>
            Task.FromResult($"Validated({input})"));
        tasks.AddActivityFunc<string, string>("ProcessPayment", (ctx, input) =>
            Task.FromResult($"Paid({input})"));
        tasks.AddActivityFunc<string, string>("ShipOrder", (ctx, input) =>
            Task.FromResult($"Shipped({input})"));
        tasks.AddActivityFunc<string, string>("SendNotification", (ctx, input) =>
            Task.FromResult($"Notified({input})"));
    })
    .UseDurableTaskScheduler(connectionString);

var host = builder.Build();
await host.RunAsync();

La ligne principale est .AddSource("Microsoft.DurableTask"), ce qui indique à OpenTelemetry de capturer des segments que le SDK Durable Task émet.

Initialisez le Kit de développement logiciel (SDK) OpenTelemetry avant d’importer des modules Durable Task. Cet ordre garantit que la variable globale TracerProvider est inscrite avant le chargement du Kit de développement logiciel (SDK).

// 1. OpenTelemetry SDK bootstrap — must run before other imports
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { resourceFromAttributes } from "@opentelemetry/resources";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

const otlpEndpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4318";

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "durable-worker",
  }),
  spanProcessors: [
    new SimpleSpanProcessor(
      new OTLPTraceExporter({ url: `${otlpEndpoint}/v1/traces` })
    ),
  ],
});
sdk.start();

// 2. Import Durable Task modules after OpenTelemetry is initialized
import {
  DurableTaskAzureManagedClientBuilder,
  DurableTaskAzureManagedWorkerBuilder,
} from "@microsoft/durabletask-js-azuremanaged";

// 3. Create the worker and client using the builders
const connectionString = process.env.DTS_CONNECTION_STRING
  || "Endpoint=http://localhost:8080;Authentication=None";

const worker = new DurableTaskAzureManagedWorkerBuilder(connectionString)
  .addOrchestrator(myOrchestrator)
  .addActivity(myActivity)
  .build();

const client = new DurableTaskAzureManagedClientBuilder(connectionString).build();

Le SDK Durable Task JS émet automatiquement des étendues lorsque vous inscrivez une TracerProvider globalement.

Configurez OpenTelemetry TracerProvider avant de créer le worker Durable Task :

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.sdk.resources import Resource
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
import durabletask.task as task

# Configure OpenTelemetry
resource = Resource.create({"service.name": "durable-worker"})
provider = TracerProvider(resource=resource)
otlp_endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

# Define activities
def validate_order(ctx: task.ActivityContext, order_id: str) -> str:
    return f"Validated({order_id})"

def process_payment(ctx: task.ActivityContext, input: str) -> str:
    return f"Paid({input})"

def ship_order(ctx: task.ActivityContext, input: str) -> str:
    return f"Shipped({input})"

def send_notification(ctx: task.ActivityContext, input: str) -> str:
    return f"Notified({input})"

# Define orchestrator
def order_processing(ctx: task.OrchestrationContext, order_id: str):
    validated = yield ctx.call_activity(validate_order, input=order_id)
    paid = yield ctx.call_activity(process_payment, input=validated)
    shipped = yield ctx.call_activity(ship_order, input=paid)
    result = yield ctx.call_activity(send_notification, input=shipped)
    return result

# Start worker
if __name__ == "__main__":
    endpoint = os.environ.get("ENDPOINT", "http://localhost:8080")
    taskhub = os.environ.get("TASKHUB", "default")

    with DurableTaskSchedulerWorker(
        host_address=endpoint,
        secure_channel=not endpoint.startswith("http://localhost"),
        taskhub=taskhub,
        token_credential=None,
    ) as w:
        w.add_orchestrator(order_processing)
        w.add_activity(validate_order)
        w.add_activity(process_payment)
        w.add_activity(ship_order)
        w.add_activity(send_notification)
        w.start()

Le SDK Durable Task Python instrumente automatiquement les orchestrations et les activités lorsque vous configurez un TracerProvider.

Le SDK Durable Task Java instrumente automatiquement les orchestrations et les activités avec des étendues OpenTelemetry lorsque vous inscrivez le OpenTelemetrySdk globalement. Le SDK utilise le nom de trace Microsoft.DurableTask (correspondant à la source d’activité .NET) et crée des étendues de type Server pour l’orchestration et l’exécution de l’activité. Il propage également le contexte de trace W3C (traceparent/tracestate) entre les limites du client, de l’orchestration, de l’activité et des sous-orchestrations.

Ajoutez les dépendances OpenTelemetry à votre build.gradle :

def openTelemetryVersion = '1.58.0'

dependencies {
    implementation "com.microsoft:durabletask-client:1.7.0"
    implementation "com.microsoft:durabletask-azuremanaged:1.7.0"
    implementation "io.opentelemetry:opentelemetry-api:${openTelemetryVersion}"
    implementation "io.opentelemetry:opentelemetry-sdk:${openTelemetryVersion}"
    implementation "io.opentelemetry:opentelemetry-exporter-otlp:${openTelemetryVersion}"
}

Configurez le Kit de développement logiciel (SDK) OpenTelemetry avec un exportateur OTLP dans votre application :

import io.opentelemetry.sdk.OpenTelemetrySdk;
import io.opentelemetry.sdk.trace.SdkTracerProvider;
import io.opentelemetry.sdk.trace.export.BatchSpanProcessor;
import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;
import io.opentelemetry.sdk.resources.Resource;
import io.opentelemetry.api.trace.Tracer;

String otlpEndpoint = System.getenv("OTEL_EXPORTER_OTLP_ENDPOINT");
if (otlpEndpoint == null) {
    otlpEndpoint = "http://localhost:4317";
}

OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint(otlpEndpoint)
    .build();

SdkTracerProvider tracerProvider = SdkTracerProvider.builder()
    .setResource(Resource.builder().put("service.name", "durable-worker").build())
    .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
    .build();

OpenTelemetrySdk openTelemetry = OpenTelemetrySdk.builder()
    .setTracerProvider(tracerProvider)
    .buildAndRegisterGlobal();

Tracer tracer = openTelemetry.getTracer("durable-worker");

L'appel buildAndRegisterGlobal() enregistre le SDK OpenTelemetry de manière globale. Le SDK Durable Task utilise GlobalOpenTelemetry.getTracer("Microsoft.DurableTask") en interne, ce qui lui permet de récupérer automatiquement cette configuration et de créer des étendues pour les orchestrations et les activités.

Configurer le point de terminaison OTLP

Les extraits de code ci-dessus référencent la OTEL_EXPORTER_OTLP_ENDPOINT variable d’environnement pour définir la destination des données de trace. Définissez cette variable en fonction de votre back-end :

Backend	Valeur du point de terminaison	Protocol
Jaeger (local)	`http://localhost:4317`	gRPC
Jaeger (local, HTTP)	`http://localhost:4318`	HTTP/protobuf
Collecteur OpenTelemetry	`http://<collector-host>:4317`	gRPC
Azure Monitor (via OTLP)	Utilisez plutôt l’exportateur Azure Monitor	N/A

Pour le développement local avec Jaeger, la valeur par défaut http://localhost:4317 fonctionne quand Jaeger est en cours d’exécution avec otLP gRPC activé (port 4317). Le Kit de développement logiciel (SDK) JavaScript utilise http/protobuf par défaut. Il cible donc le port 4318 avec le chemin d’accès /v1/traces .

Afficher les traces localement avec l’interface utilisateur Jaeger

Pour le développement local, utilisez l’émulateur Durable Task Scheduler avec Jaeger pour afficher les traces. Utilisez un docker-compose.yml pour démarrer les deux services :

services:
  dts-emulator:
    image: mcr.microsoft.com/dts/dts-emulator:latest
    ports:
      - "8080:8080"  # gRPC
      - "8082:8082"  # Dashboard
  jaeger:
    image: jaegertracing/jaeger:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP

Démarrez l’infrastructure :

docker compose up -d

Après avoir exécuté votre application, ouvrez l’interface utilisateur Jaeger à l’adresse http://localhost:16686 et recherchez le nom de votre service (par exemple durable-worker) pour afficher les traces.

Pour le développement local avec Durable Functions, les données de suivi distribuées sont envoyées par défaut à Application Insights. Pour afficher les traces localement sans déployer, vous pouvez ajouter un exportateur OTLP avec Application Insights dans votre fonction de l'application Program.cs.

builder.Services.AddOpenTelemetry()
    .WithTracing(tracing =>
    {
        tracing
            .AddSource("Microsoft.DurableTask")
            .AddOtlpExporter(opts =>
            {
                opts.Endpoint = new Uri("http://localhost:4317");
            });
    });

Ensuite, exécutez Jaeger localement avec docker run -d -p 16686:16686 -p 4317:4317 jaegertracing/jaeger:latest et ouvrez l’interface utilisateur Jaeger à l’adresse http://localhost:16686.

Afficher les traces dans Application Insights

Pour les charges de travail de production, Application Insights est le back-end de télémétrie recommandé.

Une fois DistributedTracingEnabled défini sur true avec Version défini sur V2 dans host.json, votre application Durable Functions émet des étendues corrélées à Application Insights. Pour afficher la trace d’orchestration complète dans le portail Azure :

Accédez à votre ressource Application Insights dans le portail Azure.
Ouvrez la recherche transactionnelle et recherchez votre orchestration par nom ou ID d’instance.
Sélectionnez une trace pour afficher la transaction intégrale avec tous les segments corrélés.

La trace montre l’orchestration en tant qu’étendue parent, avec des étendues enfants pour chaque appel d’activité, sous-orchestration et attente de minuteur. Les modèles suivants produisent des formes de trace distinctes :

Modèle	Forme de trace
Chaînage de fonctions	Les étendues d’activités séquentielles sont imbriquées sous l’étendue de l’orchestrateur.
Fan-out/fan-in	Les périodes d'activité parallèle se chevauchent dans le temps.
Interaction humaine	Une étendue d’orchestrateur avec une longue attente pour un événement externe.
Monitor	Des étendues d’activité répétées avec des attentes de minuteur entre les itérations.

Configurez l’exportateur OTLP pour envoyer des traces à Application Insights à l’aide de l’exportateur Azure Monitor OpenTelemetry ou exportez via OTLP vers un collecteur OpenTelemetry qui transfère à Application Insights.

Installez le package NuGet Azure.Monitor.OpenTelemetry.Exporter et remplacez l’exportateur OTLP par :

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("durable-worker"))
    .WithTracing(tracing =>
    {
        tracing
            .AddSource("Microsoft.DurableTask")
            .AddAzureMonitorTraceExporter(opts =>
            {
                opts.ConnectionString = Environment.GetEnvironmentVariable(
                    "APPLICATIONINSIGHTS_CONNECTION_STRING");
            });
    });

Installez le @azure/monitor-opentelemetry-exporter package npm et configurez l’exportateur :

import { AzureMonitorTraceExporter } from "@azure/monitor-opentelemetry-exporter";

const exporter = new AzureMonitorTraceExporter({
  connectionString: process.env.APPLICATIONINSIGHTS_CONNECTION_STRING,
});

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "durable-worker",
  }),
  spanProcessors: [new SimpleSpanProcessor(exporter)],
});
sdk.start();

Installez le azure-monitor-opentelemetry-exporter package pip et configurez :

from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter

exporter = AzureMonitorTraceExporter(
    connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"]
)
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

Utilisez l’exportateur Azure Monitor OpenTelemetry pour Java ou configurez l’agent OpenTelemetry Java avec l’chaîne de connexion Application Insights :

// Using the Azure Monitor OpenTelemetry exporter
// Add com.azure:azure-monitor-opentelemetry-exporter to your dependencies
import com.azure.monitor.opentelemetry.exporter.AzureMonitorExporterOptions;
import com.azure.monitor.opentelemetry.exporter.AzureMonitorTraceExporter;

AzureMonitorTraceExporter azureExporter = new AzureMonitorTraceExporter(
    new AzureMonitorExporterOptions()
        .connectionString(System.getenv("APPLICATIONINSIGHTS_CONNECTION_STRING")));

Quelles sont les données de trace qui s’affichent

Les données de trace produites par les kits SDK Durable Task incluent les éléments suivants :

Type d’étendue	Description
`create_orchestration`	L’étendue côté client émise lors de la planification d’une nouvelle orchestration
`orchestration`	L’orchestration côté serveur couvre le cycle de vie d’exécution complet
`activity:<name>`	Un tracé pour chaque appel d'une activité, affichant le timing et le résultat
`sub_orchestration:<name>`	Un intervalle pour chaque appel de sous-orchestration
`timer`	Une étendue pour les attentes de minuteur durable

Chaque étendue inclut des attributs tels que durabletask.type, , durabletask.task.namedurabletask.task.instance_id, et durabletask.task.task_id. Les activités et les orchestrations ayant échoué incluent les détails de l’erreur dans le statut de l’étendue et dans ses événements.

Résolution des problèmes

Problème	Résolution
Aucune trace n’apparaît	Vérifiez que la `Microsoft.DurableTask` source d’activité est inscrite et que le point de terminaison de l’exportateur est accessible.
Les traces sont incomplètes	Vérifiez que le Kit de développement logiciel (SDK) OpenTelemetry est initialisé avant le Kit de développement logiciel (SDK) Durable Task (en particulier en JavaScript/TypeScript).
Étendues manquantes dans Application Insights	Désactivez ou ajustez les paramètres d’échantillonnage pour empêcher la suppression des données de trace.
Les traces ne sont pas corrélées	Vérifiez que vous utilisez Durable Task Scheduler comme back-end. La propagation du contexte de trace nécessite le planificateur.

Exemple de code

Exemple de traçabilité distribuée V2 pour les fonctions durables (C#)

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-05-05