Instrumenting AWS Lambda

状态: 开发中

本文档定义了在 instrumenting AWS Lambda 请求处理程序时如何应用语义约定。AWS Lambda 在很大程度上遵循 FaaS 的约定，而当处理程序是针对 HTTP 请求时，HTTP 约定也同样适用。

Lambda 函数有各种触发器，本文档将随着时间的推移不断更新以涵盖所有用例。

所有触发器

对于所有事件，除非下文另有说明，否则应创建与函数调用对应的 SERVER 类型的 span。

应设置以下属性

• faas.invocation_id - AWS 请求 ID 的值，始终可以通过 Lambda Context 上的访问器获取。
• cloud.account.id - 在某些语言中，这可以通过 Lambda Context 上的访问器获取。否则，可以从 ARN 中通过按 : 分割的第五个元素解析得到。

状态:

此 span 代表 AWS Lambda 调用。

请考虑设置 faas 资源和 跟踪约定以及 云资源约定的其他属性。

Span name 必须设置为 Lambda Context 中的函数名，除非下文另有说明。

Span kind 必须设置为 SERVER，除非下文另有说明。

**Span 状态**应遵循 记录错误文档。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
aws.lambda.invoked_arn		推荐	字符串	传递给函数的 Context 中提供的完整调用 ARN（适用于 /runtime/invocation/next 的 Lambda-Runtime-Invoked-Function-Arn 头）。[1]	arn:aws:lambda:us-east-1:123456:function:myfunction:myalias
aws.lambda.resource_mapping.id		推荐	字符串	AWS Lambda EventSourceMapping 的 UUID。事件源映射到 lambda 函数。Lambda 读取其内容并用于触发函数。这在 lambda 执行上下文或 lambda 运行时环境中不可用。当 UUID 存在时，AWS SDK 会为每种语言填充此项。其中一些操作是 Create/Delete/Get/List/Update EventSourceMapping。	587ad24b-03b9-4413-8202-bbd56b36e5b7

[1] aws.lambda.invoked_arn: 如果涉及别名，这可能与 cloud.resource_id 不同。

AWS X-Ray 活动跟踪注意事项

当为 Lambda 启用了 AWS X-Ray 活动跟踪时，运行时将根据配置的采样率自动生成 span，并通过 _X_AMZN_TRACE_ID 环境变量（以及 Java Lambda 函数的 com.amazonaws.xray.traceHeader 系统属性）传播 span 上下文。此 span 上下文使用 X-Ray Tracing Header Format 进行编码。

用户必须能够 配置传播器，以优先传播此 X-Ray“活动跟踪”span 上下文。（ FYI：用户可能希望启用此项，如果 OpenTelemetry 配置为向 AWS X-Ray 报告 span，以便其跟踪能够正确链接在一起。）

xray-lambda 传播器功能

包含 AWS Lambda instrumenting 的 SDK 应该提供一个额外的传播器，与 X-Ray 传播器并行，可以通过 OTEL_PROPAGATORS 环境变量设置为 xray-lambda 来 配置。此传播器有望替换 OTEL_PROPAGATORS 列表中的 xray 传播器。此传播器的行为在下面的伪代码中进行了描述。

extract(context, carrier) {
    xrayContext = xrayPropagator.extract(context, carrier)

    // To avoid potential issues when extracting with an active span context (such as with a span link),
    // the `xray-lambda` propagator SHOULD check if the provided context already has an active span context.
    // If found, the propagator SHOULD just return the extract result of the `xray` propagator.
    if (Span.fromContext(context).getSpanContext().isValid())
      return xrayContext

    // If xray-lambda environment variable not set, return the xray extract result.
    traceHeader = getEnvironment("_X_AMZN_TRACE_ID")
    if (isEmptyOrNull(traceHeader))
      return xrayContext

    // Apply the xray propagator using the span context contained in the xray-lambda environment variable.
    return xrayPropagator.extract(xrayContext, ["X-Amzn-Trace-Id": traceHeader])
}

注意： 如果 com.amazonaws.xray.traceHeader 键的系统属性不为空，Java 实现应使用该键的系统属性值而不是环境变量。

xray-lambda 传播器配置

当从 AWS Lambda 向 AWS X-Ray 报告 span 时，xray-lambda 传播器应替换 OTEL_PROPAGATORS 配置中的 xray 传播器。同时包含两者将导致 xray-lambda 无法正常工作。

向 AWS X-Ray 报告 span 时的有效配置示例

• OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda

无效配置示例

• OTEL_PROPAGATORS=tracecontext,baggage,xray,xray-lambda
• OTEL_PROPAGATORS=tracecontext,baggage,xray-lambda,xray

当 OpenTelemetry 向 AWS X-Ray 以外的系统报告跟踪时，用户不应使用 xray-lambda，否则报告的跟踪将会中断。

当 OpenTelemetry 向 AWS X-Ray 以外的系统报告跟踪时的有效配置示例

• OTEL_PROPAGATORS=tracecontext,baggage,xray

API Gateway

API Gateway 允许用户响应 HTTP 请求来触发 Lambda 函数。它可以配置为纯代理，将有关原始 HTTP 请求的信息传递给 Lambda 函数，或者配置为 REST API，在这种情况下只有反序列化的正文 payload 可用。如果 API Gateway 配置为代理到 Lambda 函数，则 instrumented 的请求处理程序将能够以 API Gateway Proxy Request Event 的形式访问有关 HTTP 请求的所有信息。

Lambda span 的名称和 http.route span 属性应设置为代理请求事件中的 资源属性，这对应于用户配置的 HTTP 路由，而不是函数名。

