When troubleshooting message delivery, you often need to locate a specific message to verify it was sent, inspect its content, or trace its consumption path. ApsaraMQ for RocketMQ provides three query methods -- by message ID, message key, or topic -- each suited to different levels of information availability.
Query methods
The following table compares the three query methods.
| Method | Required input | Match type | When to use |
|---|---|---|---|
| By message ID | Topic + Message ID | Exact match | You have the message ID. Returns the single matching message. |
| By message key | Topic + Message key | Fuzzy match | You have a message key. Returns the most recent 64 messages that contain the key. |
| By topic | Topic + Time range | Range match | The message ID and key are unavailable. Returns all messages in the specified time range. |
Messages are stored on ApsaraMQ for RocketMQ brokers for 3 days by default. Only messages produced within the last 3 days are queryable. For example, if the current time is 15:09:48 on June 10, 2019, you can query messages produced from 15:09:48 on June 7, 2019 onward. We recommend that you do not change the default storage period.
Choose a query method
Use the following decision flow to select the most efficient query method:
Message ID available? Use query by message ID for an exact match.
Message key available? Use query by message key to find messages that share a key.
Neither available? Use query by topic and narrow the time range as much as possible.
Prerequisites
Before you begin, make sure that you have:
An ApsaraMQ for RocketMQ instance
Messages produced to at least one topic within the last 3 days
Open the message query page
Log on to the ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.
In the top navigation bar, select a region, such as China (Hangzhou).
On the Instances page, find the target instance, click More in the Actions column, and select Message Query.
On the Message Query page, select a query method, configure the required parameters, and click Search.
Query by message ID
Query by message ID returns the single message that exactly matches the specified topic and message ID. This is the fastest and most precise query method.
Best practice: Log the message ID on the producer side at send time. This simplifies troubleshooting when you need to locate a specific message later.
Get the message ID from the SendResult object:
SendResult sendResult = producer.send(msg);
String msgId = sendResult.getMessageId();For SDKs in other languages, see Overview.
Query by message key
Query by message key returns the most recent 64 messages that contain the specified key in the given topic. ApsaraMQ for RocketMQ builds an index on the message key to support this query.
Set a message key before sending the message. Messages without a key cannot be queried by this method.
Assign a unique, identifiable key to each message. If more than 64 messages share the same key, some messages will not appear in results.
Set a unique business key on each message before sending:
Message msg = new Message("Topic", "*", "Hello MQ".getBytes());
// Set a unique business key for message retrieval.
// A globally unique key is recommended.
// Messages can still be sent and received without a key,
// but key-based queries will not work.
msg.setKey("TestKey" + System.currentTimeMillis());Query by topic
Use query by topic when the message ID and key are both unavailable. Specify a topic and a time range to retrieve all matching messages.
This method can return a large number of messages across multiple pages. Narrow the time range to locate the target message more efficiently.
Query results
After a query completes, the Message Query page displays the following fields for each message:
| Field | Description |
|---|---|
| Message ID | Unique identifier of the message |
| Tag | Message tag used for filtering |
| Key | Business key set by the producer |
| Sending time | Timestamp when the message was sent |
| Storage period | Duration for which the message is stored |
From the results, you can perform the following actions:
| Action | Description |
|---|---|
| Query message traces | Track a message through the system. See Query message traces. |
| Verify message consumption | Push a message to a connected consumer to confirm it is processed correctly. See Verify message consumption. |
| Download messages | Save message data locally for offline analysis. |
Verify message consumption
Consumption verification pushes a queried message to a connected consumer client to confirm the consumer handles it with the expected logic.
Consumption verification is a test-only operation. It does not affect actual message delivery or change the message consumption status.
What's next
Query message traces -- View the trace, consumption status, and consumption result of a message.