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 entered the dead-letter queue. This helps you manage dead-letter messages based on your business requirements and prevent missing messages.
Background information
When a message first fails to be consumed, ApsaraMQ for RocketMQ automatically retries to send the message. If the message cannot be consumed after the maximum number of retries is reached, the message cannot be consumed as expected. In this case, ApsaraMQ for RocketMQ does not discard the message, but sends the message to a particular queue that corresponds to the consumer.
In ApsaraMQ for 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.
- By default, the validity period for dead-letter messages is three days, the same as the validity period of normal messages. After three days, the dead-letter messages are automatically deleted. We recommend that you handle dead-letter messages within three days after they are generated.
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, ApsaraMQ for 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 ApsaraMQ for RocketMQ console, you can query, export, and resend dead-letter messages.
Query methods for dead-letter messages
ApsaraMQ for 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 ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.
- In the top navigation bar, select a region. Example: China (Hangzhou). Then, click the ID of the instance that you want to manage.
- In the left-side navigation pane, click Dead-letter Queues. On the Dead-letter Queues page, select a method to query a dead-letter message.
- Query by Group ID
You can specify a group ID and a time range during which dead messages are generated. Then query all messages that meet these conditions.
Note The generation time of a dead-letter message refers to the time when a message is sent to the dead-letter queue after the maximum number of retries specified for the message is reached.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 to find the message that you want to query 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 ApsaraMQ for RocketMQ console.
ApsaraMQ for 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 ApsaraMQ for 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 ApsaraMQ for 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 ApsaraMQ for 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 ApsaraMQ for 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
Only messages that cannot be consumed as expected enter a dead-letter queue. Therefore, dead-letter messages require special processing. After you troubleshoot the problems of a message, you can resend the message to the corresponding consumer in the ApsaraMQ for RocketMQ console.
- If an ordered message is sent to a dead-letter queue, you cannot resend the message. You must export the message from the dead-letter queue and process the message.
- After a dead-letter message is re-sent for consumption, the message is stored in the dead-letter queue for a specific period of time. The system automatically deletes the message after the validity period elapses.
- Resend a single dead-letter message
In the ApsaraMQ for RocketMQ console, find the dead-letter message that you want to resend, click More in the Actions column, and then select Resend from the drop-down list to resend the message.
- Resend multiple dead-letter messages at a time
In the ApsaraMQ for RocketMQ console, find the dead-letter messages by group ID, select the dead-letter messages that you want to resend, and then click Batch Resend Messages to resend all selected dead-letter messages.