EMQX 企业版

简体中文

English
日本語

简体中文

English
日本語

Appearance

联系我们

端到端追踪 Span 详情 ​

EMQX 提供基于 OpenTelemetry 标准的端到端追踪能力。这允许您监控 EMQX 集群内 MQTT 消息和客户端活动的全生命周期。本页详细介绍了 EMQX 生成的各种 Span，以便深入了解 Broker 的内部工作原理。

客户端生命周期 Span ​

这些 Span 追踪 MQTT 客户端的主要生命周期事件。

  • client.connect：这是一个追踪客户端连接过程的根 Span。它在客户端向 Broker 发起连接时开始，在连接建立或被拒绝时结束。

  • client.disconnect：此 Span 追踪客户端断开连接的过程。它在客户端发送 DISCONNECT 报文或因其他原因（例如，网络错误、Keep Alive 超时）关闭连接时开始。

  • client.subscribe：此 Span 追踪客户端的订阅请求。它涵盖了 Broker 接收 SUBSCRIBE 报文、处理订阅和发送 SUBACK 报文的整个过程。

  • client.unsubscribe：此 Span 追踪客户端的取消订阅请求。它涵盖了从接收 UNSUBSCRIBE 报文到发送 UNSUBACK 报文的过程。

认证和授权 Span ​

这些 Span 提供了对客户端执行的安全相关检查的可见性。

  • client.authn：追踪客户端的认证过程。此 Span 是 client.connect Span 的子 Span。

  • client.authn_backend：追踪认证期间特定的后端调用（例如，查询数据库、调用 HTTP 服务）。这是 client.authn 的子 Span，有助于识别认证后端的性能瓶颈。

  • client.authz：追踪客户端的授权过程，该过程在发布或订阅操作时发生。

  • client.authz_backend：追踪授权期间特定的后端调用。这是 client.authz 的子 Span。

消息生命周期 Span ​

这些 Span 追踪 MQTT 消息在 Broker 中的传递过程。

消息入口 (客户端 -> Broker) ​

  • client.publish：这是一个根 Span，追踪客户端发布到 Broker 的消息。它在 Broker 收到 PUBLISH 报文时开始。

  • message.route：作为 client.publish 的子 Span，此 Span 追踪消息在 Broker 内部的路由过程，以查找匹配的订阅者。

  • message.forward：如果消息需要传递到集群中另一个节点上的订阅者，此 Span 会追踪消息转发到该节点的过程。它是 message.route 的子 Span。

  • message.handle_forward：在接收节点上，此 Span 追踪对已转发消息的处理。

消息出口 (Broker -> 客户端) ​

  • broker.publish：此 Span 追踪 Broker 准备向订阅者发布消息的过程。它是 message.route 或 message.handle_forward 的子 Span。

QoS 确认 Span ​

这些 Span 追踪 QoS 1 和 QoS 2 的确认流程。

Broker -> 发布者 ​

  • broker.puback：追踪 Broker 向发布者发送 PUBACK 的过程 (QoS 1)。

  • broker.pubrec：追踪 Broker 向发布者发送 PUBREC 的过程 (QoS 2)。

  • broker.pubcomp：追踪 Broker 向发布者发送 PUBCOMP 的过程 (QoS 2)，从而完成来自发布者一方的 QoS 2 流程。

发布者 -> Broker ​

  • client.pubrel：追踪 Broker 从发布者处接收 PUBREL 的过程 (QoS 2)。

Broker -> 订阅者 ​

  • broker.pubrel：追踪 Broker 向订阅者发送 PUBREL 的过程 (QoS 2)。

订阅者 -> Broker ​

  • client.puback：追踪 Broker 从订阅者处接收 PUBACK 的过程 (QoS 1)。

  • client.pubrec：追踪 Broker 从订阅者处接收 PUBREC 的过程 (QoS 2)。

  • client.pubcomp：追踪 Broker 从订阅者处接收 PUBCOMP 的过程 (QoS 2)，从而完成来自订阅者一方的 QoS 2 流程。

规则引擎 Span ​

