Aktivieren Sie das verteilte OpenTelemetry-Tracing mit dem Durable Task Scheduler.

Die verteilte Protokollierung bietet eine End-to-End-Sichtbarkeit in den Orchestrierungsprozess. Wenn Sie OpenTelemetry mit Durable Task Scheduler aktivieren, erzeugt jede Orchestrierung, Aktivität und Unterorchestrierung verknüpfte Span-Elemente, die Zeitplanung, Reihenfolge und Fehler im gesamten Workflow anzeigen. Sie können diese Ablaufverfolgungen in jedes mit OpenTelemetry kompatible Back-End exportieren, z. B. Azure Monitor Application Insights, Jaeger oder Zipkin.

Durable Functions und die eigenständigen Durable Task SDKs unterstützen OpenTelemetry-gestützte verteilte Ablaufverfolgung, wenn der Durable Task Scheduler als Backend verwendet wird.

So funktioniert es

Die Durable Task-SDKs instrumentieren Orchestrierungen und Aktivitäten automatisch mit OpenTelemetry-Span-Elementen. Das SDK erstellt ein übergeordnetes Span-Element für jede Orchestrierung und ein untergeordnetes Span-Element für jeden Aktivitätsaufruf, jede Unter-Orchestrierung und jeden Timer. Der Tracing-Kontext wird automatisch über alle diese Vorgänge weitergegeben, sodass Sie einen einzigen, korrelierten Trace für den gesamten Workflow erhalten.

Die resultierende Ablaufverfolgungsstruktur sieht wie folgt aus:

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

Sie müssen Ihrem Orchestrator- oder Aktivitätscode keine benutzerdefinierte Instrumentierung hinzufügen. Registrieren Sie die Aktivitätsquelle Microsoft.DurableTask mit Ihrer OpenTelemetry-Konfiguration, und das SDK behandelt den Rest.

Voraussetzungen

Ein Azure Functions Projekt mit der Erweiterung Durable Functions Version 2.13.0 oder höher.
Durable Task Scheduler wurde als Speicher-Backend für Ihre Funktions-App konfiguriert.
Ein mit OpenTelemetry kompatibles Back-End zum Anzeigen von Ablaufverfolgungen (Application Insights, Jaeger oder ein anderer OTLP-Collector).

.NET 8 SDK oder höher.
Die Microsoft.DurableTask.Worker.AzureManaged und Microsoft.DurableTask.Client.AzureManaged NuGet Pakete.
Die OpenTelemetry, OpenTelemetry.Extensions.Hosting und OpenTelemetry.Exporter.OpenTelemetryProtocol NuGet-Pakete.

Ein OpenTelemetry-kompatibles Back-End zum Anzeigen von Traces, z. B. Application Insights für die Produktion oder Jaeger für die lokale Entwicklung.

Aktivieren der verteilten Ablaufverfolgung

Um die verteilte Ablaufverfolgung in Durable Functions zu aktivieren, aktualisieren Sie Ihre host.json und konfigurieren Sie ein mit OpenTelemetry kompatibles Telemetrie-Back-End.

Aktualisieren von host.json

Fügen Sie den tracing Abschnitt unter durableTask in Ihrer host.json-Datei hinzu.

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

Application Insights konfigurieren

Legen Sie die APPLICATIONINSIGHTS_CONNECTION_STRING Umgebungsvariable in Ihrer Funktions-App fest.

Fügen Sie sie für die lokale Entwicklung zu local.settings.jsonhinzu:

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

Fügen Sie sie für Azure gehostete Apps im Azure Portal als Anwendungseinstellung unter Configuration hinzu.

Hinweis

Wenn Sie zuvor APPINSIGHTS_INSTRUMENTATIONKEY verwendet haben, wechseln Sie zu APPLICATIONINSIGHTS_CONNECTION_STRING zu den neuesten Funktionen.

Reduzieren von Telemetriegeräuschen

Um zu verhindern, dass Application Insights Ablaufverfolgungsdaten herausfiltert, schließen Sie Request von den Samplingregeln in host.json aus:

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

Registrieren Sie die Aktivitätsquelle Microsoft.DurableTask mit Ihrer OpenTelemetry-Konfiguration. Das Durable Task-SDK erstellt automatisch Abschnitte für Orchestrierungen und Aktivitäten, wenn Sie diese Quelle registrieren.

Fügen Sie in der Datei Program.cs Ihres Workers die OpenTelemetry-Ablaufverfolgung mit der Durable Task-Aktivitätsquelle hinzu.

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();

