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

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

  7. 在消息轨迹的任务列表的右上角，单击refresh按钮，直到状态切换至查询完成。在目标任务的操作列单击查询结果。

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

    message_trace_state
  8. 在展开的区域中，单击消息轨迹即可查看完整的链路图。

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

    message_trace_detail

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

查询结果说明

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

表 1. 消息轨迹名词解释
链路部分 字段 说明
生产者 发送时间 消息从生产者发送时的客户端时间戳。
发送耗时 生产者调用Send方法发送消息的毫秒耗时。
消费者 共投递次数 消息被消费者成功消费前，生产者一共投递的次数。

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

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

更多信息

  • 如需删除某个查询任务，可在消息轨迹任务列表页找到需删除的任务，在其操作列单击更多，然后在下拉菜单中，选择删除。
  • 如果对消息轨迹的查询结果有疑问，请参见常见问题中的为什么查询不到轨迹数据。