这些 Span 追踪规则引擎的执行过程。

  • broker.rule_engine.apply：追踪规则引擎处理消息以查看其是否匹配任何规则的过程。这是 message.route Span 的子 Span。

  • broker.rule_engine.action：如果规则匹配，则追踪规则引擎内特定动作的执行。这是 broker.rule_engine.apply 的子 Span。

Broker 内部 Span ​

这些 Span 追踪 Broker 的内部操作。

  • broker.disconnect：追踪 Broker 主动断开客户端连接的情况（例如，由于管理操作导致的断开）。

  • broker.subscribe：追踪由 Broker 自身发起的内部订阅过程（例如，由于管理操作导致的订阅）。

  • broker.unsubscribe：追踪内部取消订阅的过程。

追踪采样和过滤 ​

EMQX 的 OpenTelemetry 集成包含一个灵活的采样器，允许您控制生成哪些追踪。这有助于管理追踪数据的量，并专注于特定的客户端、主题或事件类型。采样决策基于以下层级结构：

  1. 追踪上下文来源 (follow_traceparent): 第一个决策是确定从何处获取初始追踪上下文。这由布尔开关 follow_traceparent 控制。

    • 如果为 true（默认值），EMQX 将尝试从传入的请求中提取追踪上下文（例如，从 MQTT 报文的 traceparent 用户属性中）。这允许您将源自上游已插桩应用程序的追踪链接起来。

    • 如果为 false，EMQX 将忽略任何传入的追踪上下文，并始终启动一个新的追踪。

  2. 远程采样决策: 如果 follow_traceparent 为 true 并且传入的请求包含一个已被标记为“已采样”的追踪上下文，EMQX 将尊重此上游决策并对该追踪进行采样，除非被其他规则覆盖。

  3. 白名单规则: 如果追踪未被远程父级采样，您可以定义特定规则来强制对某些客户端或主题进行采样。这是确保您追踪所关心活动的最直接方法。

    • 按 ClientID: 如果客户端的 ID 在 ClientID 白名单中，其所有根级别的活动（连接、订阅、发布等）都将被追踪。
    • 按 Topic: 如果消息发布到的主题与主题白名单中的过滤器匹配，则该消息的追踪将被采样。

      注意： 此规则适用于追踪的开始（例如 client.publish span）。它不适用于负责向订阅者传递消息的 broker.publish span。

  4. 基于比例的采样: 如果没有匹配的白名单规则，则决策将回退到基于比例的采样，由 sample_ratio 配置控制。

    • sample_ratio：您可以配置此比例（从 0.0 到 1.0）来控制捕获的追踪百分比。值为 1.0 意味着将捕获 100% 的追踪，而 0.0 意味着不会捕获任何追踪（除非它们匹配白名单规则）。

  5. 事件类型开关: 即使追踪被基于比例的采样器选中，只有在对应事件类型的开关被启用时，才会实际生成该追踪。此类开关相当于各类 Span 的全局启用开关。可用的开关包括：

    • client_connect_disconnect：布尔开关，用于启用或禁用客户端连接和断开连接事件的追踪。

    • client_subscribe_unsubscribe：布尔开关，用于启用或禁用客户端订阅和取消订阅事件的追踪。

    • client_messaging：布尔开关，用于启用或禁用客户端消息发布事件的追踪。

    • trace_rule_engine：布尔开关，用于启用或禁用规则引擎的追踪。

  6. 消息追踪级别: 对于与 QoS 确认相关的 Span（例如 PUBACK、PUBREC），您可以使用 msg_trace_level 开关根据 QoS 级别控制它们的创建。

    • msg_trace_level：此设置可以配置为特定的 QoS 级别（0、1 或 2），以根据原始消息的 QoS 控制创建哪些确认 Span。例如，如果 msg_trace_level 设置为 1，将为 QoS 1 消息创建 PUBACK Span。对于 QoS 2 消息，此设置将生成 PUBREC Span，但不会生成 PUBREL 或 PUBCOMP Span。这有助于减少高 QoS 消息流的追踪详细程度。