Google Cloud Pub/Sub 的语义约定

状态: 开发中

Google Cloud Pub/Sub 的语义约定扩展并覆盖了消息语义约定。

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

Span 属性

对于 Google Cloud Pub/Sub，定义了以下附加属性

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
messaging.operation.name		必需	字符串	消息操作的系统特定名称。[1]	ack; nack; send
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.gcp_pubsub.message.ordering_key		有条件必需 如果消息类型设置了排序键。	字符串	给定消息的排序键。如果属性不存在，则该消息没有排序键。	ordering_key
messaging.operation.type		条件必需 如果适用。	字符串	标识消息操作类型的字符串。[7]	create; send; receive
server.address		有条件必需 如果可用。	字符串	如果可用且无需反向 DNS 查找，则为服务器域名；否则，为 IP 地址或 Unix 域套接字名称。[8]	example.com；10.1.2.80；/tmp/my.sock
messaging.destination.subscription.name		推荐	字符串	Google Pub/Sub 订阅名称。	subscription-a
messaging.gcp_pubsub.message.ack_deadline		推荐	int	为修改确认截止时间请求设置的以秒为单位的确认截止时间。	10
messaging.gcp_pubsub.message.ack_id		推荐	字符串	给定消息的确认 ID。	ack_id
messaging.gcp_pubsub.message.delivery_attempt		推荐	int	给定消息的传递尝试次数。	2
messaging.message.id		推荐 如果 span 描述的是单条消息的操作。	字符串	消息传递系统用作消息标识符的值，表示为字符串。	452a7c7c7c7048c2f887f61572b18fc2
server.port		推荐	int	服务器端口号。[9]	80; 8080; 443

[1] messaging.operation.name： 在 Google Pub/Sub 上下文中，messaging.operation.name 具有以下一系列知名值。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

• ack 和 nack 用于结算操作
• send 用于发布操作
• modack 用于延长单个消息或消息批次的租约
• subscribe 用于表示消息从接收到确认、负确认或过期之间的时间的操作。
• create 和 receive 用于通用消息操作

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

[9] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。

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

• messaging.destination.name
• messaging.destination.subscription.name
• messaging.operation.name
• messaging.operation.type
• server.address
• server.port

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

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

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

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

示例

异步批量发布示例

以下是一个进程 P，该进程将 2 条消息异步批量发布到 Pub/Sub 上的主题 T。

flowchart LR;
  subgraph PRODUCER
  direction LR
  CA[Span Create A]
  CB[Span Create B]
  P[Span Send A B]
  end
  CA-. link .-P;
  CB-. link .-P;

  classDef producer fill:green
  class P,CA,CB producer
  classDef normal fill:green
  class PA,PB,D1 normal
  linkStyle 0,1 color:green,stroke:green

单元拉取示例

flowchart TD;
  subgraph CONSUMER
  direction LR
  R1[Receive A]
  SM1[Ack A]
  EM1[Modack A]
  end
  subgraph PRODUCER
  direction LR
  CM1[Create A]
  PM1[Send]
  end
  %% Link 0
  CM1-. link .-PM1;
  %% Link 1
  CM1-. link .-R1;
  %% Link 2
  R1-. link .-SM1;
  %% Link 3
  R1-. link .-EM1;

  %% Style the node and corresponding link
  %% Producer links and nodes
  classDef producer fill:green
  class PM1,CM1 producer
  linkStyle 0 color:green,stroke:green

  %% Consumer links and nodes
  classDef consumer fill:#49fcdc
  class R1 consumer
  linkStyle 1 color:#49fcdc,stroke:#49fcdc

  classDef ack fill:#577eb5
  class SM1 ack
  linkStyle 2 color:#577eb5,stroke:#577eb5

  classDef modack fill:#0560f2
  class EM1 modack
  linkStyle 3 color:#0560f2,stroke:#0560f2