Die Schlüsselzeile lautet .AddSource("Microsoft.DurableTask"), wodurch OpenTelemetry aufgefordert wird, Span-Elemente zu erfassen, die das Durable Task-SDK ausgibt.

Initialisieren Sie das OpenTelemetry SDK vor dem Importieren von Durable Task-Modulen. Mit dieser Reihenfolge wird sichergestellt, dass die globale TracerProvider Datei registriert wird, bevor das SDK geladen wird.

// 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();

Das Durable Task JS-SDK gibt automatisch Span-Elemente aus, wenn Sie einen TracerProvider global registrieren.

Konfigurieren Sie OpenTelemetry TracerProvider , bevor Sie den Durable-Task-Worker erstellen.

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()

Das Durable Task Python-SDK instrumentiert automatisch Orchestrierungen und Aktivitäten, wenn Sie einen TracerProvider konfigurieren.

Das Java Durable Task-SDK instrumentiert automatisch Orchestrierungen und Aktivitäten mit OpenTelemetry-Span-Elementen, wenn Sie das OpenTelemetrySdk global registrieren. Das SDK verwendet den Namen der Microsoft.DurableTask-Ablaufverfolgung (entspricht der .NET-Aktivitätsquelle) und erstellt Span-Elemente der Server-Art für die Orchestrierungs- und Aktivitätsausführung. Darüber hinaus gibt es W3C-Ablaufverfolgungskontext (traceparent/tracestate) über Client-, Orchestrierungs-, Aktivitäts- und Unterorchestrierungsgrenzen hinweg weiter.

Fügen Sie die OpenTelemetry-Abhängigkeiten zu Ihrem Build.gradle hinzu:

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}"
}

Konfigurieren Sie das OpenTelemetry SDK mit einem OTLP-Exporter in Ihrer Anwendung:

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");

Der buildAndRegisterGlobal() Aufruf registriert das OpenTelemetry SDK global. Das Durable Task-SDK verwendet GlobalOpenTelemetry.getTracer("Microsoft.DurableTask") intern, sodass diese Konfiguration automatisch übernommen wird und Span-Elemente für Orchestrierungen und Aktivitäten erstellt werden.

Konfigurieren des OTLP-Endpunkts

Die oben genannten Codeausschnitte beziehen sich auf die Umgebungsvariable OTEL_EXPORTER_OTLP_ENDPOINT, um das Ziel für Trace-Daten festzulegen. Legen Sie diese Variable basierend auf Ihrem Back-End fest:

Back-End	Endpunktwert	Protokoll
Jaeger (lokal)	`http://localhost:4317`	gRPC
Jaeger (lokal, HTTP)	`http://localhost:4318`	HTTP/protobuf
OpenTelemetry Collector	`http://<collector-host>:4317`	gRPC
Azure Monitor (über OTLP)	Verwenden Sie stattdessen den Azure Monitor-Exporter.	N/A

Für die lokale Entwicklung mit Jaeger funktioniert die Standard-Einstellung http://localhost:4317, wenn Jaeger mit aktiviertem OTLP gRPC (Port 4317) ausgeführt wird. Das JavaScript SDK verwendet standardmäßig HTTP/protobuf, sodass es auf den Port 4318 mit dem /v1/traces Pfad ausgerichtet ist.

Lokales Anzeigen von Ablaufverfolgungen mit Jaeger UI

Verwenden Sie für die lokale Entwicklung den Durable Task Scheduler-Emulator mit Jaeger, um Ablaufverfolgungen anzuzeigen. Verwenden Sie eine docker-compose.yml , um beide Dienste zu starten:

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

Starten Sie die Infrastruktur:

docker compose up -d

Öffnen Sie nach dem Ausführen Ihrer Anwendung die Jaeger-Benutzeroberfläche unter http://localhost:16686, und suchen Sie nach Ihrem Dienstnamen (z. B. durable-worker), um Ablaufverfolgungen anzuzeigen.

Für die lokale Entwicklung mit Durable Functions werden verteilte Ablaufverfolgungsdaten standardmäßig an Application Insights gesendet. Um Ablaufverfolgungen lokal ohne Bereitstellung anzuzeigen, können Sie einen OTLP exporter zusammen mit Application Insights in Ihrer Funktionen-App Program.cshinzufügen.

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

Führen Sie dann Jaeger lokal mit docker run -d -p 16686:16686 -p 4317:4317 jaegertracing/jaeger:latest und öffnen Sie die Jaeger UI unter http://localhost:16686.

Anzeigen von Ablaufverfolgungen in Application Insights

Für Produktionsworkloads ist Application Insights das empfohlene Telemetrie-Back-End.