faas.trigger 必须设置为 http。 HTTP 属性应基于由代理请求启动的 Lambda 事件中的可用信息进行设置。http.scheme 可通过 Lambda 事件中的 x-forwarded-proto 头获取。有关更多详细信息，请参阅 输入事件格式。

SQS

Amazon Simple Queue Service (SQS) 是一个消息队列，它使用消息批次触发 Lambda 函数。因此，我们同时考虑处理批次和处理每个单独的消息。函数调用 span 必须对应于 SQS 事件，即消息批次。对于每条消息，都应创建一个额外的 span 来对应 SQS 消息的处理。由于消息处理将在用户业务逻辑中，而不是 Lambda 框架中，因此无需代码更改的自动 instrumenting 机制通常无法 instrument 单个消息的处理。Instrumenting 应提供用于在用户代码中创建消息处理 span 的实用程序。

两种 SQS span 的 span kind 都应为 CONSUMER。

SQS 事件

对于 SQS 事件 span，如果事件中的所有消息都具有相同的事件源，则 span 的名称必须是 <event source> process。如果批次中有多个源，则名称必须是 multiple_sources process。父 span 应该是与函数调用对应的 SERVER span。

对于事件中的每条消息，应检查 消息系统属性（不是用户提供的消息属性）是否包含键 AWSTraceHeader。如果存在，应使用 AWS X-Ray Propagator 从该属性的值解析出一个 OpenTelemetry Context，并将其添加为 span 的链接。这意味着 span 可能有与消息批次中消息数量相同的链接。有关更多信息，请参阅 兼容性。

• faas.trigger 必须设置为 pubsub。
• messaging.operation.type 必须设置为 process。
• messaging.system 必须设置为 aws_sqs。

SQS 消息

对于 SQS 消息 span，名称必须是 <event source> process。父 span 必须是与 SQS 事件对应的 CONSUMER span。应检查 消息系统属性（不是用户提供的消息属性）是否包含键 AWSTraceHeader。如果存在，应使用 AWS X-Ray Propagator 从该属性的值解析出一个 OpenTelemetry Context，并将其添加为 span 的链接。有关更多信息，请参阅 兼容性。

• faas.trigger 必须设置为 pubsub。
• messaging.operation.type 必须设置为 process。
• messaging.system 必须设置为 aws_sqs。

其他 Messaging 属性应基于 SQS 消息事件中的可用信息进行设置。

请注意，AWSTraceHeader 是 instrumenting SQS 以防止与其他源冲突的唯一支持的上下文传播机制。特别是，消息属性（用户提供，非系统）不受支持 - 链接的上下文始终应作为消息源头的 SQS.SendMessage 请求的 HTTP 头发送。这是 AWS SDK instrumenting 的功能，而不是 Lambda instrumenting 的功能。

使用 AWSTraceHeader 可确保跨可能通过 SQS 与 Lambda 集成的 AWS 服务（例如，S3 -> SNS -> SQS -> Lambda 的流程）进行传播。AWSTraceHeader 仅作为传播上下文的手段，与任何特定的可观测性后端无关。特别是，使用它并不意味着使用 AWS X-Ray - 任何可观测性后端都可以完全正常地使用此传播机制。

示例

API Gateway 请求代理 (Lambda 跟踪被动)

给定一个进程 C，它向配置了 Lambda 函数 F 的 API Gateway 端点发送 HTTP 请求，路径为 /pets/{petId}

Process C: | Span Client        |
--
Function F:    | Span Function |

API Gateway 请求代理 (Lambda 跟踪主动)

Lambda 中的活动跟踪意味着 API Gateway span Span APIGW 和 Lambda 运行时调用 span Span Lambda 将由基础设施（非 instrumenting）导出到 AWS X-Ray。以上所有属性都相同，只是在这种情况下，APIGW 的父 span 是 Span Client，而 Span Function 的父 span 是 Span Lambda。这意味着层次结构如下所示：

Span Client --> Span APIGW --> Span Lambda --> Span Function

SQS (Lambda 跟踪被动)

给定一个进程 P，它向 SQS 中的队列 Q 发送两条消息，以及一个 Lambda 函数 F，它在一个批次中处理它们（Span ProcBatch），并分别生成每条消息的处理 span（Spans Proc1 和 Proc2）。

Process P: | Span Prod1 | Span Prod2 |
--
Function F:                      | Span ProcBatch |
                                        | Span Proc1 |
                                               | Span Proc2 |

请注意，如果 Span Prod1 和 Span Prod2 发送到不同的队列，Span ProcBatch 将不会设置 messaging.destination.name，因为它将对应于多个队列。

以上需要用户代码更改才能创建 Span Proc1 和 Span Proc2。在 Java 中，用户将继承 TracingSqsMessageHandler 而不是 Lambda 的标准 RequestHandler 来启用它们。否则，这两个 span 将不存在。

SQS (Lambda 跟踪主动)

Lambda 中的活动跟踪意味着 Lambda 运行时调用 span Span Lambda 将由基础设施（非 instrumenting）导出到 X-Ray。在这种情况下，以上所有内容都相同，只是 Span ProcBatch 的父 span 是 Span Lambda。这意味着层次结构如下所示：

Span Lambda --> Span ProcBatch --> Span Proc1 (links to Span Prod1 and Span Prod2)
                               \-> Span Proc2 (links to Span Prod1 and Span Prod2)

资源检测器

AWS Lambda 资源信息可作为运行时提供的 环境变量。

• cloud.provider 必须设置为 aws
• cloud.region 必须设置为 AWS_REGION 环境变量的值
• faas.name 必须设置为 AWS_LAMBDA_FUNCTION_NAME 环境变量的值
• faas.version 必须设置为 AWS_LAMBDA_FUNCTION_VERSION 环境变量的值

请注意，cloud.resource_id 目前无法作为资源填充，因为它在函数调用之前不可用。