“使用 Durable Execution Telemetry Exporter 观测 AWS Lambda 持久函数”。 https://t.co/3i6d9iU6Jy

使用 Durable Execution Telemetry Exporter 观测 AWS Lambda 持久函数 | Amazon Web Services

来源：https://aws.amazon.com/de/blogs/compute/observing-aws-lambda-durable-functions-with-the-durable-execution-telemetry-exporter/ 持久函数是一种 AWS Lambda 函数，可能运行数分钟、数天，甚至长达一年。你可以使用 Durable Execution SDK (https://docs.aws.amazon.com/durable-execution/) 构建这些函数，该 SDK 提供步骤、等待和并行等操作。一次持久执行可能分布在多次 Lambda 调用中，调用之间还会发生等待和重试。因此，观测由多次调用组成的持久执行需要不同的工具。你想回答的问题通常不是“这次调用做了什么？”，而是“我的持久执行进行到了哪一步，哪个步骤失败了，重试了多少次，整个过程花了多长时间？”

运行数千次执行后，问题的范围会从单次执行扩展到所有执行。有些问题与运维有关。哪个步骤最常失败，出现了什么错误？哪个步骤导致的重试最多？上周部署后，某个步骤是否变慢了？另一些问题则与工作流承载的业务有关。昨晚的付款失败影响了哪些客户？每个人工审批步骤需要多长时间？在已启动的订单中，有多少进入了付款步骤，其余订单停在了哪里？回答这些问题需要每次执行的遥测数据，其中包含状态、时间、步骤，以及你选择输出的输入和输出字段等相关数据。

传统的 Lambda 可观测性适用于单次调用。Lambda 为每次调用写入一个日志流，因此，暂停四次的持久执行会写入四个独立的日志流，并与其他所有并发执行的日志交错。Amazon CloudWatch 指标可以告诉你函数的错误率，却无法指出工作流中的哪个步骤导致了错误。AWS X-Ray 或 OpenTelemetry 等分布式追踪工具可以展示一次执行的时间信息。它们并非为回答跨多次执行的问题而设计，例如本周哪个步骤失败最频繁。为此，你需要为每次执行保留一条可查询的记录。