Sobald DistributedTracingEnabled auf true und Version auf V2 in host.json festgelegt ist, gibt Ihre Durable Functions-App korrelierte Span-Elementes an Application Insights aus. So zeigen Sie die vollständige Orchestrierungsnachverfolgung im Azure-Portal an:

Wechseln Sie im Azure-Portal zu Ihrer Application Insights-Ressource.
Öffnen Sie die Transaktionssuche, und suchen Sie nach Ihrer Orchestrierung anhand des Namens oder der Instanz-ID.
Wählen Sie eine Ablaufverfolgung aus, um die End-to-End-Transaktion mit allen korrelierten Spans anzuzeigen.

Die Ablaufverfolgung zeigt die Orchestrierung als übergeordnetes Span-Element mit untergeordneten Span-Elementen für jeden Aktivitätsaufruf, die Suborchestrierung und die Wartezeit des Zeitgebers an. Die folgenden Muster erzeugen unterschiedliche Formen von Ablaufverfolgungen.

Schema	Spurform
Funktionskette	Sequenzielle Aktivitäten sind unter den Span-Elementen des Orchestrators verschachtelt.
Auffächern nach außen/innen	Parallele Aktivitätsspan-Elemente überlappen sich im Zeitverlauf.
Menschliche Interaktion	Ein Orchestrator-Abschnitt mit einer langen Wartezeit auf ein externes Ereignis.
Monitor	Wiederholte Aktivitätsphasen mit Zeitwartezeiten zwischen Iterationen.

Konfigurieren Sie den OTLP-Exporter so, dass Ablaufverfolgungen mithilfe des Azure Monitor OpenTelemetry-Exporters an Application Insights gesendet werden. Alternativ können Sie die Abläufe über OTLP an einen OpenTelemetry-Collector exportieren, der sie dann an Application Insights weiterleitet.

Installieren Sie das Azure.Monitor.OpenTelemetry.Exporter NuGet-Paket, und ersetzen Sie den OTLP-Exporter durch:

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

Installieren Sie das @azure/monitor-opentelemetry-exporter npm-Paket, und konfigurieren Sie den Exporter:

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();

Installieren Sie das azure-monitor-opentelemetry-exporter Pip-Paket, und konfigurieren Sie Folgendes:

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)

Verwenden Sie den Azure Monitor OpenTelemetry-Exporter für Java, oder konfigurieren Sie den OpenTelemetry-Java-Agent mit dem Application Insights-Verbindungszeichenfolge:

// 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")));

Welche Informationen aus den Ablaufverfolgungsdaten hervorgehen

Zu den Ablaufverfolgungsdaten, die von den Durable Task SDKs erzeugt werden, gehören:

Span-Typ	Beschreibung
`create_orchestration`	Das clientseitige Span-Element, das beim Planen einer neuen Orchestrierung ausgegeben wird
`orchestration`	Der serverseitige Orchestrierungsbereich umfasst den vollständigen Ausführungslebenszyklus.
`activity:<name>`	Eine Spanne für jeden Aktivitätsaufruf mit Anzeigedauer und Ergebnis
`sub_orchestration:<name>`	Ein Span-Element für jeden Unter-Orchestrierungsaufruf
`timer`	Ein Span-Element für lange Timerwartezeiten

Jeder Bereich enthält Attribute wie durabletask.type, durabletask.task.name, , durabletask.task.instance_idund durabletask.task.task_id. Fehlgeschlagene Aktivitäten und Orchestrierungen beinhalten Fehlerdetails im Status und den Ereignissen des jeweiligen Span-Elements.

Problembehandlung

Thema	Resolution
Es werden keine Spuren angezeigt	Überprüfen Sie, ob die `Microsoft.DurableTask` Aktivitätsquelle registriert ist und der Exporterendpunkt erreichbar ist.
Ablaufverfolgungen sind unvollständig	Überprüfen Sie, ob das OpenTelemetry SDK vor dem Durable Task SDK (insbesondere in JavaScript/TypeScript) initialisiert wird.
Fehlende Spannweiten in Application Insights	Deaktivieren Sie die Samplingeinstellungen, oder passen Sie sie an, um zu verhindern, dass Ablaufverfolgungsdaten gelöscht werden.
Spuren hängen nicht zusammen	Überprüfen Sie, ob Sie den permanenten Aufgabenplaner als Back-End verwenden. Für die Propagierung des Ablaufverfolgungskontextes ist der Scheduler erforderlich.

Beispielcode

Beispiel für verteiltes Tracing V2 bei Durable Functions (C#)

Feedback

War diese Seite hilfreich?

Last updated on 2026-05-05