
AWS Lambda durable functions の OpenTelemetry サポートを試してみた
はじめに
2026年11月19日に、AWS Lambda durable functions の OpenTelemetry サポートが発表されました。
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 プラグインの仕様は次のドキュメントにあります。
依存パッケージ
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 ではありません。
AWS Compute Blog の記事は次です。
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」にあります。
まとめ
Lambda durable functions の OpenTelemetry プラグインを使うと、複数回の invocation に分かれた実行が1つの trace ID にまとまりました。
このトレースから step の所要時間や retry を読み取れるため、ボトルネックや障害の原因の特定に役立つ可能性があります。今回のアップデートを評価してみることをおすすめします。









