AWS Lambda durable functions の OpenTelemetry サポートを試してみた

AWS Lambda durable functions の OpenTelemetry サポートを試してみた

OpenTelemetry プラグインにより、複数回の invocation に分かれる durable execution が、1つの trace ID にまとまります。step の所要時間や retry を1本のトレースで追えるため、ボトルネックや障害の原因の特定に役立つ可能性があります。
2026.11.21

はじめに

2026年11月19日に、AWS Lambda durable functions の OpenTelemetry サポートが発表されました。

https://aws.amazon.com/about-aws/whats-new/2026/11/lambda-durable-otel/

OpenTelemetry プラグインを使うと、step、wait、callback、chained invoke を含む durable execution 全体が1本のトレースとして出力されます。この記事では Python SDK を使い、CloudWatch Logs の aws/spans に出る span の構造を確かめます。execution view と invocation view も比べます。

検証環境

  • リージョン:東京(ap-northeast-1)
  • ランタイム:Python 3.13(x86_64)
  • aws-durable-execution-sdk-python:3.0.2
  • aws-durable-execution-sdk-python-otel:2.1.0
  • ADOT レイヤー:AWSOpenTelemetryDistroPython 30
  • トレース:Active tracing
  • Transaction Search:有効(検証前から)
  • X-Ray トレースセグメントの送り先:CloudWatchLogs
  • X-Ray のインデックスのルール:Default(サンプリング 1%)
  • AWS CLI:2.41.2
  • SAM CLI:1.174.0

プラグイン 2.1.0 は core SDK に >=3.0.0,<4 を要求します。core SDK のバージョンを固定しなかったときは、pip が 3.1.0 をインストールしました。この記事では 3.0.2 に固定しています。

設定

OpenTelemetry プラグインの仕様は次のドキュメントにあります。

https://docs.aws.amazon.com/durable-execution/sdk-reference/observability/opentelemetry/

依存パッケージ

requirements.txt に、プラグインを core SDK と並べて書きます。

aws-durable-execution-sdk-python==3.0.2
aws-durable-execution-sdk-python-otel==2.1.0

テンプレート

ADOT で X-Ray へ出力する構成として、ドキュメントは Active tracing の有効化と、実行ロールへの AWSXRayDaemonWriteAccess の付与を示しています。template.yaml は次のとおりです。

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Lambda durable functions OpenTelemetry plugin verification

Globals:
  Function:
    Runtime: python3.13
    Architectures:
      - x86_64
    MemorySize: 512
    Timeout: 60
    Tracing: Active
    Layers:
      - arn:aws:lambda:ap-northeast-1:615299751070:layer:AWSOpenTelemetryDistroPython:30
    Environment:
      Variables:
        AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-instrument

Resources:
  ChildFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: otel-demo-child
      CodeUri: src/
      Handler: child.handler
      AutoPublishAlias: live
      DurableConfig:
        ExecutionTimeout: 900
        RetentionPeriodInDays: 1
      Policies:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
        - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess

  MainFunction:
    Type: AWS::Serverless::Function
    Properties:
      FunctionName: otel-demo-main
      CodeUri: src/
      Handler: main.handler
      AutoPublishAlias: live
      DurableConfig:
        ExecutionTimeout: 900
        RetentionPeriodInDays: 1
      Environment:
        Variables:
          CHILD_FUNCTION: !Ref ChildFunction.Alias
      Policies:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicDurableExecutionRolePolicy
        - arn:aws:iam::aws:policy/AWSXRayDaemonWriteAccess
        - LambdaInvokePolicy:
            FunctionName: !Ref ChildFunction

ADOT レイヤーのバージョンはリージョンごとに異なります。AWS Compute Blog の例は us-east-1 のバージョン 33 で、東京は 30 です。自分のリージョンの ARN は次の一覧で確認できます。ARN にある 615299751070 は、公開されている ADOT レイヤーの提供元のアカウント ID で、利用者のアカウント ID ではありません。

https://aws-otel.github.io/docs/getting-started/lambda

AWS Compute Blog の記事は次です。

https://aws.amazon.com/blogs/compute/aws-lambda-durable-functions-observability-with-opentelemetry/

sam build の後に、次のコマンドでデプロイします。

sam deploy --stack-name otel-demo --region ap-northeast-1 --resolve-s3 --capabilities CAPABILITY_IAM

関数コード

