Azure 消息系统的语义约定

状态: 开发中

Azure Service Bus 和 Azure Event Hubs 的语义约定扩展并覆盖了消息语义约定。

警告

正在使用此文档 v1.24.0（或之前版本）的现有消息传递仪器

在消息传递语义约定被标记为稳定之前，不应更改它们默认发出的消息传递约定版本。约定包括但不限于属性、指标和跨度名称、跨度种类和度量单位。
在现有主版本中，应引入一个名为 OTEL_SEMCONV_STABILITY_OPT_IN 的环境变量，该变量是一个逗号分隔的类别特定值列表（例如，http、databases、messaging）。值列表包括：
- messaging - 发出新的、稳定的消息传递约定，并停止发出仪器先前发出的旧实验性消息传递约定。
- messaging/dup - 同时发出旧的稳定消息传递约定和新的稳定消息传递约定，实现无缝过渡。
- 默认行为（在没有这些值的情况下）是继续发出仪器先前发出的旧实验性消息传递约定的任何版本。
- 注意：如果同时存在 messaging 和 messaging/dup，则 messaging/dup 的优先级高于 messaging。
在开始发出两组约定后，应至少维护现有主版本（至少进行安全修补）六个月。
应在下一个主版本中删除该环境变量。
当 messaging/dup 出现在列表中时，应为跨度名称、跨度种类和类似的“单一”值概念发出新的、稳定的值。

Azure Service Bus

messaging.system 必须设置为 "servicebus"，并且应在 **span 创建时** 提供。

Span 属性

定义了以下附加属性

Attributes

键	需求级别	Value Type	描述	Example Values
`messaging.operation.name`	`必需`	字符串	Azure Service Bus 操作名称。[1]	`send`；`receive`；`complete`；`process`；`peek`
`error.type`	`条件必需` 仅当消息操作失败时。	字符串	描述操作结束时发生的错误类型。[2]	`amqp:decode-error`; `KAFKA_STORAGE_ERROR`; `channel-error`
`messaging.batch.message_count`	`有条件地必需` [3]	int	在批处理操作范围内发送、接收或处理的消息数量。[4]	`0`; `1`; `2`
`messaging.destination.name`	`有条件地必需` [5]	字符串	消息目标名称[6]	`MyQueue`; `MyTopic`
`messaging.destination.subscription.name`	`有条件必需` 如果消息是从订阅中接收的。	字符串	Azure Service Bus 订阅名称。	`subscription-a`
`messaging.operation.type`	`条件必需` 如果适用。	字符串	标识消息操作类型的字符串。[7]	`create`; `send`; `receive`
`messaging.servicebus.disposition_status`	`有条件必需` 当且仅当 `messaging.operation` 为 `settle` 时。	字符串	描述了结算类型。	`complete`；`abandon`；`dead_letter`
`messaging.servicebus.message.delivery_count`	`有条件地必需` [8]	int	此消息已尝试的传递次数。	`2`
`server.address`	`有条件必需` 如果可用。	字符串	如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[9]	`example.com`；`10.1.2.80`；`/tmp/my.sock`
`messaging.message.conversation_id`	`推荐`	字符串	消息相关 ID 属性。	`MyConversationId`
`messaging.message.id`	`推荐` 如果 span 描述的是单条消息的操作。	字符串	消息传递系统用作消息标识符的值，表示为字符串。	`452a7c7c7c7048c2f887f61572b18fc2`
`messaging.servicebus.message.enqueued_time`	`推荐`	int	消息被接受并存储在实体中的 UTC 纪元秒。	`1701393730`
`server.port`	`推荐`	int	服务器端口号。[10]	`80`; `8080`; `443`

[1] messaging.operation.name：操作名称应匹配以下值之一

发送者操作：send、schedule、cancel_scheduled
事务操作：create_transaction、commit_transaction、rollback_transaction
接收者操作：receive、peek、receive_deferred、renew_message_lock
结算操作：abandon、complete、defer、dead_letter、delete
会话操作：accept_session、get_session_state、set_session_state、renew_session_lock

如果以上操作名称均不适用，则该属性应设置为客户端方法的名称（snake_case 格式）。

[2] error.type: error.type 应可预测且具有低基数。

当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。

Instrumentations 应该记录它们报告的错误列表。

一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。

如果操作已成功完成，Instrumentations 不应设置 error.type。

如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议

使用特定于域的属性
设置 error.type 以捕获所有错误，无论它们是否包含在特定于域的集合中。

[3] messaging.batch.message_count：如果 span 描述的是对消息批次的操作。

[4] messaging.batch.message_count：Instrumentation 不应在对单个消息进行操作的 span 上设置 messaging.batch.message_count。当消息客户端库支持同一操作的批处理和单消息 API 时，Instrumentation 应为批处理 API 使用 messaging.batch.message_count，而为单消息 API 不应使用它。

[5] messaging.destination.name：如果 span 描述的是对单个消息的操作，或者如果该值适用于批次中的所有消息。

[6] messaging.destination.name：目标名称应唯一标识代理中的特定队列、主题或其他实体。如果代理没有此概念，则目标名称应唯一标识代理。

[7] messaging.operation.type：如果使用了自定义值，则它必须是低基数的。

[8] messaging.servicebus.message.delivery_count：如果传递计数可用且大于 0。

[9] server.address: 如果可用且无需反向 DNS 查找，则为代理的服务器域名；否则，为 IP 地址或 Unix 域套接字名称。

[10] server.port: 当从客户端观察到并且通过中间件通信时，server.port 应代表任何中间件（例如代理）之后的服务器端口，如果可用。

以下属性对于做出采样决策可能很重要，并且应在跨度创建时提供（如果提供的话）

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

值	描述	Stability
`_OTHER`	当检测不到自定义值时使用的回退错误值。

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

值	描述	Stability
`create`	创建消息。“Create”跨度始终指单条消息，用于为批量发送场景中的消息提供唯一的创建上下文。
`process`	一个或多个消息由消费者处理。
`receive`	一个或多个消息由消费者请求。此操作指拉取式场景，其中消费者显式调用消息 SDK 的方法来接收消息。
`send`	提供一个或多个消息以发送到中介。如果发送了单条消息，“Send”跨度的上下文可用作创建上下文，无需创建“Create”跨度。
`settle`	一个或多个消息已结算。

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

值	描述	Stability
`abandon`	消息被放弃
`complete`	消息已完成
`dead_letter`	消息已发送至死信队列
`defer`	消息已延迟

Azure Event Hubs

messaging.system 必须设置为 "eventhubs"，并且应在 **span 创建时** 提供。