Durable Task Scheduler を使用して OpenTelemetry 分散トレースを有効にする

分散トレースを使用すると、オーケストレーションの実行をエンドツーエンドで可視化できます。 Durable Task Scheduler で OpenTelemetry を有効にすると、各オーケストレーション、アクティビティ、サブオーケストレーションによって、ワークフロー全体のタイミング、順序、エラーを示すリンクされたスパンが生成されます。これらのトレースは、Azure Monitor Application Insights、Jaeger、または Zipkin など、OpenTelemetry 互換のバックエンドにエクスポートできます。

Durable Functions スタンドアロンの Durable Task SDK はどちらもバックエンドとして Durable Task Scheduler を使用する場合に OpenTelemetry 分散トレースをサポートします。

どのように機能するのか

Durable Task SDK は、OpenTelemetry スパンを使用し、オーケストレーションとアクティビティを自動的にインストルメント化します。 SDK は、各オーケストレーションのために親スパンを作成し、各アクティビティ呼び出し、サブオーケストレーション、タイマーごとに子スパンを作成します。トレースコンテキストはこれらすべての操作に自動的に伝達されるため、ワークフロー全体に対して 1 つの相関トレースが取得されます。

結果のトレースツリーは次のようになります。

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

オーケストレーターまたはアクティビティコードにカスタムインストルメンテーションを追加する必要はありません。 Microsoft.DurableTask アクティビティソースを OpenTelemetry 構成に登録すると、SDK によって残りの処理が行われます。

前提条件

Durable Functions 拡張機能バージョン 2.13.0 以降を含むAzure Functions プロジェクト。
関数アプリのストレージバックエンドとして構成された Durable Task Scheduler。
トレースを表示するための OpenTelemetry 互換バックエンド (Application Insights、Jaeger、または別の OTLP コレクター)。

.NET 8 SDK 以降。
Microsoft.DurableTask.Worker.AzureManagedとMicrosoft.DurableTask.Client.AzureManaged NuGet パッケージ。
NuGet パッケージの OpenTelemetry、 OpenTelemetry.Extensions.Hosting、および OpenTelemetry.Exporter.OpenTelemetryProtocol 。

運用用の Application Insights やローカル開発用の Jaeger など、トレースを表示するための OpenTelemetry 互換バックエンド。

分散トレースを有効にする

Durable Functionsで分散トレースを有効にするには、host.json を更新し、OpenTelemetry と互換性のあるテレメトリバックエンドを構成します。

host.json を更新する

host.jsontracingdurableTask の下にセクションを追加します。

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

Application Insights の構成

関数アプリで APPLICATIONINSIGHTS_CONNECTION_STRING 環境変数を設定します。

ローカル開発の場合は、 local.settings.jsonに追加します。

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

Azureホストされているアプリの場合は、Azure ポータルの Configuration の下にアプリケーション設定として追加します。

注

以前に APPINSIGHTS_INSTRUMENTATIONKEYを使用していた場合は、最新の機能の APPLICATIONINSIGHTS_CONNECTION_STRING に切り替えます。

テレメトリのノイズを削減する

Application Insights がトレースデータをサンプリングしないようにするには、host.jsonのサンプリング規則からRequestを除外します。

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

Microsoft.DurableTask アクティビティソースを OpenTelemetry 構成に登録します。 Durable Task SDK では、このソースを登録すると、オーケストレーションとアクティビティのスパンが自動的に作成されます。

ワーカーの Program.csで、Durable Task アクティビティソースを使用して OpenTelemetry トレースを追加します。

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

重要な行は .AddSource("Microsoft.DurableTask")であり、Durable Task SDK が出力するスパンをキャプチャするように OpenTelemetry に指示します。

Durable Task モジュールをインポートする前に、OpenTelemetry SDK を初期化します。この順序により、SDK が読み込まれる前にグローバル TracerProvider が確実に登録されます。

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

Durable Task JS SDK は、 TracerProvider をグローバルに登録すると、スパンを自動的に出力します。

Durable Task worker を作成する前に、OpenTelemetry TracerProvider を構成します。

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

Durable Task Python SDK では、TracerProviderを構成すると、オーケストレーションとアクティビティが自動的にインストルメント化されます。

お客様が OpenTelemetrySdkをグローバルに登録すると、Java Durable Task SDK は、OpenTelemetry スパンを使用してオーケストレーションとアクティビティを自動的にインストルメント化します。 SDK では、Microsoft.DurableTask トレーサー名 (.NET アクティビティソースと一致) を使用し、オーケストレーションとアクティビティの実行にServer 種類のスパンを作成します。また、W3C トレースコンテキスト (traceparent/tracestate) をクライアント、オーケストレーション、アクティビティ、およびサブオーケストレーションの境界に伝達します。

OpenTelemetry 依存関係を 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}"
}

アプリケーションで OTLP エクスポーターを使用して OpenTelemetry SDK を構成します。

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

buildAndRegisterGlobal()呼び出しにより、OpenTelemetry SDK がグローバルに登録されます。 Durable Task SDK は内部で GlobalOpenTelemetry.getTracer("Microsoft.DurableTask") を使用するため、この構成は自動的に取得され、オーケストレーションとアクティビティのスパンが作成されます。

OTLP エンドポイントを構成する