親関数の main.py は、step、retry、wait、callback、chained invoke を1本の流れに並べたものです。プラグインは plugins=[create_otel_plugin_factory()] でハンドラーに登録します。各操作の span 名には、コードで name= に渡した値が使われます。試行ごとの span(Attempt span)の名前には、attempt 1 のような接尾辞が付きます。

import json
import os

from aws_durable_execution_sdk_python import (
    DurableContext,
    durable_execution,
    durable_step,
)
from aws_durable_execution_sdk_python.config import Duration
from aws_durable_execution_sdk_python.types import WaitForCallbackContext
from aws_durable_execution_sdk_python_otel import create_otel_plugin_factory

@durable_step
def extract_text(step_context, doc_id):
    step_context.logger.info(f"Extracting text from document: {doc_id}")
    return {"doc_id": doc_id, "text": "extracted content"}

@durable_step
def summarize(step_context, extracted):
    # 1回目の試行だけ失敗させて、retry が Attempt span としてどう見えるかを確認する
    step_context.logger.info(f"Summarizing document (attempt {step_context.attempt})")
    if step_context.attempt == 1:
        raise RuntimeError("temporary failure on first attempt")
    return {"summary": "Document summary here"}

@durable_step
def publish(step_context, summary, approval, child_result):
    step_context.logger.info(f"Publishing with approval from: {approval.get('reviewer')}")
    return {"status": "published", "child": child_result}

@durable_execution(plugins=[create_otel_plugin_factory()])
def handler(event: dict, context: DurableContext) -> dict:
    extracted = context.step(extract_text(event["doc_id"]), name="extract-text")
    summary = context.step(summarize(extracted), name="summarize")

    context.wait(Duration.from_seconds(10), name="cooldown")

    def submit_for_review(callback_id: str, ctx: WaitForCallbackContext) -> None:
        ctx.logger.info(f"CALLBACK_ID={callback_id}")

    approval = context.wait_for_callback(submitter=submit_for_review, name="human-review")
    if isinstance(approval, str):
        approval = json.loads(approval)

    child_result = context.invoke(
        os.environ["CHILD_FUNCTION"], {"doc_id": event["doc_id"]}, name="call-child"
    )
    return context.step(publish(summary, approval, child_result), name="publish")

context.invoke で呼ぶ別の durable 関数 child.py にも、同じ方法でプラグインを登録しました。

from aws_durable_execution_sdk_python import DurableContext, durable_execution
from aws_durable_execution_sdk_python_otel import create_otel_plugin_factory

@durable_execution(plugins=[create_otel_plugin_factory()])
def handler(event: dict, context: DurableContext) -> dict:
    return context.step(lambda ctx: {"child": "done", "doc_id": event["doc_id"]}, name="child-work")

トレースの取得

実行

この関数は wait_for_callback を使うため、非同期で起動します。応答の DurableExecutionArn が、後で実行の trace ID を引くときのキーになります。

aws lambda invoke --function-name otel-demo-main --qualifier live --invocation-type Event --region ap-northeast-1 --cli-binary-format raw-in-base64-out --payload '{"doc_id": "test-doc-001"}' /tmp/otel-resp.json
{
    "StatusCode": 202,
    "DurableExecutionArn": "arn:aws:lambda:ap-northeast-1:123456789012:function:otel-demo-main:1/durable-execution/<実行名>/<実行ID>"
}

実行は human-review の callback を受け取るまで待機します。callback ID は、起動の約18秒後(step の retry の待ちと 10秒の wait の後)に、ログの message へ CALLBACK_ID=<値> の形で出ます。

aws logs filter-log-events --log-group-name /aws/lambda/otel-demo-main --region ap-northeast-1 --filter-pattern CALLBACK_ID --start-time $(( ($(date +%s) - 600) * 1000 )) --query "events[].message" --output text

取得した callback ID を使って、実行のタイムアウト(この検証では 900秒)の前に結果を送ります。callback ID は / を含む Base64 文字列です。/ の位置で区切らず、全体をそのまま渡します。

aws lambda send-durable-execution-callback-success --cli-binary-format raw-in-base64-out --callback-id <callback-id> --region ap-northeast-1 --result '{"approved": true, "reviewer": "alice"}'

aws/spans からの取得

実行の TraceHeader は get-durable-execution で取れます。

aws lambda get-durable-execution --durable-execution-arn <DurableExecutionArn> --region ap-northeast-1 --output json
"TraceHeader": {
    "XAmznTraceId": "Root=1-<8桁>-<24桁>;Parent=<親ID>;Sampled=1"
}

