FaaS Span 的语义约定

状态: 开发中

本文档定义了如何使用 Span 来描述无服务器函数（也称为无服务器函数或 FaaS）的运行实例。

另请参阅 有关仪器化 AWS Lambda 的附加说明。

通用属性

Span 的 name 应设置为正在执行的函数名称。根据 faas.trigger 属性的值，必须设置其他属性。例如，http 触发器应遵循 HTTP 服务器语义约定。有关更多信息，请参阅 函数触发器类型 部分。

有关如何记录 Span 状态的详细信息，请参阅 记录错误 文档。

如果生成遵循此约定的 Span，则必须存在类型为 faas 的资源，遵循 资源语义约定。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
cloud.resource_id		推荐	字符串	被监控云资源的特定于云提供商的原生标识符（例如，AWS 上的 ARN，Azure 上的 完全限定资源 ID，GCP 上的 完整资源名称）[1]	arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function; //run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID; /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>
faas.invocation_id		推荐	字符串	当前函数调用的调用 ID。	af9d5aa4-a685-4c5f-a22b-444f80b3cc28
faas.trigger		推荐	字符串	导致此函数调用的触发器的类型。[2]	datasource; http; pubsub

[1] cloud.resource_id： 在某些云提供商上，可能无法在启动时确定完整 ID，因此可能需要将 cloud.resource_id 设置为 Span 属性。

cloud.resource_id 的确切值取决于云提供商。如果您设置了此属性，并且它们适用，则必须使用以下已知定义。

• AWS Lambda: 函数 ARN。请注意不要直接使用“调用 ARN”，而是将任何 别名后缀替换为已解析的函数版本，因为同一个运行时实例可能可以使用多个不同的别名进行调用。
• GCP: 资源的 URI
• Azure: 被调用函数的 完全限定资源 ID，而不是函数应用，格式为 /subscriptions/<SUBSCRIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>。这意味着必须使用 span 属性，因为 Azure 函数应用可以托管多个通常会共享 TracerProvider 的函数。

[2] faas.trigger： 对于入站端的服务器/使用者 Span，必须设置 faas.trigger。

调用 FaaS 实例的客户端通常无法设置 faas.trigger，因为它们通常需要检查有效负载以确定事件类型。如果客户端设置了它，它应该与相应入站调用将具有的触发器相同（也就是说，这与用于调用 lambda 的 API 的底层传输无关，后者通常是 HTTP）。

faas.trigger 具有以下已知值列表。如果其中一个适用，则必须使用相应的owel；否则，可以使用自定义值。

值	描述	Stability
datasource	对某些数据源操作（如数据库或文件系统读/写）的响应
http	为响应入站 HTTP 请求而提供答案
other	如果以上都不适用
pubsub	设置一个函数，在消息发送到消息系统时执行
timer	调度函数定期执行

函数名称

可以在 2 个位置记录函数的名称：Span 名称和 faas.name 资源属性。

如果存在 faas.name 属性，则保证它包含函数名称，因为它是严格为此目的定义的。Span 名称也很可能包含函数名称（例如，用于 Span 显示目的），但不能保证（因为这是一个较弱的“SHOULD”要求）。需要这种保证的消费者可以使用 faas.name 属性作为源。

调用与实例的区别

出于性能原因（例如 AWS lambda 或 Azure functions），FaaS 提供商会为单个函数实例分配一个执行环境，用于处理多个请求。开发人员利用这一点来解决冷启动问题，在不同的函数调用之间缓存昂贵的资源计算。此外，FaaS 提供商鼓励这种行为，例如 Google functions。faas.instance 资源属性可以设置，以帮助关联属于同一执行环境的函数调用。Span 属性 faas.invocation_id 与 资源属性 faas.instance 的区别如下：

• faas.invocation_id 指的是当前函数调用的 ID；
• faas.instance 指的是函数的执行环境 ID。

入站调用

本节描述 FaaS 实例自身报告的入站 FaaS 调用。

入站 FaaS Span 属性

状态:

此 Span 代表 FaaS 调用的服务器（入站）端。

Span kind 应为 SERVER。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
faas.trigger		必需	字符串	导致此函数调用的触发器的类型。[1]	datasource; http; pubsub
faas.coldstart		推荐	布尔值	一个布尔值，如果无服务器函数是第一次执行（又名冷启动），则为 true。

[1] faas.trigger： 对于入站端的服务器/使用者 Span，必须设置 faas.trigger。

调用 FaaS 实例的客户端通常无法设置 faas.trigger，因为它们通常需要检查有效负载以确定事件类型。如果客户端设置了它，它应该与相应入站调用将具有的触发器相同（也就是说，这与用于调用 lambda 的 API 的底层传输无关，后者通常是 HTTP）。

faas.trigger 具有以下已知值列表。如果其中一个适用，则必须使用相应的owel；否则，可以使用自定义值。

值	描述	Stability
datasource	对某些数据源操作（如数据库或文件系统读/写）的响应
http	为响应入站 HTTP 请求而提供答案
other	如果以上都不适用
pubsub	设置一个函数，在消息发送到消息系统时执行
timer	调度函数定期执行

