edit-icon download-icon

Query message traces

Last Updated: Jun 26, 2018

The use of message tracing does not add extra access cost. You only needs to ensure that this feature is supported by the current version of your client SDK. After you start sending and receving messages normally, you can query the message traces on the MQ console.

1. Access conditions

The message tracing function currently supports Java clients (version 1.2.7 and higher), C++, and .NET clients. For detailed client information, check the upgrade prompt in the console, and upgrade your client SDK to the latest version.

2. Create a trace query job

In the left-side navigation pane of the MQ console, select Message Tracing, and then click the Create Query Job button in the upper right corner of the page.

The message tracing function supports three query types. Please select a query method, and then specify the corresponding conditions for the query. Instructions for the three query methods are as follows:

  • Message-ID-based query: You must specify the unique message ID of a message, the topic name, and the approximate sending time of the message (a time range).
  • Message-key-based query: You must specify the message key, the topic, and the approximate sending time (a time range). This query method is suitable for the scenario where the message ID is not recorded but the message key is.
  • Topic-based query: You must specify the topic and the message’s approximate sending time (a time range) for batch query. The query method is suitable for the scenario where there is no message ID or message key and the volume of messages is relatively small.


  • Set the time range as accurate as possible to narrow the query scope and increase the query speed.
  • Message-ID-based query is a precise query. It is fast to find the exact match, therefore, this query method is recommended.
  • Mesage-key-based query is a fuzzy query, and is suitable for the scenario where the message ID is not recorded but a business-distinctive message key is set. A maximum of 1,000 traces can be displayed for a mesage-key-based query.
  • A topic-based query is a range query. It is not recommended because there are a great number of messages within a time range, and it is not easy to quickly find the one you are looking for.

3. Manage query jobs

After you created a query job, MQ backend will execute the query job asynchronously, and send the execution status back to the Query Jobs page. When the query job is completed, Query Complete will be displayed in the Job Status column; otherwise, Querying will be displayed.

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

4. View traces

After completing the query, click Details to view the message trace. If you do not see any result, refer to the link provided in the pop-up to troubleshoot the problem.

If the trace is queried out, you can see the trace’s brief information, including the message’s attributes and its sending and receiving status.

5. View trace diagram

Click View Trace to see the complete trace diagram.

The message trace diagram consists of 3 parts:

  • Producer information
  • Topic information
  • Consumer information

For message-key-based and topic-based queries, if multiple traces are matched, you can scroll up and down the page to compare the traces.

Glossary for message tracing

The terms that appear in the message trace page are as follows.

Term Meaning (TCP scenario)
Sending time Record the client’s time stamp when a message was sent from the sender
Sending duration Record the time elapsed in milliseconds when the sender calls the send method to send a message
Region Record the region where a message is stored, or the region where the consumer instance is located
(Consumption) duration Record the time it takes for the client to execute the consumeMessage method after the message is pushed to the client
Delivery time Record the time stamp when a client executes the consumeMessage method to consume a message

Status description

The statuses that may be displayed in the message tracing page are as follows.

Status Meaning (TCP scenario)
Sent Successfully The message is sent successfully, and is stored in the server successfully.
Sending Failed The message is failed to be sent, and is not stored in the server. Please try again.
Message Standing By The message is a scheduled or delayed message, and the delivery time is not reached yet.
Transaction Uncommitted The message is a transactional message and has not been committed yet.
Transaction Rolled Back The message is a transactional message and has been rolled back.
All Succeeded All deliveries of the message have been successfully consumed.
Partially Succeeded Certain deliveries of the message failed,or later succeeded after retries
Not Consumed The message has not been delivered to any consumer.
Consumption Result Unreturned The message consuming method has not returned any result yet, or has been interrupted, and therefore, the consumption status is not returned to the server.
Consumption Failed The message consuming method returned a failure result, or the consuming method threw an exception.

If you have any questions about the result of a trace query, see Message tracing in “FAQ”.

Thank you! We've received your feedback.