Dead-letter queues are used to process messages that cannot be consumed as expected. This topic describes how to query, export, and resend dead-letter messages that have entered the dead-letter queue. This helps you manage dead-letter messages as needed and prevent missing messages.
Background information
When a message fails to be consumed for the first time, Message Queue for Apache RocketMQ automatically retries to send the message. If the message still cannot be consumed after the maximum number of retries, the message cannot be consumed as expected. In this case, Message Queue for Apache RocketMQ does not discard the message, but sends the message to a particular queue that corresponds to the consumer.
In Message Queue for Apache RocketMQ, a message that cannot be consumed as expected is called a dead-letter message. The dead-letter message is stored in a particular queue named dead-letter queue.
Features
Dead-letter messages have the following features:
- Dead-letter messages can no longer be consumed as expected.
- Dead-letter messages have a validity period of three days. This validity period is the same as that of a normal message. After three days, the dead-letter messages are automatically deleted. Therefore, we recommend that you handle dead-letter messages within three days after they are produced.
Dead-letter queues have the following features:
- Each dead-letter queue corresponds to a group ID rather than a consumer instance.
- If no dead-letter message is produced for a group ID, Message Queue for Apache RocketMQ does not create a dead-letter queue for the group ID.
- A dead-letter queue contains all the dead-letter messages for the corresponding group ID regardless of which topics these messages belong to.
In the Message Queue for Apache RocketMQ console, you can query, export, and resend dead-letter messages.
Query methods for dead-letter messages
Message Queue for Apache RocketMQ provides the following two query methods for dead-letter messages.
Query method | Condition | Type | Description |
---|---|---|---|
By group ID | Group ID + Time Range | Range query | You can specify a group ID and a time range, and then retrieve all the messages that meet these conditions in batches. This type of query allows you to query a large number of messages by using fuzzy match. |
By message ID | Group ID + Message ID | Exact match | You can specify a group ID and a message ID, and then locate a message by using exact match. |
Query dead-letter messages
- Log on to the Message Queue for Apache RocketMQ console.
- In the left-side navigation pane, click Instances.
- In the top navigation bar, select a region, for example, China (Hangzhou).
- On the Instances page, find the instance, click More in the Actions column, and then select Dead-letter Queues from the drop-down list.
- On the Dead-letter Queues page, you can select one of the following query methods:
- Query by Group ID
You can specify a group ID and a time range, and then query all the messages that meet these conditions in batches.
Notice The production time of a dead-letter message refers to the time when a message is sent to a dead-letter queue after the maximum number of retries.All dead-letter messages that meet the filter conditions are displayed.
- Query by Message ID
If you query messages by message ID, exact match is used. You can specify a group ID and a message ID, and then locate a message by using exact match.
All dead-letter messages that meet the filter conditions are displayed.
- Query by Group ID
Export dead-letter messages
If you cannot process dead-letter messages within the validity period, export the messages in the Message Queue for Apache RocketMQ console.
Message Queue for Apache RocketMQ allows you to export a single dead-letter message or export dead-letter messages in batches in the console. The exported file is in CSV format.
The following information of dead-letter messages is exported.
Field | Description |
---|---|
instanceId | The ID of the Message Queue for Apache RocketMQ instance. |
topic | The topic to which the message belongs. |
msgId | The message ID. |
bornHost | The URL of the producer that produced the message. |
bornTimestamp | The timestamp when the message was produced. |
storeTimestamp | The timestamp when the message was stored in the Message Queue for Apache RocketMQ server. |
reconsumeTimes | The number of consumption failures. |
properties | The message properties in the JSON format. |
body | The message body that is encoded in Base64. |
bodyCRC | The message body Cyclic Redundancy Check (CRC). |
- Export a single dead-letter message
In the Message Queue for Apache RocketMQ console, find the dead-letter message and click More in the Actions column, and then select Export Message from the drop-down list to export the message.
- Export dead-letter messages in batches
In the Message Queue for Apache RocketMQ console, find the dead-letter messages by group ID, select the dead-letter messages, and then click Batch Export Messages to export all the selected dead-letter messages.
Resend dead-letter messages
If a message enters a dead-letter queue, the message cannot be consumed as expected due to specific causes. Therefore, you must troubleshoot the message. After that, you can resend the message to the consumer in the Message Queue for Apache RocketMQ console.
- Resend a single dead-letter message
In the Message Queue for Apache RocketMQ console, find the dead-letter message, click More in the Actions column, and then select Resend from the drop-down list to resend the message.
- Resend dead-letter messages in batches
In the Message Queue for Apache RocketMQ console, find the dead-letter messages by group ID, select the dead-letter messages, and then click Batch Resend Messages to resend all the selected dead-letter messages.