今天，我们推出 Durable Execution Telemetry Exporter (https://docs.aws.amazon.com/durable-execution/sdk-reference/observability/telemetry/)，这是一个适用于 AWS Lambda 持久函数的可观测性插件。我们还推出了 Durable Execution Telemetry MCP 服务器，这是一个模型上下文协议 (MCP) 服务器，可让 AI 编程代理查询遥测数据。该导出器支持 TypeScript、Python、Java 和 Go，并在各语言的 Durable Execution SDK 代码仓库中开源。AWS 在 aws-durable-execution-sdk-js (https://github.com/aws/aws-durable-execution-sdk-js/blob/main/packages/aws-durable-execution-sdk-js-telemetry-mcp/README.md) 代码仓库中提供开源 MCP 服务器。

只需修改一行配置，即可获得每次执行的记录，涵盖每个步骤、等待、回调和调用，包括时间、重试次数、状态和错误。导出器会将记录发送到你选择的目标。无需编写自定义插桩代码，也无需运行单独的代理。

持久执行遥测导出器的工作原理

Durable Execution Telemetry Exporter 是持久执行 SDK 的一个插件。它在 Lambda 函数内部运行，与处理程序处于同一进程，并订阅 SDK 的插桩生命周期。它不在请求处理路径中运行。

每次调用持久执行时，插件都会构建该执行的累积快照，而不是增量视图或单次调用视图。由于持久执行 SDK 会在每次恢复时从头重放处理程序，并将检查点保存的状态传递给插件，因此插件可以从任意一次调用中重建截至当前的整个执行过程。该快照是一个名为 DurableExecutionTelemetryRecord 的 JSON 文档：

{ "recordType": "DurableExecutionTelemetry", "schemaVersion": "1.0", "executionArn": "arn:aws:lambda:us-east-1:111122223333:function:order-processor:$LATEST/durable-execution/abc123/inv456", "executionName": "abc123", "functionName": "order-processor", "status": "SUCCEEDED", "startTime": "2026-06-16T17:00:22.100Z", "endTime": "2026-06-16T17:00:27.514Z", "durationMs": 5414, "input": { "orderId": "order-12345", "customerId": "cust-789" }, "output": { "orderId": "order-12345", "status": "completed", "charged": 99.99 }, "operations": [ { "name": "validate-order", "type": "STEP", "status": "SUCCEEDED", "durationMs": 250 }, { "name": "check-inventory", "type": "STEP", "status": "SUCCEEDED", "durationMs": 350 }, { "name": "cool-down", "type": "WAIT", "status": "SUCCEEDED", "durationMs": 5000 }, { "name": "charge-payment", "type": "STEP", "status": "SUCCEEDED", "durationMs": 80 } ] }

每条记录本身都是完整的。表中的一行对应一次持久执行，这意味着你提出的问题 (最慢的步骤、重试次数最多的步骤、付款步骤后失败的执行) 都可以通过普通查询回答，无需跨日志流关联日志。

入门

将插件与持久执行 SDK 一起安装：

npm install @aws/durable-execution-sdk-js-telemetry-exporter

然后将其传递给 withDurableExecution：

`` import { DurableContext, withDurableExecution } from “@aws/durable-execution-sdk-js”; import { durableExecutionTelemetry } from “@aws/durable-execution-sdk-js-telemetry-exporter”;

const handler = async (event: OrderEvent, context: DurableContext) => { const order = await context.step(“validate-order”, async () => validateOrder(event.orderId), );

const inventory = await context.step(“check-inventory”, async () => reserveInventory(order), );

await context.wait({ seconds: 30 });

return await context.step(“charge-payment”, async () => chargeCustomer(order, inventory), ); };

export const lambdaHandler = withDurableExecution(handler, { plugins: [durableExecutionTelemetry({})], }); ``

以上就是全部集成工作。在不进行任何配置的情况下，默认的 LambdaLogExporter 会将记录以 JSON 格式写入函数自身的 CloudWatch 日志组。你无需创建任何基础设施，也无需授予额外的 AWS Identity and Access Management (IAM) 权限，因为函数本来就会写入自己的日志。你可以立即使用 Amazon CloudWatch Logs Insights 查询结果：

fields executionName, status, durationMs | filter recordType = "DurableExecutionTelemetry" and status = "FAILED" | sort durationMs desc

选择记录的发送目标

插件包含 13 种目标导出器，方便你将记录发送到有用的位置：

目标导出器适用场景函数自身的日志组 LambdaLogExporter 快速入门，无需设置任意 CloudWatch 日志组 CloudWatchLogsExporter 跨函数集中管理记录Amazon Simple Storage Service (Amazon S3) S3Exporter Amazon Athena SQL、长期保留Amazon DynamoDB DynamoDBExporter 按执行快速查找、实时仪表板Amazon Aurora AuroraExporter 将工作流数据与业务数据关联Amazon Redshift RedshiftExporter 大规模跨函数分析Amazon OpenSearch Service OpenSearchExporter 全文搜索、仪表板Amazon EventBridge EventBridgeExporter 失败时告警和修复Amazon Data Firehose FirehoseExporter 扇出到 S3、Splunk 或第三方Amazon Simple Queue Service (Amazon SQS) SQSExporter 解耦的下游处理任意 OTLP 端点 OTelExporter 第三方可观测性平台任意 HTTPS 端点 HttpExporter 自定义后端和 Webhook文件系统或 Amazon Elastic File System (Amazon EFS) FileExporter 本地开发、EFS 持久化插件会并行向所有已配置的导出器发送记录。这让你可以根据不同存储的特点路由数据，例如使用快速存储进行实时查找，使用成本更低、容量更大的存储进行长期保存：

`` import { durableExecutionTelemetry, S3Exporter, DynamoDBExporter, EventBridgeExporter, } from “@aws/durable-execution-sdk-js-telemetry-exporter”;

const telemetry = durableExecutionTelemetry({ emitMode: “on-complete”, samplingRate: 1.0, exporters: [ new S3Exporter({ bucket: string }), // 使用你拥有的有效存储桶名称 new DynamoDBExporter({ tableName: “durable-execution-telemetry-live” }), new EventBridgeExporter({}), ], }); ``

使用 S3 导出器时，插件会将记录写入 Hive 风格的分区 (year=YYYY/month=MM/day=DD/)，AWS Glue 爬网程序会自动发现这些分区，因此 Athena 查询无需额外建模即可运行：

SELECT op.name, COUNT(*) AS failures, AVG(op.durationms) AS avg_ms FROM durable_execution_telemetry CROSS JOIN UNNEST(operations) AS t(op) WHERE status = 'FAILED' AND year = '2026' AND month = '06' GROUP BY op.name ORDER BY failures DESC;

控制频率和内容

三个设置决定了生产部署的成本和对外暴露的内容。

emitMode 决定插件何时发送记录。默认值 on\-complete 会在执行进入 SUCCEEDED 或 FAILED 状态时发送一次记录。如果只关注错误，可使用 on\-failure 将开销降至最低；如果希望近乎实时地观察执行进度，则使用 on\-change。

samplingRate 用于降低发送频率。插件根据执行 ARN 的哈希值做出采样决策。执行 ARN 在重放过程中保持不变，因此采样决策是确定性的：被采样选中的执行会发送其全部记录，未被选中的执行则不发送任何记录。你永远不会收到只记录了一半的工作流。

content 控制哪些内容可以离开函数。默认情况下，插件会原样包含执行的输入和输出，这在开发中很方便，但在生产环境中通常不可接受。可以传入转换函数以脱敏：

const telemetry = durableExecutionTelemetry({ samplingRate: 0.1, content: { input: (event) => ({ orderId: event.orderId }), output: (result) => ({ status: result.status }), }, });

各目标支持的载荷大小不同：CloudWatch Logs 事件为 256 KB，DynamoDB 项目为 400 KB。每个导出器都有一个 maxRecordSizeBytes，当记录超出该限制时，插件会仅针对该目标截断记录，而不影响其他目标：先截断操作结果，再按从旧到新的顺序删除整个操作，最后才截断执行的输入和输出。插件绝不会丢弃标识和时间线字段，并会将裁剪后的记录标记为 truncated: true，因此始终可以区分截断记录和完整记录。我们建议使用 content 转换函数有意识地限制载荷大小，而不是依赖截断。

通过 AI 代理查询执行历史

要回答“昨晚的批处理为什么失败”，需要知道你配置了哪个数据存储、它使用哪种查询方言，以及记录的架构是什么样的。DynamoDB PartiQL、Athena 的 Trino SQL、Aurora PostgreSQL、Amazon Redshift、OpenSearch 和 CloudWatch Logs Insights 各不相同。

Durable Execution Telemetry MCP 服务器消除了这一要求。它是一个本地 stdio 服务器，可将你配置的目标提供给任何支持 MCP 的代理，包括 Kiro、Claude Code 和 Cursor。使用一条命令即可添加：

kiro-cli mcp add \ --name durable-telemetry \ --command npx \ --args "-y,@aws/durable-execution-sdk-js-telemetry-mcp" \ --env DURABLE_TELEMETRY_DESTINATION_TYPE=dynamodb \ --env DURABLE_TELEMETRY_DYNAMODB_TABLE_NAME=durable-execution-telemetry-live \ --env DURABLE_TELEMETRY_REGION=us-east-1 \ --scope workspace

配置完全通过环境变量完成，凭证来自标准 AWS SDK 提供程序链，因此无需状态文件，也无需单独配置密钥。该服务器提供五个工具：

• test\_destination 运行只读连接检查。如果缺少必需的变量，它会指出确切的变量名称，并在不发起任何 AWS 调用的情况下返回。
• describe\_schema 返回当前所配置目标的记录架构、查询方言和行数上限。代理应在编写查询之前调用它。
• list\_executions 按状态、函数名称和时间范围进行筛选，无需使用查询语言。这可以处理大多数问题。
• get\_execution 根据执行 ARN 获取一条记录。
• query 处理筛选条件无法表达的问题。

你提出问题，代理选择工具：

过去 24 小时内，order-processor 中哪些步骤失败最频繁，平均重试次数是多少？

对于 SQL 目标，请将每个查询写成 SELECT 语句，或以 SELECT 结尾的 WITH 语句。这是服务器唯一会执行的两种形式。服务器会在发起任何 AWS 调用之前检查查询，因此会修改数据的语句绝不会到达你的目标。对于 CloudWatch Logs 目标，Logs Insights 查询语言中没有写入数据的语句。因此，通过该服务器执行的所有查询都是只读的。

最佳实践与注意事项

**有意识地选择 operationDetail。**默认值 top\-level 仅记录顶层操作，无论何时发送记录，都会生成相同的一组操作。full\-tree 包含映射项和并行分支等上下文的子操作，但默认情况下，持久执行后端会从传递给后续调用的状态中裁剪已完成上下文的子操作。要在暂停和恢复后保留完整的树，还需在 withDurableExecution 上设置 pluginsConfig\.childOperationsDepth。这种保留会产生成本：它会在恢复时强制对每个保留的上下文执行一次重放，因此只应启用所需的深度。

**选择目标能够查询的操作名称。**插件会原样使用名称作为键和标识符，绝不会对其进行清理。名称中的 \. 在 CloudWatch Logs Insights 和 OpenSearch 中是字段路径分隔符。字母、数字、\- 和 \_ 在所有目标中都具有可移植性。

**了解插件无法看到的内容。**Durable Execution Telemetry Exporter 在函数内部运行，因此只有函数被调用时才能发送记录。由 Lambda 服务产生、且未触发调用的终止状态永远不会到达插件：手动停止产生的 STOPPED，以及超过执行超时限制时产生的 TIMED\_OUT。要覆盖完整生命周期，请在默认的 Amazon EventBridge 总线上订阅 Lambda 持久执行生命周期事件，并通过一个小型处理程序更新目标：

{ "source": ["aws.lambda"], "detail-type": ["Lambda Durable Execution State Change"], "detail": { "status": ["STOPPED", "TIMED_OUT"] } }

**考虑目标的成本。**插件每次发送记录时最多增加一次导出操作，因为对于积压的更新，它只发送最新的一条。每条记录都是完整快照，最新快照会取代之前的所有快照。如果更新的到达速度超过导出器的处理能力，插件会丢弃中间快照。需要关注的是目标产生的费用：CloudWatch Logs 摄取、DynamoDB 写入、Aurora 容量等。结合使用 samplingRate 和 emitMode 来控制这些费用。

结论

Durable Execution Telemetry Exporter 为 AWS Lambda 持久函数提供了一种与其运行方式相匹配的可观测性模型：每次执行对应一条完整记录，并发送到适合团队需求的目标。Durable Execution Telemetry MCP 服务器则让 AI 代理能够直接针对这些数据回答问题。

要开始使用持久函数，请参阅《AWS Lambda 开发人员指南》。有关插件的完整导出器参考、配置选项，以及可部署所有目标以供测试的 AWS Cloud Development Kit (AWS CDK) 堆栈，请参阅软件包 README (https://github.com/aws/aws-durable-execution-sdk-js/blob/main/packages/aws-durable-execution-sdk-js-telemetry-exporter/README.md)。

关于作者