概述
本文档介绍MQ消息轨迹功能的使用，主要内容包括消息轨迹基本原理，使用场景，使用指南，使用案例。对于消息轨迹的查询结果有疑问请参考FAQ部分文档。
1.基本原理
定义：消息轨迹指的是一条消息从生产方发出到消费方消费处理，整个过程中的各个相关节点的时间地点等数据汇聚而成的完整链路信息。
基本思路：从MQ系统中，一条消息的完整链路包含生产方，服务方，消费方三个角色，每个角色处理消息的过程中都会在轨迹链路中增加相关的信息，将这些信息汇聚即可获取任意消息当前的状态，从而为生产环境中的问题排查提供强有力的信息支持。
消息轨迹的数据包含：
发送方信息：
- 发送方客户端信息
- 发送时间
- 发送成功与否
- 发送耗时
- …
服务方信息：
- 消息存储位置
- 消息存储时间
- 消息本身的属性
- …
接收方信息：
- 接收方客户端信息
- 投递信息（第几次投递，投递时间）
- 消费成功与否
- 消费耗时
- …
2. 消息轨迹的使用场景
消息轨迹功能一般在生产环境的消息收发不符合预期时排查问题使用。通过消息的一些属性（MessageID，MessageKey，Topic）搜索相关的消息轨迹，找到关心的消息的实际收发状态，帮助诊断问题。
消息轨迹的使用方场景：
3.使用指南指南
消息轨迹的使用对于业务方不会增加额外的接入成本，仅仅需要确保客户端SDK版本支持该特性。正常收发消息后以消息的相关属性在MQ控制台上查询即可。
3.1 接入条件
要使用消息轨迹功能，必须确保Java客户端版本至少是1.2.2，低版本并不支持，因此需要首先升级客户端。详细的客户端信息，请参考SDK下载页面，获取最新的SDK。下载链接请点击此处。
3.2 新建轨迹查询
登录MQ控制台，点击消息轨迹功能（现处于公测阶段），点击右上角新建查询按钮。
消息轨迹查询功能支持三种查询方式，请按照对应方式输入查询条件，新建查询。
- 根据MessageID查询：需要输入消息的唯一MessageID，Topic名称以及消息的大致发送时间。
- 根据MessageKey查询：需要输入消息的MessageKey和Topic以及大致发送时间，适用于没有记录MessageID，但记录了MessageKey的场景。
- 根据Topic查询：仅仅输入Topic和时间段，批量查询，适用于没有上述MessageID和MessageKey，而且消息量比较小的场景。
注意：
- 查询时，尽可能设置最为精确的时间区间，以便缩小查询范围，提高速度。
- 根据MsgID查询属于精确查询，速度快，精确匹配，推荐用户使用。
- 根据MsgKey查询属于模糊查询，仅适用于业务方没有记录MessageID但是设置了MessageKey，同时MessageKey具有区分度的情况，MessageKey查询最多查询1000条轨迹。
- 根据Topic分段查询属于范围查询，不推荐使用，因为时间范围内消息很多，不具备区分度。
3.3 查询任务管理
新建查询后，会生成一个查询任务，MQ后台会异步执行，并将任务状态反馈到管理页面，查询结束时，任务状态显示查询完成，否则显示查询中。
根据任务的状态可以选择查看轨迹，或者删除查询任务。
3.4 查看轨迹
点击查看轨迹按钮，查看轨迹，如果发现没有结果，请参考弹窗链接，排查原因。
如果查询到轨迹信息，可以看到轨迹的简要信息，主要是消息本身的属性以及接收状态的统计，如下图所示：
3.5 查看轨迹链路图
点击查看轨迹按钮即可查看完整的链路图，如图所示：
消息链路图包含4个部分：
- 生产者信息
- Topic信息
- 消费者信息
- 详情信息
各个字段区域均可以通过鼠标悬停的方式获取详细信息。对于MsgKey和Topic查询方式，如果匹配到多条轨迹，可以进行上下翻页，查看比对轨迹数据。
3.6 消息轨迹名词解释
消息轨迹查询页面中涉及到的名词概念列表如下。
| 相关概念 | 含义 |
|---|---|
| 发送成功 | 消息发送成功 |
| 发送失败 | 消息发送失败 |
| 消息定时中 | 该消息是定时或者延时消息，且尚未到达投递时间 |
| 事务未提交 | 该消息是事务消息，且尚未提交状态 |
| 事务回滚 | 该消息是事务消息，并且已经回滚 |
| 全部成功 | 该消息所有投递都已成功消费 |
| 部分成功 | 该消息投递中存在消费失败并重试成功的情况 |
| 尚未消费 | 该消息尚未投递给任何消费方 |
| 发送时间 | 记录消息从发送端发送时的客户端时间戳 |
| 发送耗时 | 记录发送端调用send方法发送消息的毫秒耗时 |
| Region | 记录消息存储的Region信息，或者消费方机器所在的Region信息 |
| 消费耗时 | 记录消息推送到客户端之后执行consumeMessage方法的耗时 |
| 投递时间 | 记录客户端执行consumeMessage方法开始消费消息时的时间戳 |
4.消息轨迹使用案例
本部分文档介绍消息轨迹的一些使用案例，推荐用户参考以下的场景，利用消息轨迹来排查MQ问题。
4.1 业务上有一条消息一直没有收到怎么办？
业务方如果根据业务日志里的信息判断某条消息一直没有没有收到，此时可以使用消息轨迹工具来确认该情况。
Step1：收集怀疑的消息的信息，MessageID,MessageKey，Topic以及大概的发送时间范围。
Step2：进入MQ控制台，根据已有的信息新建查询任务，查询相关的消息的轨迹。
Step3：查看结果。并分析判断原因，如果轨迹显示尚未消费，则可以去订阅管理页面查询，确认是否有堆积导致消息尚未消费。
Step4：如果发现已经消费，请根据消费端的信息，找到对应的客户端机器和时间，登录查看相关日志。
企业级互联网架构Aliware，让您的业务能力云化：https://www.aliyun.com/aliware
