集成 OpenTelemetry 追踪

OpenTelemetry 追踪是一个用于追踪请求在分布式系统中的流动的规范，用于追踪请求在分布式系统中的流动情况，并提供可视化分析请求的性能和行为的能力。在 MQTT 场景下，这一概念可以实现跨越 MQTT 消息传输中的不同参与者（发布者-MQTT 服务器-订阅者）的请求追踪。

"Trace context"（追踪上下文）是一种分布式追踪的机制，它用于跟踪和识别跨越多个系统和服务的请求或事务。EMQX 遵循 W3C 的 Trace Context MQTT 规范实现了端到端的分布式追踪功能。这样，系统管理员或开发人员可以通过追踪信息来观测消息在整个系统中的流转情况。

EMQX 传播追踪上下文的固有能力使其能够无缝地参与分布式追踪系统，这种传播是通过简单地将消息发布者的 traceparent 和 tracestate 用户属性转发给订阅者来实现的。当 EMQX 将应用消息转发给客户端时，它保证了追踪上下文完整不变地传输。这种方法完全符合 MQTT 规范 3.3.2.3.7，确保了追踪数据传输的一致性和可靠性。

提示

用户属性在 MQTT 5.0 中引入，因此 EMQX 仅支持 MQTT 5.0 客户端的追踪上下文提取和传播。

对于非 MQTT 5.0 客户端，需要在 EMQX 开启追踪全部消息选项，EMQX 将内部自动为消息添加追踪 ID 实现分布式追踪。

借助 OpenTelemetry 分布式追踪，EMQX 系统管理员或开发者可以实时监测和分析物联网应用的性能和行为，并在出现故障时快速定位并排除故障。

本页介绍了如何将 OpenTelemetry 追踪与 EMQX 集成，详细描述了设置 OpenTelemetry Collector 并在 EMQX 中启用和配置 OpenTelemetry 追踪集成，以及管理追踪跨度过载。

设置 OpenTelemetry Collector

在将 EMQX 与 OpenTelemetry 追踪集成之前，您需要部署并配置 OpenTelemetry Collector 以及一个兼容 OpenTelemetry 的可观测性平台，例如 Jaeger。以下步骤概述了部署和配置过程：

1. 创建 OpenTelemetry Collector 配置文件 otel-trace-collector-config.yaml：

   receivers:
     otlp:
       protocols:
         grpc:
   
   exporters:
     otlp:
       endpoint: jaeger:4317
       tls:
         insecure: true
   
   processors:
     batch:
   
   extensions:
     health_check:
   
   service:
     extensions: [health_check]
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlp]

2. 在相同目录下创建 Docker Compose 文件 docker-compose-otel-trace.yaml：

   version: '3.9'
   services:
     jaeger:
       image: jaegertracing/all-in-one:1.51.0
       restart: always
       ports:
         - "16686:16686"
   
     otel-collector:
       image: otel/opentelemetry-collector:0.90.0
       restart: always
       command: ["--config=/etc/otel-collector-config.yaml", "${OTELCOL_ARGS}"]
       volumes:
         - ./otel-trace-collector-config.yaml:/etc/otel-collector-config.yaml
       ports:
         - "13133:13133" # 健康检查扩展
         - "4317:4317"   # OTLP gRPC 接收器
       depends_on:
         - jaeger

3. 使用 Docker Compose 启动服务：

   docker compose -f docker-compose-otel-trace.yaml up

4. 启动后，OpenTelemetry Collector 将在主机的默认 gRPC端口（4317）上监听，Jaeger WEB UI 可以在 http://localhost:16686 访问。

在 EMQX 中启用 OpenTelemetry 追踪

本节指导您如何在 EMQX 中启用 OpenTelemetry 追踪，展示多节点设置中的分布式追踪能力。

你也可以在 Dashboard 管理 -> 监控 页面下的 监控集成 选项卡中配置 OpenTelemetry 追踪集成。

1. 将以下配置添加到 EMQX cluster.hocon 文件中（假设 EMQX 在本地机器上运行）：

   opentelemetry {
     exporter { endpoint = "http://localhost:4317" }
     traces {
      enable = true
      # 是否追踪全部消息
      # 如果无法从消息中提取追踪 ID，则会生成一个新的追踪 ID。
      # filter.trace_all = true
    }
   }

2. 启动 EMQX 节点，例如，以节点名 emqx@127.0.0.1 和 emqx1@127.0.0.1 启动一个有两个节点的集群，以展示分布式追踪功能。

3. 使用 MQTTX CLI 作为客户端在不同节点和端口上订阅相同主题。

   • 在 emqx@127.0.0.1 节点上（默认 MQTT 监听器在端口 1883）：

     mqttx sub -t t/trace/test -h localhost -p 1883

   • 在 emqx1@127.0.0.1 节点上（监听器在端口 1884）：

     mqttx sub -t t/trace/test -h localhost -p 1884

4. 发布带有追踪上下文的消息，向主题发送包含有效 traceparent 用户属性的消息：

   mqttx pub -t t/trace/test -h localhost -p 1883 -up "traceparent: 00-cce3a024ca134a7cb4b41e048e8d98de-cef47eaa4ebc3fae-01"

5. 大约 5 秒后（EMQX 导出追踪数据的默认间隔），导航到 http://localhost:16686 的 Jaeger WEB UI 观察追踪数据：

   • 选择 emqx 服务并点击 查找追踪。如果 emqx 服务没有立即出现，请稍等片刻后刷新页面。您应该看到消息追踪：

     

   • 点击追踪查看详细的跨度信息和追踪时间线：

     

在此示例中，EMQX 追踪了两种不同类型的跨度：

• process_message 跨度从接收并解析 PUBLISH 包的 EMQX 节点开始，直到消息被分发给本地订阅者和转发给其他有活跃订阅者的节点（如果有）为止。每个跨度对应一个被追踪的已发布消息。
• send_published_message 跨度从订阅者的连接控制进程接收追踪消息开始，直到将外发包序列化并发送到连接套接字为止。每个活跃订阅者都会创建一个 send_published_message 跨度。

管理追踪跨度过载

EMQX 会积累追踪跨度，并定期批量导出它们。 导出间隔由 opentelemetry.trace.scheduled_delay 参数控制，默认为 5 秒。 批处理追踪跨度处理器包含过载保护机制，允许只积累到一定限制的跨度，该限制默认为 2048 个跨度。您可以使用以下配置设置此限制：

opentelemetry {
  traces { max_queue_size = 2048 }
}

一旦达到 max_queue_size 限制，新的追踪跨度将被丢弃，直到当前队列被导出。

提示

如果追踪的消息被分发给大量订阅者（远高于 max_queue_size 的值）， 预计只有少量跨度会被导出，大多数跨度会因过载保护而被丢弃。

增加 max_queue_size 应该非常谨慎，因为它可能会影响性能和内存消耗。