作为入站 FaaS Span 属性的资源属性

除了上面列出的属性之外，任何 FaaS 或 云 资源属性也可以设置为入站 FaaS 调用 Span 的 Span 属性：在某些 FaaS 环境中，某些资源属性所需的信息仅在调用上下文中易于获取（例如，作为“请求上下文”参数的一部分），并且虽然通常可以通过单独的 API 调用来查找资源信息，但由于冷启动持续时间问题，它可能非常昂贵。AWS 上的 cloud.resource_id 和 cloud.account.id 属性就是一些例子。原则上，上述考虑因素适用于满足上述标准的任何资源属性（即，没有额外努力就无法轻松获得的，而这种努力可能很昂贵）。

出站调用

本节描述调用 FaaS 实例的客户端报告的出站 FaaS 调用。

状态:

此 Span 代表对 FaaS 服务的出站调用。

客户端为下面列出的属性报告的值应等于被调用 FaaS 实例自身报告的相应 FaaS 资源属性 和 云资源属性（如果它已仪器化）。

**Span 类型**应为 CLIENT。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
faas.invoked_name		必需	字符串	被调用函数的名称。[1]	my-function
faas.invoked_provider		必需	字符串	被调用函数的云提供商。[2]	alibaba_cloud; aws; azure
faas.invoked_region		有条件地必需 [3]	字符串	被调用函数的云区域。[4]	eu-central-1

[1] faas.invoked_name： 应等于被调用函数的 faas.name 资源属性。

[2] faas.invoked_provider： 应等于被调用函数的 cloud.provider 资源属性。

[3] faas.invoked_region： 对于某些云提供商，如 AWS 或 GCP，函数所在的区域对于唯一标识函数至关重要，并且也是其端点的一部分。由于它是被调用端点的一部分，客户端始终知道该区域。在这些情况下，必须相应地设置 faas.invoked_region。如果客户端不知道区域或区域不是唯一标识被调用函数所必需的，则设置 faas.invoked_region 是可选的。

[4] faas.invoked_region： 应等于被调用函数的 cloud.region 资源属性。

faas.invoked_provider 具有以下已知的列表值。如果其中一个适用，则必须使用相应的价值；否则，可以使用自定义价值。

值	描述	Stability
alibaba_cloud	阿里云
aws	Amazon Web Services
azure	Microsoft Azure
gcp	Google Cloud Platform
tencent_cloud	腾讯云

函数触发器类型

本节描述如何根据 faas.trigger 属性的值来处理 Span 的创建和附加属性。

数据源

状态:

此 Span 代表 FaaS 调用由数据库或文件系统读/写等数据源操作触发的服务器端。

Span kind 应为 SERVER。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
faas.document.collection		必需	字符串	在触发操作的源上执行的操作的名称。例如，在 Cloud Storage 或 S3 中对应于存储桶名称，在 Cosmos DB 中对应于数据库名称。	myBucketName; myDbName
faas.document.operation		必需	字符串	描述了对数据执行的操作的类型。	insert; edit; delete
faas.document.name		推荐	字符串	进行操作的文档名称/表。例如，在 Cloud Storage 或 S3 中是文件的名称，在 Cosmos DB 中是表名。	myFile.txt; myTableName
faas.document.time		推荐	字符串	一个字符串，包含数据访问时间的 ISO 8601 格式（以 UTC 表示）。	2020-01-23T13:47:06Z

faas.document.operation 具有以下已知列表值。如果其中一个适用，则必须使用相应的价值；否则，可以使用自定义价值。

值	描述	Stability
delete	删除对象时。
edit	修改对象时。
insert	创建新对象时。

HTTP

函数负责响应入站 HTTP 请求。faas Span 应遵循 HTTP Server 语义约定 中描述的建议。

PubSub

当消息发送到消息系统时，函数会被设置为执行。在这种情况下，多个消息可能会被批量处理并一次性转发到同一个函数调用。因此，对于函数处理的每条消息，都必须创建一个不同类型的 faas 根 Span，遵循 消息系统语义约定。这样，就可以将每条消息与其调用发送者相关联。

定时器

函数被安排定期执行。建议使用以下附加属性。

状态:

此 Span 代表 FaaS 调用由定时器触发的服务器端。

Span kind 应为 SERVER。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
faas.cron		推荐	字符串	一个包含计划周期的字符串，使用 Cron Expression 格式。	0/5 * * * ? *
faas.time		推荐	字符串	一个包含函数调用时间的字符串，使用 ISO 8601 格式（以 UTC 表示）。	2020-01-23T13:47:06Z

其他

FaaS 提供了如此大的灵活性，以至于不可能完全用语义约定来覆盖。当一个函数不满足上述任何情况时，Span 必须将属性 faas.trigger 设置为 "other"。在这种情况下，由框架或仪器库来定义最合适的属性。

示例

此示例显示了托管在 Google Cloud Platform 上的（非 FaaS）进程的 FaaS 属性（Span A，Kind 为 CLIENT），该进程调用 Amazon Web Services 中的名为“my-lambda-function”的 Lambda 函数（Span B，Kind 为 SERVER）。