新功能发布记录
消息轨迹
引言
消息队列 MQTT 版（TDMQ MQTT）提供的消息轨迹功能，能够将业务上下游信息完整串联，帮助您更好地排查异常信息，定位问题。它记录了消息从生产者发送到服务端，再由服务端投递给消费者的全生命周期。本文将介绍消息轨迹的核心概念、关键参数定义，并重点介绍如何利用轨迹数据进行可观测性分析，快速定位“消息未收到”、“消费延迟”等典型故障.
什么是消息轨迹
定义
消息轨迹是指一条消息从生产者发送到云消息队列 TDMQ MQTT 版服务端，再到消费者消费，整个过程中的各个相关节点的时间、执行结果、生产者 IP、消费者 IP 等详细信息汇聚而成的完整链路信息。如果消息收发不符合预期，您可以通过查询消息轨迹，快速分析和定位问题，及时恢复业务。
组成
一条完整的 MQTT 消息轨迹由以下两部分组成：
消息生产轨迹：记录生产者向 Broker 发送消息的过程。
核心关注：生产端是否成功发送？服务端是否成功接收？
消息消费轨迹：记录 Broker 向所有匹配订阅的消费者投递消息的过程。
核心关注：有哪些消费者订阅了该主题？消息是否成功推送到客户端？客户端是否返回了确认（ACK）？
消息轨迹使用场景
消息队列 MQTT 版支持查询消息收发流程中的关键数据，通过查看轨迹信息可快速获取当前业务处理的状态，帮助您快速定位异常问题。
消息轨迹的典型应用场景如下：
场景一：查看某条消息是否发送成功或是否消费成功。
确认消息是否由设备成功发出。
确认服务端是否接收并持久化。
确认消费者是否在线且在订阅列表中。
场景二：查看消费进程是否正常。
对比“服务端接收时间”与“投递给消费者的时间”。
检查 QoS 交互流程是否完整（例如 QoS 1 是否缺少 PUBACK）。
场景三：查看生产者、消费者身份信息，进一步排查问题原因。
查看实际收发消息的 Client ID 和 IP 地址，排除非法连接或客户端 ID 混用的问题。
通过消息轨迹排查消费异常实践
路径一：消息视角全链路排查
适用场景：已知某条消息（Message ID）或大概的发送时间，想要确认这条消息被哪些设备消费了，或者为何没被消费。
入口：控制台 > 消息查询 > 消息轨迹。
查看某条消息的消息轨迹
前往消息查询页面，确定目标集群、Topic（需要填写准确的Topic Name 或订阅时的 Topic Filter ）和时间范围后搜索目标消息：
选择具体的某个消息 ID，并单击查看详情，可查看详细的消息轨迹。
在消息视角全链路排查中可以根据以下现象进行判断及排查：
检查“消息生产”
现象 | 判断 | 排查/解决建议 |
搜不到该消息轨迹 | 消息未到达服务端 | 1. 检查设备网络是否连通。 2. 检查设备端代码是否捕获到发送异常。 3. 确认设备发送的 Topic 与查询的 Topic 是否严格一致。 |
请求结果：失败 | 服务端拒绝接收 | 1. 检查设备是否有发布该 Topic 的权限（ACL）。 2. 检查消息体大小是否超过服务端限制。 |
请求结果：成功 | 生产正常 | 生产者正常，若有问题可能出在消费链路 |
检查“消息消费”
现象 | 判断 | 排查/解决建议 |
列表中找不到目标 Client ID | 消费者运行异常，导致消息无法消费到。 | 1. 检查 Topic Filter：消费端的订阅规则（通配符）是否能匹配当前消息的 Topic？ 2. 检查订阅状态：确认消费端在消息发送时是否处于在线订阅状态（或建立了持久会话）。 |
列表中有Client ID，但请求结果：失败 | 云端推送失败，消费者未收到队列的消息推送。 | 1. 检查消费端设备是否离线 2. 检查消费端网络状况（弱网环境）。 |
最后推送时间 >> 生产时间 (时间差很大) | 消费堆积/延迟 | 1. 消费端处理逻辑过慢，阻塞了 MQTT 线程。 2. 客户端频繁上下线导致消息在服务端排队。 3. 若使用了共享订阅：查看共享订阅组的消费者个数是否合理 |
QoS Packet 不闭环 | QoS 确认异常 | 对于消息生产和消息消费过程，消息轨迹详细展示各个请求Packet 的请求结果和时间 QoS 0 正常流程：服务端推送 PUBLISH 若请求失败，可能是TCP连接不稳定导致 QoS 1 消息 正常流程：服务端推送 PUBLISH -> 客户端回复 PUBACK。 若只有 PUBLISH 无 PUBACK，即客户端收到了消息，但未向服务端返回确认。服务端会认为发送失败并不断重试，导致消息重复或阻塞。 QoS 2 消息 正常流程：PUBLISH -> PUBREC -> PUBREL -> PUBCOMP。 流程中断在中间任意环节时，可判断通常是网络链路不稳定导致确认报文丢失。 |
路径二：客户端视角排查
适用场景：关注特定设备（例如设备 A 反馈收不到指令，或数据上报不成功），需要查看该设备所有的收发记录。
入口：控制台 > 客户端管理 > 单击具体 Client ID > 客户端消息轨迹 Tab 页。
查看某个客户端消息轨迹
前往客户端管理页面，搜索相应客户端 ID。
单击查看详情，查看对应客户端基本信息，Session 详情。
在 Tab 页中可选择查看客户端消息轨迹。
在此视图下，系统会筛选出所有与该设备有关的轨迹，包括它发送的（作为生产者）和接收的（作为消费者）消息。
生产者（Producer）：代表该设备向云端上报数据的记录。
消费者（Consumer）：代表云端向该设备下发指令/推送消息的记录。
生产者问题
1. 筛选或寻找“客户端类型”为生产者的记录，确认消息是否成功发送到 MQTT 实例
2. 找不到符合条件的“生产者”记录，检查生产者代码的参数是否正确，设备端发起网络请求是否成功。
若根据上述几个方法查到消息确实已经被消息队列 MQTT 版服务端存储，则可以重点排查后续的消息消费过程是否存在异常。
消费者问题
如果您怀疑设备收不到指令，请筛选或寻找“客户端类型”为消费者的记录：
列表中没有“消费者”记录
结论：云端没有给该设备推过消息。
原因：可能是设备掉线了（Broker 认为不在线就不推了），或者是发布者发错 Topic 了（导致没匹配上该设备的订阅）。
有记录，但单击查看详情发现没有 ACK
结论：云端推了，设备也（可能）收到了，但设备卡死了没回复确认。
建议：检查设备端业务逻辑是否阻塞了 MQTT 客户端线程。
附：消息轨迹相关参数说明
消息生产参数（上行链路）
参数 | 说明 | 排查要点 |
请求时间 | 发布者客户端（Producer）向服务端发出请求 Packet 的时间点 | 消息的开始生产时间。 |
请求 Packet 类型 | 请求 Packet 报文类型： PUBLISH：发布消息 PUBACK：发布确认，对 QoS 1 等级的 PUBLISH 报文的确认响应。 PUBREC：发布已收到，QoS 2 等级的第一步确认，表示已收到一个 QoS 2 消息。 PUBREL：发布释放，QoS 2 等级的第二步，是发送方对 PUBREC 的响应，表示请求释放之前已初步确认的消息。 PUBCOMP：发布完成，QoS 2 等级的最后一步确认，表示整个 QoS 2 消息的传输流程已全部完成。 | PUBLISH: 正在发送消息。 PUBACK: QoS 1 的确认。 |
客户端 ID | 发布这条消息的客户端唯一标识符，用于追踪消息的来源。 | 用于确认来源，排除“脏数据”。 |
QoS | 消息的服务质量等级，决定了消息传递的可靠性和保证程度，包括 0（最多一次）、1（至少一次）、2（恰好一次）。 | 决定了消息传递的可靠性机制。 |
请求结果 | 服务端对这条消息发布请求的处理结果。 | 成功: 服务端已接收。 失败: 发送被拒绝。 |
消息消费参数（下行链路）
参数 | 说明 | 排查要点 |
客户端 ID | 服务端投递这条消息的目标客户端唯一标识符。 | 如果此处没有您预期的 ID，说明该设备未订阅成功。 |
QoS | 消息的服务质量等级，决定了消息传递的可靠性和保证程度，包括 0（最多一次）、1（至少一次）、2（恰好一次）。 | 决定了消息传递的可靠性机制。 |
最后推送时间 | 服务端最后一次向该客户端推送此消息的时间点。 | 如果此时间一直在更新，说明服务端正在重试投递。 |
请求结果 | 服务端投递这条消息的最终结果。 | 成功: 流程闭环。 失败: 需展开详情查看具体卡在哪个 Packet。 |
单击客户端 ID 下方的右三角，可以查看服务端推送此消息的请求详情。
参数 | 说明 | 排查要点 |
请求时间 | 服务端向目标客户端（Consumer）发出请求 Packet 的时间点 | 消息的开始消费时间 |
请求 Packet 类型 | 请求 Packet 报文类型： PUBLISH：发布消息 PUBACK：发布确认，对 QoS 1 等级的 PUBLISH 报文的确认响应。 PUBREC：发布已收到，QoS 2 等级的第一步确认，表示已收到一个 QoS 2 消息。 PUBREL：发布释放，QoS 2 等级的第二步，是发送方对 PUBREC 的响应，表示请求释放之前已初步确认的消息。 PUBCOMP：发布完成，QoS 2 等级的最后一步确认，表示整个 QoS 2 消息的传输流程已全部完成。 | 结合生产时间可计算端到端延迟。 |
请求结果 | 客户端对这条消息投递请求的处理结果。 | 重点观察是否有ACK类报文返回。 |
文档反馈