上記のコードスニペットは、 OTEL_EXPORTER_OTLP_ENDPOINT 環境変数を参照して、トレースデータの宛先を設定します。バックエンドに基づいてこの変数を設定します。

Backend	エンドポイント値	プロトコル
Jaeger (ローカル)	`http://localhost:4317`	gRPC
Jaeger (ローカル、HTTP)	`http://localhost:4318`	HTTP/protobuf
OpenTelemetry コレクター	`http://<collector-host>:4317`	gRPC
Azure Monitor (OTLP 経由)	代わりに Azure Monitor エクスポーターを使用する	N/A

Jaeger を使用したローカル開発では、Jaeger が OTLP gRPC を有効 (ポート 4317) で実行している場合、既定の http://localhost:4317 が機能します。 JavaScript SDK は既定で HTTP/protobuf を使用するため、4318 パスを持つポート /v1/tracesを対象とします。

Jaeger UI を使用してトレースをローカルで表示する

ローカル開発の場合は、Jaeger で Durable Task Scheduler エミュレーターを使用してトレースを表示します。両方のサービスを開始するには、 docker-compose.yml を使用します。

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

インフラストラクチャを開始します。

docker compose up -d

アプリケーションを実行したら、 http://localhost:16686 で Jaeger UI を開き、サービス名 ( durable-worker など) を検索してトレースを表示します。

Durable Functionsを使用したローカル開発の場合、分散トレースデータは既定で Application Insights に送信されます。デプロイせずにトレースをローカルで表示するには、関数アプリの Program.csに Application Insights と共に OTLP エクスポーターを追加します。

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

次に、 docker run -d -p 16686:16686 -p 4317:4317 jaegertracing/jaeger:latest を使用して Jaeger をローカルで実行し、 http://localhost:16686で Jaeger UI を開きます。

Application Insights でトレースを表示する

運用環境のワークロードでは、 Application Insights が推奨されるテレメトリバックエンドです。

DistributedTracingEnabled の中で true が Version に設定され、V2 が host.json に設定された後、開発中の Durable Functions アプリは、Application Insights に関連付けられたスパンを出力します。 Azure ポータルで完全なオーケストレーショントレースを表示するには:

Azure ポータルで Application Insights リソースに移動します。
トランザクション検索を開き、名前またはインスタンス ID でオーケストレーションを検索します。
トレースを選択すると、すべての相関スパンを持つエンドツーエンドのトランザクションが表示されます。

トレースは、各アクティビティ呼び出し、サブオーケストレーション、タイマー待機ごとに、子スパンを持つ親スパンという形でオーケストレーションを表示します。次のパターンでは、個別のトレース図形が生成されます。

パターン	トレース図形
関数の連鎖	オーケストレータースパンの下で入れ子になっている複数のシーケンシャルアクティビティスパン。
ファンアウト/ファンイン	並列アクティビティスパンは、時間方向で重なり合っています。
人間との相互作用	外部イベントを長時間待機するオーケストレータースパン。
モニター	反復アクティビティは、イテレーションの間にタイマー待ちを伴って繰り返し実行されます。

Azure Monitor OpenTelemetry エクスポーターを使用して Application Insights にトレースを送信するように OTLP エクスポーターを構成するか、OTLP を介して Application Insights に転送する OpenTelemetry コレクターにエクスポートします。

Azure.Monitor.OpenTelemetry.Exporter NuGet パッケージをインストールし、OTLP エクスポーターを次のように置き換えます。

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

@azure/monitor-opentelemetry-exporter npm パッケージをインストールし、エクスポーターを構成します。

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

azure-monitor-opentelemetry-exporter pip パッケージをインストールして構成します。

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)

Java Azure Monitor OpenTelemetry エクスポーターを使用するか、Application Insights 接続文字列を使用して OpenTelemetry Java エージェントを構成します。

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

トレースデータに表示される内容

Durable Task SDK によって生成されるトレースデータには、次のものが含まれます。

スパンの種類	説明
`create_orchestration`	新しいオーケストレーションをスケジュール設定するときに出力されるクライアント側のスパン
`orchestration`	完全な実行ライフサイクルをカバーするサーバー側オーケストレーションスパン
`activity:<name>`	タイミングと結果を示す各アクティビティ呼び出しのスパン
`sub_orchestration:<name>`	各サブオーケストレーション呼び出しのスパン
`timer`	永続タイマーの待機に対応するスパン

各スパンには、 durabletask.type、 durabletask.task.name、 durabletask.task.instance_id、 durabletask.task.task_idなどの属性が含まれます。失敗したアクティビティとオーケストレーションは、スパンの状態やイベントの中で、エラーの詳細を保持しています。

Troubleshooting

問題点	Resolution
痕跡が表示されない	`Microsoft.DurableTask` アクティビティソースが登録され、エクスポーターエンドポイントに到達可能であることを確認します。
トレースが不完全です	Durable Task SDK (特に JavaScript/TypeScript) の前に OpenTelemetry SDK が初期化されていることを確認します。
Application Insights の中で不足しているスパン	トレースデータが削除されないように、サンプリング設定を無効または調整します。
トレースは一致しません	バックエンドとして Durable Task Scheduler を使用していることを確認します。トレースコンテキストの伝達にはスケジューラが必要です。

サンプルコード

Durable Functionsの分散トレース V2 サンプル (C#)

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-05