edit-icon download-icon

Message query

Last Updated: Dec 21, 2018

The MQ console provides several message query methods to assist you with troubleshooting.


MQ provides you with three ways to query messages: by message ID, by message key and by topic.

Their characteristics are compared as follows.

Query method Query condition Query category Description
Query by message ID Topic + message ID Precise query According to the message ID, you can locate any message precisely and obtain the properties of the message.
Query by message key Topic + message key Fuzzy query The latest 64 messages with the specified key can be queried. It is suggested that you set a key as unique as possible for each message, to ensure that the number of messages with the same key will not exceed 64; otherwise, certain messages could be missed.
Query by topic Topic + time period Range query All messages that match the specified topic and time range can be obtained. The query volume is large, and it is not easy to locate the message you want.

Recommended query process:


Query by message ID

A message-ID-based query is a precise query. You can precisely query out any message by its topic and message ID. Therefore, in order to get more precise query results to facilitate troubleshooting, it is recommended that you include the message IDs in the log that is printed out after the messages are successfully sent.

As for Java SDK, the message ID can be obtained as follows:

  1. SendResult sendResult = producer.send(msg);
  2. String msgId = sendResult.getMessageId();

Query results

After a message is queried out, you can view its basic properties, the download link of its message body, and its consumption status on the message’s details page.

The delivery status is based on the consumer progress of each consumer ID. For detailed explanation, see the following table.

Note: The delivery status is only an estimation based on the consumer progress. To get more detailed consumption information, use the message tracing function. With the message tracing function, you can view the complete trace of a message. For details, see Query message traces.

Delivery statuses

Delivery status Possible reasons
Subscribed to, and consumed at least once The consumer ID has consumed this message normally
Subscribed to, but filtered out by a filter expression, check the tag The message’s tag is not subscribed by the consumer ID, and therefore, the message is filtered out. To check the consumer ID’s subscription, go to the Consumers page in the console, and in the Actions column of the consumer ID click Consumer Status.
Subscribed to, but not consumed The consumer ID has subscribed to the message, but has not consumed it yet. The cause could be that the consumption is slow, or is blocked by an exception.
Subscribed, but the consumer ID is currently offline
Use message trajectory for a precise query.
The consumer ID has subscribed to the message, but is offline. Please check the reason why the consumer application is offline.
Unknown exception An unlisted exception occurred. Please open a ticket for technical support.

Consumption verification

MQ provides a consumption verification function which allows you to push a specified message to a designated online client, in order to test whether the message is consumed in an expected logic by the client.

Note: The consumption verification function is used only to test a client’s consumption logic and does not affect the normal message receiving process. Therefore, the consumer status of the message does not change after the consumption verification.

Query by message key

The mechanism of message-key-based query is that MQ creates an index for the messages according to message keys you provide, and when you query by message key, the matched messages can be found through the index and are returned to you.


  • The condition for message-key-based query is the message key property set by the user.
  • Only the latest 64 messages that meet the condition will be returned when you query by message key, so please make sure that the key you set is unique and has a distinctive service identification.

The method for setting a message key is as follows:

  1. Message msg = new Message("Topic","*","Hello MQ".getBytes());
  2. /**
  3. * Set a key for each message. The key’s value represents the primary service attribute of the message, so please try to make it globally unique.
  4. * So that when you cannot receive message normally, you can query the messages in the MQ console. Regular message sending and receiving will not be affected if keys are not set.
  5. */
  6. msg.setKey("TestKey"+System.currentTimeMillis());

Query by topic

When the query conditions for the two query methods above are not available, you can use the topic-based query, which is query by topic and message sending’s time range, to obtain all messages within the time range in chunk, and then find the data of your interest.


  • Topic-based query is a range query for obtaining all messages meeting the time condition under a specified topic, so the message volume is large and it is recommended that you shorten the query interval to the greatest extent.
  • Topic-based query involves a large amount of data, so the result is usually displayed on multiple pages.
Thank you! We've received your feedback.