Messaging Span 定义
Specifaition 中描述了 messaging span 的拓扑关系,包括代表消息发送、接收和处理的不同 span 之间的父子和链接关系。
关于具体的定义可以参考:Semantic Conventions of Messaging。对应到 RocketMQ 中,有三种不同的 span:
特别地,默认情况下,receive span 是不启用的。在 receive span 启用和不启用的两种情况下,span 之间的组织关系是不同的:
启用 receive span 前后的 span 关系
在没有启用 receive span 的情况下,process span 会作为 send span 的 child;而当 receive span 启用的情况下,process span 会作为 receive span 的 child,同时 link 到 send span。
Messaging Attributes 定义
语义约定中规定了随 span 携带的通用属性的统一名称,这包括但不限于:
- messaging.message.id: 消息的唯一标识符。
- messaging.destination:消息发送的目的地,通常是一个队列或主题名称。
- messaging.operation:对消息的操作类型,例如发送、接收、确认等。
具体可以查看 Messaging Attributes 的部分。
特别地,不同的消息系统可能会有自己特定的行为和属性,RocketMQ 也和 Kafka 以及 RabbitMQ 一起,将自己特有的属性推进了社区规范中,这包括:
快速开始
在 OpenTelemetry 中有两种不同的方式可以为应用程序添加可观测信息:
- Automatic Instrumentation:无需编写任何代码,只需进行简单的配置即可自动生成可观测信息,包括应用程序中使用的类库和框架,这样可以更方便地获取基本的性能和行为数据。
- Manual Instrumentation:需要编写代码来创建和管理可观测数据,并通过 exporter 导出到指定的目标。这样可以更灵活自由地控制用户想要观测的逻辑和功能。
在 Java 类库中,前者是一种更为常见的使用形式。RocketMQ 5.0 客户端的 trace 也依托于 automatic instrumentation 进行实现。在 Java 程序中,automatic instrumentation 的表现形式为挂载 Java agent。在过去的一年里,我们将基于 RocketMQ 5.0 客户端的 instrumentation推入了 OpenTelemetry 官方社区。现在,只需要在 Java 程序运行时挂载上 OpenTelemetry agent,即可实现对应用程序透明的分布式全链路追踪。
除此之外,Automatic Instrumentation 和 Manual Instrumentation 并不冲突,Automatic Instrumentation 中所使用的关键对象会被注册成全局对象,在 Manual Instrumentation 的使用方式中也可以非常方便的获取。实现两个 Instrumentation 共用一套配置,非常灵活和方便。
首先准备好 RocketMQ 5.0 Java 客户端,可以参考 example进行消息的收发。关于 RocketMQ 5.0 的更多细节,欢迎大家参考和关注 rocketmq-clients 仓库和 RocketMQ 官网。
然后准备好 OpenTelemetry agent jar,可以从 OpenTelemetry 官方下载最新 agent,在应用程序启动时增加 -javaagent:yourpath/opentelemetry-javaagent.jar 即可。
可以通过设置 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量来设置 OpenTelemetry collector 的接入点。
默认情况下,按照 OpenTelemetry 中关于 messaging 的规范,只有 send 和 process 的 span 会被启用,receive 的 span 是默认不启用的,如果想要启用 receive span,需要手动设置 -Dotel.instrumentation.messaging.experimental.receive-telemetry.enabled=true。