云消息队列 RocketMQ 版将消息发送、消息存储、消息消费这几个关键节点的数据定义为轨迹参数，例如消息发送结果、发送耗时、消息到达服务端的时间、消息的消费结果、消费耗时、客户端信息等，并支持可视化查询。当消息收发结果不符合预期或您需要对特定消息进行追踪时，您可通过查看消息轨迹获取指定消息在各个环节的处理状态。
消息轨迹数据
云消息队列 RocketMQ 版系统中，一条消息的完整链路包含生产者、服务端、消费者三个角色，每个角色处理消息的过程中都会在轨迹链路中增加相关的信息，将这些信息汇聚即可获取任意消息当前的状态。
使用说明
所有类型的消息正常发送后，即可根据消息的属性在云消息队列 RocketMQ 版控制台上查询到消息的发送轨迹，但查询轨迹需要注意以下几点。
支持查询的时间范围
由于消息在云消息队列 RocketMQ 版中存储的时间默认为3天，即只能查询当前时间起最大3天内的消息轨迹。例如，当前时间是2023年11月30日15:09:48，那么能查询到的消息轨迹最早的时间点为2023年11月27日15:09:48。
消费状态对查询结果的影响
消息类型 | 查询说明 |
没消费前显示尚未消费。消费后会展示投递和消费信息。 | |
没消费前显示尚未消费。消费后会展示投递和消费信息。 | |
如果当前系统时间没有到达指定消费的时间，轨迹可以查询到，但是消息查询不到。 | |
事务未提交之前，轨迹可以查询到，但是消息查询不到。 |
各语言SDK支持消息轨迹的版本
协议 | 语言 | 支持消息轨迹的版本 | 版本说明 |
TCP协议 | Java | 1.2.7.Final及以上版本 | |
C/C++ | 1.1.2及以上版本 | ||
.NET | 1.1.2及以上版本 | ||
HTTP协议 | Node.js | 1.0.2及以上版本 | |
其他多语言 | 1.0.1及以上版本 |
增强版消息轨迹使用条件
增强版消息轨迹功能指的是若您使用的实例及客户端SDK版本符合以下条件，您可在控制台查看更多的轨迹数据，包括消息消费环节的轨迹数据、定时和延时消息及事务消息的相关轨迹数据等，具体的轨迹参数说明，请参见消息轨迹参数说明。
TCP协议Java SDK：
SDK版本：升级至2.x.x.Final版本。
实例所属地域：华东1（杭州）、华北1（青岛）、华北2（北京）、华北3（张家口）、华北5（呼和浩特）、华南1（深圳）、西南1（成都）、德国（法兰克福）和印度尼西亚（雅加达）。
TCP协议C++ SDK：
SDK版本：升级至3.x.x版本。
实例所属地域：所有地域均支持。
使用场景
在生产环境的消息收发不符合预期时，可以通过Message ID、Message Key或Topic的时间范围查询相关的消息轨迹，找到消息的实际收发状态，帮助您快速诊断消息问题。
使用示例
假设您根据业务日志里的信息来诊断某条消息为何一直没有收到，则可以参照以下步骤，利用消息轨迹来排查问题。
收集疑似有问题的消息信息，包括Message ID、Message Key、Topic以及大概的发送时间。
进入云消息队列 RocketMQ 版控制台，根据已有的信息创建查询任务，查询相关的消息的轨迹。
查看结果并分析判断原因。
如果轨迹显示尚未消费，则可以前往Group 管理页面查看消费者状态，确认消息是否因堆积而导致尚未消费。具体步骤，请参见查看消费者状态。
如果发现已经消费，请根据消费端的信息，找到对应的客户端机器和时间，登录客户端机器查看相关日志。
操作入口
登录云消息队列 RocketMQ 版控制台，在左侧导航栏单击实例列表。
在顶部菜单栏选择地域，如华东1（杭州），然后在实例列表中，单击目标实例名称。
在左侧导航栏单击消息轨迹，然后在页面左上角单击创建查询任务。
在弹出的创建消息轨迹查询任务面板中，按需选择查询条件并按提示输入信息，单击确定完成创建。
重要查询时，尽可能精确地设置时间范围，以便缩小查询范围，提高速度。
消息轨迹查询功能支持三种查询方式，具体说明如下：
按 Message ID 查询：该方式属于精确查询、速度快、精确匹配，推荐使用。
按 Message Key 查询：该方式属于模糊查询，最多查询1000条轨迹。仅适用于您没有记录Message ID但是设置了Message Key，同时Message Key具有区分度的情况。
按 Topic 查询：该方式属于范围查询，适用于没有上述Message ID和Message Key，而且消息量比较小的场景。因为时间范围内消息很多，且不具备区分度，所以不推荐使用。
您创建查询任务后，即可在消息轨迹页面查看到刚创建的查询任务，若状态显示查询中，说明暂不能查看消息轨迹。您需要在任务列表的右上角，单击
按钮，直到状态切换至查询完成。
消息轨迹参数说明
以下参数仅当您的实例和客户端SDK版本符合增强版消息轨迹功能的条件时，才能在控制台查看到。具体条件，请参见本文增强版消息轨迹使用条件。
生产者：AccessKey。
MQ Server：到达Server、预设DeliverAt、实际AvailableAt、提交/回滚时间。
消费者：到达消费端、等待处理耗时。
表 1. 消息轨迹参数说明
参数归属 | 参数名称 | 说明 |
基础信息 | Message ID | 消息的全局唯一标识，由云消息队列 RocketMQ 版系统自动生成。 |
Topic | 消息所属的Topic名称。 | |
消息 Key | Message Key，消息的业务标识，由消息生产者设置，唯一标识某个业务逻辑。 | |
消息 Tag | 消息标签，用于区分某Topic下的消息分类。 | |
生产者 | AccessKey | 您的阿里云账号或RAM用户的AccessKey ID，用于标识用户。当您通过SDK或API调用云消息队列 RocketMQ 版资源时，需要使用AccessKey ID进行身份验证。 |
客户端 IP | 消息生产者的客户端IP地址。 | |
消息生产时间 | 消息从生产者发送时的客户端时间戳。 | |
发送 RT | 消息发送的毫秒级耗时。 | |
发送状态 | 请参见消息状态说明中的发送状态。 | |
MQ Server | 消息类型 | 说明 发送的消息为定时消息或延时消息时，消息类型都显示为定时消息。 |
到达Server | 消息到达云消息队列 RocketMQ 版服务端的时间。 | |
预设DeliverAt | 定时消息的预计投递时间。 | |
实际AvailableAt | 消息可被投递到消费端的时间。 | |
提交/回滚时间 | 事务消息提交或回滚的时间。 | |
消费者 | AccessKey | 您的阿里云账号或RAM用户的AccessKey ID，用于标识用户。当您通过SDK或API调用云消息队列 RocketMQ 版资源时，需要使用AccessKey ID进行身份验证。 |
到达消费端 | 消息到达消费者客户端的时间。 | |
等待处理耗时 | 消息到达消费者客户端到消息开始消费时的耗时。 | |
本次投递结果 | 某条消息投递给指定消费者可能要投递多次才会消费成功，该参数表示其中某一次投递的结果。更多信息，请参见消息状态说明中的消费状态。 | |
客户端 IP | 消息消费者客户端的IP地址。 | |
消息处理开始 | 消息开始消费时的客户端时间戳。 | |
消息处理结束 | 消息完成消费时的客户端时间戳。 | |
消息处理耗时 | 消息消费开始到结束的耗时。 |
在消息轨迹的任务列表页，单击某任务操作列的查询结果会显示消息的发送状态和消费状态；具体的消息轨迹详情中的生产者和消费者区域也会分别显示消息的发送和消费状态。这些状态的说明如下：
表 2. 消息状态说明
状态类型 | 状态参数 |
发送状态 | 发送成功 |
发送失败 | |
消息定时中 | |
事务未提交 | |
事务回滚 | |
消费状态 | 全部成功 |
部分成功 | |
全部失败 | |
尚未消费 | |
消费结果未返回 | |
消费成功 | |
消费失败 |
消息轨迹常见问题
为什么查询不到消息轨迹？
检查客户端的SDK版本是否正确。具体支持的版本，请参见各语言SDK支持消息轨迹的版本。
查询的时间范围是否正确。
由于消息在云消息队列 RocketMQ 版中存储的时间默认为3天，即只能查询当前时间起最大3天内的消息轨迹。例如，当前时间是2023年11月30日15:09:48，那么能查询到的消息轨迹最早的时间点为2023年11月27日15:09:48。
重要由于轨迹存储空间不足，可能导致轨迹数据发生滚动，从而无法保存完整的三天轨迹数据。若需保存完整的三天轨迹，建议采用铂金版实例固定存储大小。
由于消息轨迹采用异步链路，因此，不保证轨迹数据一定完整。当查询条件正确时，仍会有小概率查询不到结果，请以实际业务消费情况为准，您可以通过查看客户端日志获取详细状态。具体信息，请参见日志配置。
相关文档
除了控制台，云消息队列 RocketMQ 版还支持通过API接口查询消息轨迹。