Query message traces

Last Updated: Mar 08, 2018

The use of message tracing does not increase access costs on the business side, and it only needs to ensure that this feature is supported by the client SDK version. After a message is sent or received normally, relevant properties of the message can be queried on the MQ console.

1. Access conditions

The message tracing function currently supports Java clients (versions 1.2.7 and later), C++, and .NET clients. For detailed client information, please refer to the upgrade prompt provided by the console for the latest SDK.

2. Create a trace query

Select Message Tracing in the left-side navigation pane of the MQ console, select the region, and click the New Query button in the top right corner.

The message tracing function supports three query modes. Please enter the query conditions according to the corresponding mode for a new query. Specific descriptions of the three query modes are as follows:

  • Message-ID-based query: it needs to enter the unique message ID of a message, the Topic name, and the approximate sending time of the message.
  • Message-key-based query: it needs to enter the message key of a message, the Topic, and the approximate sending time; applicable to scenarios where the message ID is not recorded but the message key is recorded.
  • Topic-based query: only enter the Topic and the time period for batch query; applicable to scenarios where there is no message ID and message key and the amount of messages is relatively small.


  1. Set the time interval as accurate as possible during query to narrow the query range and increase the speed.
  2. Message-ID-based query is a precise query, and is fast for exact matches. It is recommended for use.
  3. Mesage-key-based query is a fuzzy query, and only applicable to scenarios where the business side does not record the message ID but sets the message key and the message key has a distinction. A maximum of 1,000 traces can be queried by mesage-key-based query.
  4. Topic-based query with period is a range query, and is not recommended for use because there are a great number of messages within a time range and a distinction is not provided.

3. Manage query tasks

After creating a new query, a query task will be generated. The MQ backend will execute it asynchronously, and feed back the task status to the Query Management List page. When the query is completed, Query Completed will be displayed in Task Status; otherwise, Querying will be displayed.

Depending on the task status, you can choose to view the trace or delete the query task.

4. View traces

After completing the query, click the Details button in the right action options to view the trace. If you find no result, please refer to the pop-up link to troubleshoot.

If trace information has been queried, you can see the brief information of the trace, mainly the attributes of the message itself and statistics of the receiving status.

5. View trace diagrams

Click the View Trace button to see the complete link diagram.

The message link diagram consists of 4 parts:

  • Producer information
  • Topic information
  • Customer information
  • Details

The mouse can hover over each field area for detailed information. For message key-based and Topic-based query modes, if multiple traces are matched, you can page up and down to view and compare the trace data.

Glossary for message tracing

The list of terms and concepts involved in the message tracing page is as follows.

Related concepts Meaning (TCP scenario)
Sending time Record the client’s time stamp when a message was sent from the sender
Elapsed sending time Record the time elapsed in milliseconds as the sender calls a sending method to send a message
Region Record information of a region where a message is stored, or information of a region where a consumer’s machine is located
Elapsed consumption time Record the time elapsed for executing a consumeMessage method after the message is pushed to the client
Delivery time Record the timestamp when a client executes the consumeMessage method to start to consume a message

Message trace status description

The list of statuses involved in the message tracing page is as follows.

Related concepts Meaning (TCP scenario)
Sent successfully The message is sent successfully, and the server has stored it successfully
Failed to send The message failed to be sent, and the server did not store it. You needs to try again
Message standing by The message is a scheduled or delayed message, and the delivery time has not been reached yet
Transaction uncommitted The message is a transactional message and has not been committed yet
Transaction rollback The message is a transactional message and has been rolled back
All succeeded All deliveries of the message have been successfully consumed
Partially succeeded Some deliveries of the message failed and has been retried successfully
Unconsumed The message has not been delivered to any consumer
Consumption unreturned The message consuming method has not returned yet, or it was interrupted, resulting in the result of this consumption being not returned to the server
Consumption failed The message consuming method initiatively returns a failure sign, or the consuming method throws an exception

If you have any question about the query result of a message trace, you can also refer to Message tracing in “FAQ”.

Thank you! We've received your feedback.