Root の値から先頭の 1- を除き、残りの8桁と24桁をつないだ32桁の値が aws/spans の traceId になります。この検証でも両者は一致しました。

span は filter-log-events で取り出せます。

aws logs filter-log-events --log-group-name aws/spans --region ap-northeast-1 \
  --filter-pattern '"<traceId>"' --start-time <開始のエポックミリ秒> --output json

Logs Insights では、次のクエリで span の種類、attempt、outcome、所要時間(ミリ秒)を並べました。execution ARN に otel-demo-main を含む span に絞っています。

aws logs start-query --log-group-name aws/spans --region ap-northeast-1 \
  --start-time <開始のエポック秒> --end-time <終了のエポック秒> \
  --query-string "fields name, attributes.durable.operation.type as type, attributes.durable.attempt.number as attempt, attributes.durable.attempt.outcome as outcome, durationNano/1000000 as ms | filter traceId = '<traceId>' and attributes.durable.execution.arn like /otel-demo-main/ | sort startTimeUnixNano asc | limit 50" \
  --output json

start-query が返す queryId を get-query-results に渡します。結果が揃うのは status が Complete になってからです。

aws logs get-query-results --query-id <queryId> --region ap-northeast-1 --output json

取得したトレース

1本のトレースに入る範囲

取得した span には、durable の span のほかに、Lambda が Active tracing で出す otel-demo-main/LambdaService などの span と、ADOT が出す main.handler の span が入ります。親子関係を追いやすくするため、span をツリー表示するスクリプトを用意しました。--durable-only を付けると、Lambda と ADOT が出す span を除いて durable の span だけを表示します。各行は span 名、操作の種類、attempt と outcome、status、トレースの先頭の span からの開始時刻(+)、所要時間、関数名の順です。

span_tree.py
# 使い方: python3 span_tree.py spans.json --durable-only
import json
import sys
from collections import defaultdict

path = sys.argv[1]
durable_only = "--durable-only" in sys.argv

text = open(path).read()
events = json.loads(text[text.index("{"): text.rindex("}") + 1])["events"]

spans = {}
for e in events:
    m = json.loads(e["message"])
    key = m["spanId"]
    # 同じ spanId が部分的に2回出力されるものは、所要時間が長いほうを採用する
    if key not in spans or m.get("durationNano", 0) > spans[key].get("durationNano", 0):
        spans[key] = m

t0 = min(m["startTimeUnixNano"] for m in spans.values())
children = defaultdict(list)
roots = []
for m in spans.values():
    p = m.get("parentSpanId")
    if p in spans:
        children[p].append(m)
    else:
        roots.append(m)

def label(m):
    a = m.get("attributes", {})
    parts = [m["name"]]
    if "durable.operation.type" in a:
        parts.append(f"[{a['durable.operation.type']}]")
    if "durable.attempt.number" in a:
        parts.append(f"attempt={a['durable.attempt.number']} outcome={a.get('durable.attempt.outcome')}")
    if "durable.operation.status" in a:
        parts.append(f"status={a['durable.operation.status']}")
    if "durable.execution.status" in a:
        parts.append(f"execution.status={a['durable.execution.status']}")
    if "durable.invocation.status" in a:
        parts.append(f"invocation.status={a['durable.invocation.status']}")
    if "durable.invocation.first" in a:
        parts.append(f"first={a['durable.invocation.first']}")
    if m.get("status", {}).get("code") == "ERROR":
        parts.append("ERROR")
    return " ".join(parts)

def is_durable(m):
    return any(k.startswith("durable.") for k in m.get("attributes", {})) or m["name"] in ("Workflow", "Invocation")

def show(m, depth):
    start = (m["startTimeUnixNano"] - t0) / 1e9
    dur = m.get("durationNano", 0) / 1e9
    if not durable_only or is_durable(m):
        print(f"{'  ' * depth}{label(m)}  +{start:.3f}s  {dur:.3f}s  ({m.get('resource', {}).get('attributes', {}).get('service.name', '-')})")
        depth += 1
    for c in sorted(children[m["spanId"]], key=lambda x: x["startTimeUnixNano"]):
        show(c, depth)

for r in sorted(roots, key=lambda x: x["startTimeUnixNano"]):
    show(r, 0)

print()
print(f"spans={len(spans)} trace_ids={sorted({m['traceId'] for m in spans.values()})}")

