云消息隊列 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接口查詢消息軌跡。