消息轨迹是指一条消息从生产者发送到消息队列 RocketMQ 版服务端，再到消费者消费处理，整个过程中的各个相关节点的时间、状态等数据汇聚而成的完整链路信息。该轨迹可作为生产环境中排查问题强有力的数据支持。本文介绍消息轨迹的使用场景、查询步骤以及查询结果的参数说明。

消息轨迹数据

消息队列 RocketMQ 版系统中，一条消息的完整链路包含生产者、服务端、消费者三个角色，每个角色处理消息的过程中都会在轨迹链路中增加相关的信息，将这些信息汇聚即可获取任意消息当前的状态。

轨迹数据

使用场景

在生产环境的消息收发不符合预期时，可以通过 Message ID、Message Key 或 Topic 的时间范围查询相关的消息轨迹，找到消息的实际收发状态，帮助诊断问题。

使用场景

使用示例

假设您根据业务日志里的信息来诊断某条消息为何一直没有收到，则可以参照以下步骤，利用消息轨迹来排查问题。

  1. 收集疑似有问题的消息信息，包括 Message ID、Message Key、Topic 以及大概的发送时间。
  2. 进入消息队列 RocketMQ 版控制台，根据已有的信息创建查询任务，查询相关的消息的轨迹。
  3. 查看结果并分析判断原因。
    • 如果轨迹显示尚未消费，则可以前往 Group 管理页面查看消费者状态，确认消息是否因堆积而导致尚未消费。具体步骤请参见查看消费者状态。
    • 如果发现已经消费，请根据消费端的信息，找到对应的客户端机器和时间，登录客户端机器查看相关日志。

使用说明

消息轨迹的使用不会增加额外的接入成本。所有类型的消息正常发送后，即可根据消息的属性在消息队列 RocketMQ 版控制台上查询到消息的发送轨迹，但消费轨迹需要注意以下几点。

消息类型 查询说明
普通消息 没消费前显示尚未消费。消费后会展示投递和消费信息。
顺序消息 没消费前显示尚未消费。消费后会展示投递和消费信息。
定时和延时消息 如果当前系统时间没有到达指定消费的时间，轨迹可以查询到，但是消息查询不到。
事务消息 事务未提交之前，轨迹可以查询到，但是消息查询不到。

查询消息轨迹

由于消息在消息队列 RocketMQ 版中存储的时间默认为 3 天（不建议修改），即只能查询从当前查询时间算起 3 天内的消息轨迹。例如，当前时间是 2019 年 6 月 10 日 15:09:48，那么能查询到的消息轨迹最早的时间点为 2019 年 6 月 7 日 15:09:48。

前提条件

  • 请确保您的 SDK 版本支持消息轨迹功能，具体说明如下：
    • TCP 协议下，支持通过 Message ID、Message Key 或 Topic 的时间范围查询相关的消息轨迹。
    • HTTP 协议下，仅支持通过 Message ID 查询相关的消息轨迹。

      除 Node.js SDK 需为 v1.0.2 及以上版本外，其余语言的 SDK 均需为 v1.0.1 及以上版本。详情请参见消息队列 RocketMQ 版HTTP SDK 库。

  • 您的消息已从生产者发送。
操作步骤
  1. 登录消息队列 RocketMQ 版控制台。在顶部菜单栏，选择所需查询的消息所在实例的地域（Region），如华东1（杭州）。
  2. 在实例列表页面，找到目标实例，在其操作列，单击详情。
  3. 在左侧导航栏，选择消息轨迹 > 创建查询任务。
  4. 在弹出的创建查询任务对话框中，按需选择查询条件并按提示输入信息，单击确认完成创建。
    注意 查询时，尽可能精确地设置时间范围，以便缩小查询范围，提高速度。
    消息轨迹查询功能支持三种查询方式，具体说明如下：
    • 按 Message ID 查询：该方式属于精确查询、速度快、精确匹配，推荐使用。按 Message ID 查询
    • 按 Message Key 查询：该方式属于模糊查询，最多查询 1000 条轨迹。仅适用于您没有记录 Message ID 但是设置了 Message Key，同时 Message Key 具有区分度的情况。按 Message Key 查询
    • 按 Topic 查询：该方式属于范围查询，适用于没有上述 Message ID 和 Message Key，而且消息量比较小的场景。因为时间范围内消息很多，且不具备区分度，所以不推荐使用。按 Topic 查询

    您创建查询任务后，即可在消息轨迹页面查看到刚创建的查询任务，且任务状态显示查询中，说明暂不能查看消息轨迹。

  5. 在消息轨迹的任务列表的右上角，单击refresh按钮，直到状态切换至查询完成。单击 添加 图标。

    查看到的轨迹的简要信息如下所示，主要是消息本身的属性以及接收状态的信息。

    接收状态信息
  6. 在展开的区域中，单击查看轨迹即可查看完整的链路图。

    在 TCP 协议下按 Message ID 查询普通消息的轨迹示例如下。

    消息轨迹

    对于 Message Key 和 Topic 查询方式，如果匹配到多条轨迹，可以进行上下翻页，查看比对轨迹数据。

查询结果说明

消息轨迹链路图中的部分关键字段的解释如下。

表 1. 消息轨迹名词解释
链路部分 字段 说明
生产者 发送时间 消息从生产者发送时的客户端时间戳。
发送耗时 生产者调用 Send 方法发送消息的毫秒耗时。
Topic Region 消息存储的地域。
消费者 耗时 消息推送到客户端之后执行 consumeMessage 方法的耗时。
投递时间 客户端执行 consumeMessage 方法开始消费消息时的时间戳。

在消息轨迹的任务列表页，单击某任务的 添加 图标会显示消息的发送状态和消费状态；而消息轨迹链路图中的生产者和消费者信息区域也会分别显示消息的发送和消费状态。这些状态字段及其解释如下。

表 2. 状态信息说明
发送/消费状态 状态字段 说明
发送状态 发送成功 消息发送成功，服务端已经存储成功。
发送失败 消息发送失败，服务端没有存储消息，需要重试。
消息定时中 该消息是定时或者延时消息，且尚未到达投递时间。
事务未提交 该消息是事务消息，且尚未提交状态。
事务回滚 该消息是事务消息，并且已经回滚。
消费状态 全部成功 该消息的所有投递都已成功消费。
部分成功 该消息投递中存在消费失败的情况，或消费失败并重试成功的情况。
全部失败 该消息的所有投递都消费失败。
尚未消费 该消息尚未投递给任何消费方。
消费结果未返回 消费消息的方法尚未返回结果，或者被中断，导致本次消费结果未传回服务端。
消费成功 该消息已被成功消费。
消费失败 消费消息的方法主动返回失败标志，或者是消费方法抛异常。

更多信息

  • 如需删除某个查询任务，可在消息轨迹任务列表页找到需删除的任务，在其操作列，单击 删除 图标，按提示完成删除。
  • 如果对消息轨迹的查询结果有疑问，请参见常见问题中的为什么查询不到轨迹数据。