filter-log-events の出力を spans.json に保存して実行します。

python3 span_tree.py spans.json --durable-only
Invocation invocation.status=PENDING first=True  +2.648s  0.271s  (otel-demo-main)
Invocation invocation.status=PENDING first=False  +7.883s  0.214s  (otel-demo-main)
Invocation invocation.status=PENDING first=False  +18.050s  0.187s  (otel-demo-main)
Invocation invocation.status=PENDING first=False  +153.129s  0.275s  (otel-demo-main)
Workflow execution.status=SUCCEEDED  +0.089s  156.202s  (otel-demo-main)
  extract-text [STEP] attempt=1 outcome=None status=SUCCEEDED  +2.649s  0.096s  (otel-demo-main)
    extract-text attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +2.649s  0.001s  (otel-demo-main)
  summarize [STEP] attempt=2 outcome=None status=SUCCEEDED  +2.806s  5.125s  (otel-demo-main)
    summarize attempt 1 [STEP] attempt=1 outcome=FAILED ERROR  +2.771s  0.001s  (otel-demo-main)
    summarize attempt 2 [STEP] attempt=2 outcome=SUCCEEDED  +7.884s  0.000s  (otel-demo-main)
  cooldown [WAIT] status=SUCCEEDED  +7.984s  10.000s  (otel-demo-main)
  human-review [CONTEXT] status=SUCCEEDED  +18.075s  135.080s  (otel-demo-main)
    human-review create callback id [CALLBACK] status=SUCCEEDED  +18.075s  134.970s  (otel-demo-main)
    human-review submitter [STEP] attempt=1 outcome=None status=SUCCEEDED  +18.089s  0.028s  (otel-demo-main)
      human-review submitter attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +18.089s  0.001s  (otel-demo-main)
  call-child [CHAINED_INVOKE] status=SUCCEEDED  +153.266s  2.810s  (otel-demo-main)
    Workflow execution.status=SUCCEEDED  +153.304s  2.751s  (otel-demo-child)
      child-work [STEP] attempt=1 outcome=None status=SUCCEEDED  +155.825s  0.110s  (otel-demo-child)
        child-work attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +155.825s  0.000s  (otel-demo-child)
    Invocation invocation.status=SUCCEEDED first=True  +155.824s  0.230s  (otel-demo-child)
  publish [STEP] attempt=1 outcome=None status=SUCCEEDED  +156.148s  0.021s  (otel-demo-main)
    publish attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +156.148s  0.000s  (otel-demo-main)
Invocation invocation.status=SUCCEEDED first=False  +156.147s  0.144s  (otel-demo-main)

親関数の1回の実行は Lambda の invocation 5回に分かれ、5回分の span が1つの trace ID に入りました。invocation は、step の retry の待ち、10秒の wait、callback の待ち、chained invoke の完了待ちの4か所で区切られます。子関数 child.py の Workflow、Invocation、step の span も同じ trace ID に入り、親の call-child span の下に並びます。

既定の execution view では、操作の span は Workflow の子です。Invocation span は Workflow の子ではなく、ADOT が出す main.handler の span の下に並びます。Workflow は最後の invocation の otel-demo-main/LambdaExecutionEnvironment の下に出ます。操作の span は、その操作を export した invocation の span へのリンクを持ちます。

ログからもトレースへ辿れます。JSON ログには traceId、spanId、otelTraceSampled が入り、traceId は aws/spans の trace ID と一致しました。

retry と所要時間

summarize の1回目の試行は、コードの例外で失敗します。Attempt span の summarize attempt 1 は durable.attempt.outcome=FAILED、OTel の status は ERROR です。この span の exception イベントには、例外の型とメッセージが入ります。

この実行の summarize の step の span は 5.125秒で、1回目の失敗の直後から2回目の成功までの区間です。step に retry 戦略を指定していないため、retry は既定の動作です。この実行では retry までの待ちが約5秒でした。step 全体の所要時間は step の span から、1回ごとの試行の長さは Attempt span から読み取れます。

step の retry を待って終わった1回目の invocation も、wait、callback、chained invoke の待ちで終わった invocation も、durable.invocation.status が PENDING で、OTel の status は OK でした。

環境変数での登録とビュー

登録の設定

プラグインは、コードに plugins= を書く代わりに、環境変数 DURABLE_EXECUTION_PLUGINS で登録することもできます。値が otel なら execution view、otel-invocation なら invocation view になります。

