edit-icon download-icon

Query message traces

Last Updated: Dec 24, 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 message 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 Details. In the unfolded area, 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 diagram are as follows.

Category Term Description
Producer Sending time The client’s time stamp when a message was sent from the sender
Producer Sending duration The time elapsed in milliseconds when the sender calls the send method to send a message
Topic Region The region where a message is stored
Consumers Duration The time it takes for the client to execute the consumeMessage method after the message is pushed to the client
Consumers Delivery time The time stamp when a client executes the consumeMessage method to consume a message

Status description

On the Query Jobs page, click Details and an area is unfolded. In this area, Sending Status and Consumption Status are displayed. These statuses are also displayed in the Producer and Consumers areas of the message trace diagram. The statuses that may be displayed are as follows.

Category Status Description
Sending Status Sent Successfully The message is sent successfully, and is stored in the server successfully.
Sending Status Sending Failed The message is failed to be sent, and is not stored in the server. Please try again.
Sending Status Message Standing By The message is a scheduled or delayed message, and the delivery time is not reached yet.
Sending Status Transaction Uncommitted The message is a transactional message and has not been committed yet.
Sending Status Transaction Rolled Back The message is a transactional message and has been rolled back.
Consumption Status All Succeeded All deliveries of the message have been successfully consumed.
Consumption Status Partially Succeeded Certain deliveries of the message failed,or later succeeded after retries
Consumption Status All Failed All delivered messages failed to be consumed.
Consumption Status Not Consumed The message has not been delivered to any consumer.
Consumption Status 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 Status Consumed Successfully The message has been successfully consumed.
Consumption Status 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.