消息传递客户端指标的语义约定
状态: 开发中
正在使用 此文档 v1.24.0（或之前版本） 的现有消息传递仪器
- 在消息传递语义约定被标记为稳定之前，不应更改它们默认发出的消息传递约定版本。约定包括但不限于属性、指标和跨度名称、跨度种类和度量单位。
- 在现有主版本中，应引入一个名为
OTEL_SEMCONV_STABILITY_OPT_IN的环境变量，该变量是一个逗号分隔的类别特定值列表（例如，http、databases、messaging）。值列表包括：messaging- 发出新的、稳定的消息传递约定，并停止发出仪器先前发出的旧实验性消息传递约定。messaging/dup- 同时发出旧的稳定消息传递约定和新的稳定消息传递约定，实现无缝过渡。- 默认行为（在没有这些值的情况下）是继续发出仪器先前发出的旧实验性消息传递约定的任何版本。
- 注意：如果同时存在
messaging和messaging/dup，则messaging/dup的优先级高于messaging。
- 在开始发出两组约定后，应至少维护现有主版本（至少进行安全修补）六个月。
- 应在下一个主版本中删除该环境变量。
- 当
messaging/dup出现在列表中时，应为跨度名称、跨度种类和类似的“单一”值概念发出新的、稳定的值。
通用指标
Metric: messaging.client.operation.duration
当此指标与消息传递跨度一起报告时，指标值应与相应的跨度持续时间相同。
此指标是必需的。
此指标 SHOULD 使用 ExplicitBucketBoundaries，其值为 [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]。
| 名称 | Instrument Type | Unit (UCUM) | 描述 | Stability | 实体关联 |
|---|---|---|---|---|---|
messaging.client.operation.duration | Histogram | s | 生产者或消费者客户端发起的消息传递操作的持续时间。[1] |  |
[1]: 此指标不应用于报告处理持续时间 - 处理持续时间在 messaging.process.duration 指标中报告。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | 必需 | 字符串 | 消息操作的系统特定名称。 | send; receive; ack |
messaging.system | | 必需 | 字符串 | 由客户端仪器识别的消息传递系统。[1] | activemq; aws.sns; aws_sqs |
error.type |  | 条件必需 仅当消息操作失败时。 | 字符串 | 描述操作结束时发生的错误类型。[2] | amqp:decode-error; KAFKA_STORAGE_ERROR; channel-error |
messaging.consumer.group.name | | 条件必需（如果适用）。 | 字符串 | 与消费者关联的消费者组的名称。[3] | my-group; indexer |
messaging.destination.name | | 有条件地必需 [4] | 字符串 | 消息目标名称 [5] | MyQueue; MyTopic |
messaging.destination.subscription.name | | 条件必需（如果适用）。 | 字符串 | 从消息中消耗的消息的目标订阅名称。[6] | subscription-a |
messaging.destination.template | | 条件必需（如果可用）。 | 字符串 | 消息目标名称的低基数表示 [7] | /customers/{customerId} |
messaging.operation.type | | 条件必需 如果适用。 | 字符串 | 标识消息传递操作类型的字符串。[8] | create; send; receive |
server.address | | 有条件必需 如果可用。 | 字符串 | 如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[9] | example.com；10.1.2.80；/tmp/my.sock |
messaging.destination.partition.id | | 推荐 | 字符串 | 发送或接收消息的分区的标识符，在 messaging.destination.name 中是唯一的。 | 1 |
server.port | | 推荐 | int | 服务器端口号。[10] | 80; 8080; 443 |
[1] messaging.system: 实际的消息传递系统可能与客户端所知的系统不同。例如，当使用 Kafka 客户端库与 Azure Event Hubs 通信时，messaging.system 根据仪器所知的最佳信息设置为 kafka。
[2] error.type: error.type 应可预测且具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[3] messaging.consumer.group.name: 特定消息传递系统的语义约定应记录 messaging.consumer.group.name 是否适用以及它在该系统中的含义。
[4] messaging.destination.name: 当且仅当 messaging.destination.name 已知具有低基数时。否则，可以填充 messaging.destination.template。
[5] messaging.destination.name: 目标名称应唯一标识代理中的特定队列、主题或其他实体。如果代理没有此类概念，则目标名称应唯一标识代理。
[6] messaging.destination.subscription.name: 特定消息传递系统的语义约定应记录 messaging.destination.subscription.name 是否适用以及它在该系统中的含义。
[7] messaging.destination.template: 目标名称可以从模板构建。例如，目标名称可能涉及用户名或产品 ID。尽管在这种情况下目标名称具有高基数，但底层模板具有低基数，并且可以有效地用于分组和聚合。
[8] messaging.operation.type: 如果使用自定义值，则其基数必须较低。
[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.system 具有以下一系列已知值。如果适用其中一个，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
生产者指标
Metric: messaging.client.sent.messages
此指标是必需的。
| 名称 | Instrument Type | Unit (UCUM) | 描述 | Stability | 实体关联 |
|---|---|---|---|---|---|
messaging.client.sent.messages | Counter | {message} | 生产者尝试发送到代理的消息数量。[1] | |
[1]: 此指标不得计算已创建但尚未发送的消息。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | 必需 | 字符串 | 消息操作的系统特定名称。 | send; schedule; enqueue |
messaging.system | | 必需 | 字符串 | 由客户端仪器识别的消息传递系统。[1] | activemq; aws.sns; aws_sqs |
error.type | | 条件必需 仅当消息操作失败时。 | 字符串 | 描述操作结束时发生的错误类型。[2] | amqp:decode-error; KAFKA_STORAGE_ERROR; channel-error |
messaging.destination.name | | 有条件地必需 [3] | 字符串 | 消息目标名称 [4] | MyQueue; MyTopic |
messaging.destination.template | | 条件必需（如果可用）。 | 字符串 | 消息目标名称的低基数表示 [5] | /customers/{customerId} |
server.address | | 有条件必需 如果可用。 | 字符串 | 如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[6] | example.com；10.1.2.80；/tmp/my.sock |
messaging.destination.partition.id | | 推荐 | 字符串 | 发送或接收消息的分区的标识符，在 messaging.destination.name 中是唯一的。 | 1 |
server.port | | 推荐 | int | 服务器端口号。[7] | 80; 8080; 443 |
[1] messaging.system: 实际的消息传递系统可能与客户端所知的系统不同。例如，当使用 Kafka 客户端库与 Azure Event Hubs 通信时，messaging.system 根据仪器所知的最佳信息设置为 kafka。
[2] error.type: error.type 应可预测且具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[3] messaging.destination.name: 当且仅当 messaging.destination.name 已知具有低基数时。否则，可以填充 messaging.destination.template。
[4] messaging.destination.name: 目标名称应唯一标识代理中的特定队列、主题或其他实体。如果代理没有此类概念，则目标名称应唯一标识代理。
[5] messaging.destination.template: 目标名称可以从模板构建。例如，目标名称可能涉及用户名或产品 ID。尽管在这种情况下目标名称具有高基数，但底层模板具有低基数，并且可以有效地用于分组和聚合。
[6] server.address: 如果可用且无需反向 DNS 查找，则为代理的服务器域名；否则，为 IP 地址或 Unix 域套接字名称。
[7] server.port: 当从客户端观察到并且通过中间件通信时，server.port 应代表任何中间件（例如代理）之后的服务器端口，如果可用。
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
messaging.system 具有以下一系列已知值。如果适用其中一个，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
消费者指标
Metric: messaging.client.consumed.messages
此指标是必需的。
| 名称 | Instrument Type | Unit (UCUM) | 描述 | Stability | 实体关联 |
|---|---|---|---|---|---|
messaging.client.consumed.messages | Counter | {message} | 已传递给应用程序的消息数量。[1] | |
[1]: 记录从代理拉取的消息数量或在推送式场景中分派给应用程序的消息数量。此指标应为每条消息传递报告一次。例如，如果为单条消息传递分别仪器化了接收和处理操作，则在消息接收时会增加此计数器，而在处理时不会报告。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | 必需 | 字符串 | 消息操作的系统特定名称。 | receive; peek; poll; consume |
messaging.system | | 必需 | 字符串 | 由客户端仪器识别的消息传递系统。[1] | activemq; aws.sns; aws_sqs |
error.type | | 条件必需 仅当消息操作失败时。 | 字符串 | 描述操作结束时发生的错误类型。[2] | amqp:decode-error; KAFKA_STORAGE_ERROR; channel-error |
messaging.consumer.group.name | | 条件必需（如果适用）。 | 字符串 | 与消费者关联的消费者组的名称。[3] | my-group; indexer |
messaging.destination.name | | 有条件地必需 [4] | 字符串 | 消息目标名称 [5] | MyQueue; MyTopic |
messaging.destination.subscription.name | | 条件必需（如果适用）。 | 字符串 | 从消息中消耗的消息的目标订阅名称。[6] | subscription-a |
messaging.destination.template | | 条件必需（如果可用）。 | 字符串 | 消息目标名称的低基数表示 [7] | /customers/{customerId} |
server.address | | 有条件必需 如果可用。 | 字符串 | 如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[8] | example.com；10.1.2.80；/tmp/my.sock |
messaging.destination.partition.id | | 推荐 | 字符串 | 发送或接收消息的分区的标识符，在 messaging.destination.name 中是唯一的。 | 1 |
server.port | | 推荐 | int | 服务器端口号。[9] | 80; 8080; 443 |
[1] messaging.system: 实际的消息传递系统可能与客户端所知的系统不同。例如，当使用 Kafka 客户端库与 Azure Event Hubs 通信时，messaging.system 根据仪器所知的最佳信息设置为 kafka。
[2] error.type: error.type 应可预测且具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[3] messaging.consumer.group.name: 特定消息传递系统的语义约定应记录 messaging.consumer.group.name 是否适用以及它在该系统中的含义。
[4] messaging.destination.name: 当且仅当 messaging.destination.name 已知具有低基数时。否则，可以填充 messaging.destination.template。
[5] messaging.destination.name: 目标名称应唯一标识代理中的特定队列、主题或其他实体。如果代理没有此类概念，则目标名称应唯一标识代理。
[6] messaging.destination.subscription.name: 特定消息传递系统的语义约定应记录 messaging.destination.subscription.name 是否适用以及它在该系统中的含义。
[7] messaging.destination.template: 目标名称可以从模板构建。例如，目标名称可能涉及用户名或产品 ID。尽管在这种情况下目标名称具有高基数，但底层模板具有低基数，并且可以有效地用于分组和聚合。
[8] server.address: 如果可用且无需反向 DNS 查找，则为代理的服务器域名；否则，为 IP 地址或 Unix 域套接字名称。
[9] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
messaging.system 具有以下一系列已知值。如果适用其中一个，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |
Metric: messaging.process.duration
当此指标与消息传递处理跨度一起报告时，指标值应与相应的跨度持续时间相同。
此指标对于推送式消息传递是必需的，并且对于仪器化为拉取式场景的处理操作是推荐的。
此指标 SHOULD 使用 ExplicitBucketBoundaries，其值为 [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]。
| 名称 | Instrument Type | Unit (UCUM) | 描述 | Stability | 实体关联 |
|---|---|---|---|---|---|
messaging.process.duration | Histogram | s | 处理操作的持续时间。[1] | |
[1]: 此指标必须为 messaging.operation.type 匹配 process 的操作报告。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
messaging.operation.name | | 必需 | 字符串 | 消息操作的系统特定名称。 | process; consume; handle |
messaging.system | | 必需 | 字符串 | 由客户端仪器识别的消息传递系统。[1] | activemq; aws.sns; aws_sqs |
error.type | | 条件必需 仅当消息操作失败时。 | 字符串 | 描述操作结束时发生的错误类型。[2] | amqp:decode-error; KAFKA_STORAGE_ERROR; channel-error |
messaging.consumer.group.name | | 条件必需（如果适用）。 | 字符串 | 与消费者关联的消费者组的名称。[3] | my-group; indexer |
messaging.destination.name | | 有条件地必需 [4] | 字符串 | 消息目标名称 [5] | MyQueue; MyTopic |
messaging.destination.subscription.name | | 条件必需（如果适用）。 | 字符串 | 从消息中消耗的消息的目标订阅名称。[6] | subscription-a |
messaging.destination.template | | 条件必需（如果可用）。 | 字符串 | 消息目标名称的低基数表示 [7] | /customers/{customerId} |
server.address | | 有条件必需 如果可用。 | 字符串 | 如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[8] | example.com；10.1.2.80；/tmp/my.sock |
messaging.destination.partition.id | | 推荐 | 字符串 | 发送或接收消息的分区的标识符，在 messaging.destination.name 中是唯一的。 | 1 |
server.port | | 推荐 | int | 服务器端口号。[9] | 80; 8080; 443 |
[1] messaging.system: 实际的消息传递系统可能与客户端所知的系统不同。例如，当使用 Kafka 客户端库与 Azure Event Hubs 通信时，messaging.system 根据仪器所知的最佳信息设置为 kafka。
[2] error.type: error.type 应可预测且具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[3] messaging.consumer.group.name: 特定消息传递系统的语义约定应记录 messaging.consumer.group.name 是否适用以及它在该系统中的含义。
[4] messaging.destination.name: 当且仅当 messaging.destination.name 已知具有低基数时。否则，可以填充 messaging.destination.template。
[5] messaging.destination.name: 目标名称应唯一标识代理中的特定队列、主题或其他实体。如果代理没有此类概念，则目标名称应唯一标识代理。
[6] messaging.destination.subscription.name: 特定消息传递系统的语义约定应记录 messaging.destination.subscription.name 是否适用以及它在该系统中的含义。
[7] messaging.destination.template: 目标名称可以从模板构建。例如，目标名称可能涉及用户名或产品 ID。尽管在这种情况下目标名称具有高基数，但底层模板具有低基数，并且可以有效地用于分组和聚合。
[8] server.address: 如果可用且无需反向 DNS 查找，则为代理的服务器域名；否则，为 IP 地址或 Unix 域套接字名称。
[9] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
messaging.system 具有以下一系列已知值。如果适用其中一个，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
activemq | Apache ActiveMQ | |
aws.sns | Amazon Simple Notification Service (SNS) | |
aws_sqs | Amazon Simple Queue Service (SQS) | |
eventgrid | Azure Event Grid | |
eventhubs | Azure Event Hubs | |
gcp_pubsub | Google Cloud Pub/Sub | |
jms | Java Message Service | |
kafka | Apache Kafka | |
pulsar | Apache Pulsar | |
rabbitmq | RabbitMQ | |
rocketmq | Apache RocketMQ | |
servicebus | Azure Service Bus | |