ビューを比べるため、EnvExecFunction(otel-demo-env-exec)と EnvInvFunction(otel-demo-env-inv)の2関数を追加しました。どちらも親関数と同じ CodeUri: src/ と Globals を使います。親関数との違いは、関数名、環境変数、Handler が minimal.handler であることの3点です。

EnvExecFunction には、次の環境変数を設定します。

      Environment:
        Variables:
          DURABLE_EXECUTION_PLUGINS: otel

EnvInvFunction では、値を otel-invocation にします。

      Environment:
        Variables:
          DURABLE_EXECUTION_PLUGINS: otel-invocation

ハンドラーは、@durable_execution だけを付けた minimal.py です。

from aws_durable_execution_sdk_python import DurableContext, durable_execution
from aws_durable_execution_sdk_python.config import Duration

# プラグインはコードに書かない。環境変数 DURABLE_EXECUTION_PLUGINS で登録する。
@durable_execution
def handler(event: dict, context: DurableContext) -> str:
    data = context.step(lambda ctx: event["id"], name="fetch-data")
    context.wait(Duration.from_seconds(5), name="cooldown")
    return context.step(lambda ctx: f"processed {data}", name="process")

どちらの関数にも、id を含む JSON を payload として渡します。次は EnvExecFunction の起動例です。

aws lambda invoke --function-name otel-demo-env-exec --qualifier live --invocation-type Event --region ap-northeast-1 --cli-binary-format raw-in-base64-out --payload '{"id": "abc"}' /tmp/otel-resp-exec.json

ビューごとのトレース

同じ minimal.py を2つのビューで動かし、span のツリーを比べました。execution view(otel)は次のとおりです。

Invocation invocation.status=PENDING first=True  +2.744s  0.238s  (otel-demo-env-exec)
Workflow execution.status=SUCCEEDED  +0.082s  8.001s  (otel-demo-env-exec)
  fetch-data [STEP] attempt=1 outcome=None status=SUCCEEDED  +2.745s  0.090s  (otel-demo-env-exec)
    fetch-data attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +2.745s  0.000s  (otel-demo-env-exec)
  cooldown [WAIT] status=SUCCEEDED  +2.871s  5.000s  (otel-demo-env-exec)
  process [STEP] attempt=1 outcome=None status=SUCCEEDED  +7.929s  0.036s  (otel-demo-env-exec)
    process attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +7.929s  0.000s  (otel-demo-env-exec)
Invocation invocation.status=SUCCEEDED first=False  +7.928s  0.155s  (otel-demo-env-exec)

invocation view(otel-invocation)は次のとおりです。

Invocation invocation.status=PENDING first=True  +2.609s  0.276s  (otel-demo-env-inv)
  fetch-data [STEP] attempt=1 outcome=None status=SUCCEEDED  +2.610s  0.103s  (otel-demo-env-inv)
    fetch-data attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +2.610s  0.000s  (otel-demo-env-inv)
  cooldown [WAIT] status=STARTED  +2.739s  0.146s  (otel-demo-env-inv)
Workflow execution.status=SUCCEEDED  +0.078s  7.959s  (otel-demo-env-inv)
Invocation invocation.status=SUCCEEDED first=False  +7.840s  0.196s  (otel-demo-env-inv)
  cooldown [WAIT] status=SUCCEEDED  +7.841s  0.000s  (otel-demo-env-inv)
  process [STEP] attempt=1 outcome=None status=SUCCEEDED  +7.841s  0.074s  (otel-demo-env-inv)
    process attempt 1 [STEP] attempt=1 outcome=SUCCEEDED  +7.841s  0.000s  (otel-demo-env-inv)

cooldown の span は、execution view では5秒の1本です。invocation view では、1回目の Invocation span の下の STARTED と、2回目の Invocation span の下の SUCCEEDED の2本に分かれます。また invocation view では、操作の span の親が Workflow ではなく、その操作を実行した Invocation になります。

どちらのビューを選ぶかの目安は、ドキュメントの「Choosing a view」にあります。

https://docs.aws.amazon.com/durable-execution/sdk-reference/observability/opentelemetry/

まとめ

Lambda durable functions の OpenTelemetry プラグインを使うと、複数回の invocation に分かれた実行が1つの trace ID にまとまりました。

このトレースから step の所要時間や retry を読み取れるため、ボトルネックや障害の原因の特定に役立つ可能性があります。今回のアップデートを評価してみることをおすすめします。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事