RocketMQNotes

第 12 章：消息轨迹

zjc 于 2026-01-12 发布

这是《RocketMQ 零基础实战指南》的独立章节版。本章从概念、实操和生产排查三个视角展开，代码块保留了原书可直接运行的版本。 消息轨迹记录消息从生产、存储到消费的全过程，是定位“是否发出、何时入队、谁消费、是否重试”的关键数据。没有轨迹，消息问题往往只能靠日志和时间猜测。

12.1 轨迹内容

一条完整轨迹通常包含：

阶段 信息
Produce Topic、Tag、Key、生产组、客户端 IP、耗时、结果
Broker 存储时间、Broker、QueueId、Offset、消息大小
Consume 消费组、客户端 IP、线程、耗时、结果、重试次数
Exception 错误码、异常、失败时间

示意：

10:00:00.100 producer 10.1.1.10 send success cost=8ms
10:00:00.104 broker-a queue=3 offset=10001 store
10:00:00.150 consumer 10.1.2.20 pull success
10:00:00.170 consumer 10.1.2.20 consume success cost=15ms

12.2 开启轨迹

生产者：

DefaultMQProducer producer = new DefaultMQProducer(
        "order-producer-group", true);
producer.setNamesrvAddr("rocketmq-namesrv:9876");
producer.start();

消费者 API 随版本差异较大，常见方式是在构造函数或 DefaultMQPushConsumerImpl 中启用轨迹开关。使用前应确认客户端版本对应 API，避免复制不同版本的示例。

开启轨迹会带来额外消息和磁盘开销，生产环境应评估采样率与保留周期。

12.3 轨迹 Topic

轨迹默认写入系统 Topic，常见名称类似：

RMQ_SYS_TRACE_TOPIC

治理要点：

  1. 控制保留时间；
  2. 监控轨迹 Topic 磁盘；
  3. 不让业务 Topic 与轨迹 Topic 互相抢占关键磁盘；
  4. 高吞吐系统可采样；
  5. 关键链路全量开启；
  6. 将轨迹导出到日志或观测平台。

12.4 查询方式

按消息 Key 查询：

Key: O202608250001

推荐消息契约中携带：

message key = orderNo
user property traceId = 7f0c...
user property eventId = 01J8...

这样可以把 RocketMQ 轨迹、应用日志和链路追踪串起来：

traceId
  -> gateway log
  -> order service log
  -> RocketMQ message
  -> consumer log
  -> inventory service log

12.5 问题定位

消息未到达 Broker

检查：

  1. 生产者是否调用成功；
  2. SendStatus 是否为 OK；
  3. Topic 和环境是否正确；
  4. 网络是否超时；
  5. ACL 是否通过；
  6. 本地事件表是否有记录。

Broker 有消息但未消费

检查：

  1. 消费组是否在线；
  2. 订阅关系是否一致；
  3. Tag 过滤是否排除；
  4. 队列是否分配；
  5. 消费位点是否落后；
  6. 是否处于重试挂起。

已拉取但业务未生效

检查：

  1. 消费结果；
  2. 消费耗时和异常；
  3. 业务事务是否提交；
  4. 幂等是否提前返回；
  5. 下游是否失败；
  6. 是否死信。

12.6 采样设计

链路 建议
支付、订单 全量
用户行为 采样
日志类事件 可关闭或低采样
异常消息 强制全量
灰度服务 全量

示例规则：

boolean sample = isCriticalEvent(event) || random.nextInt(100) < 10;

异常和重试消息应始终保留轨迹，否则最需要定位的时刻反而缺数据。

12.7 安全与合规

轨迹可能包含业务标识、账号、手机号或错误详情：

  1. 敏感字段脱敏；
  2. 不把完整报文无限制写入轨迹；
  3. 控制查询权限；
  4. 设置保留周期；
  5. 记录轨迹查询审计；
  6. 导出外部系统时继续执行访问控制。

12.8 常见问题

问题 排查
轨迹为空 客户端未开启、Broker 不支持、权限不足
只有生产没有消费 消费组、订阅、位点、过滤问题
只有拉取没有结果 消费线程异常或进程退出
查询不到 Key 生产未设置或时间范围错误
轨迹延迟 轨迹 Topic 积压或查询系统延迟
磁盘增长快 全量开启且保留过长

本章小结

消息轨迹把生产、存储、拉取、消费和异常串成一条可查询的时间线。开启前要评估开销，开启后要控制敏感信息、采样率、保留周期和查询权限。定位问题时，用同一业务键和 traceId 贯穿 RocketMQ 与应用日志，效率最高。

思考题

  1. 轨迹能证明哪些“没有发生”的事实？
  2. 为什么异常消息应强制保留轨迹？
  3. 轨迹 Topic 的磁盘如何治理？
  4. traceId 和消息 Key 如何配合？
  5. 轨迹中哪些字段需要脱敏？