All Products
Search
Document Center

Dead-letter queue

Last Updated: Sep 13, 2019

Overview

Dead-letter queues are used to process messages that cannot be consumed. When a message fails to be consumed for the first time, MQ automatically retires the consumption of the message. If the message still cannot be consumed after the maximum number of retries is reached, the message cannot be properly consumed. Instead of immediately discarding the message, MQ sends it to a particular queue of the corresponding consumer.

In MQ, a message that cannot be properly consumed is called a dead-letter message, which is stored by a particular queue named dead-letter queue.

Dead-letter messages have the following features:

  • They can no longer be properly consumed.
  • They have a valid period that is the same as that of a normal message, namely, three days. After three days, the message is deleted automatically. Therefore, process dead-letter messages within the three days after being produced.

The dead-letter queue has the following features:

  • A dead-letter queue corresponds to a group ID rather than a consumer instance.
  • When no dead-letter messages are produced for a group ID, MQ does not create a dead-letter queue for it.
  • A dead-letter queue contains all the dead-letter messages of the corresponding group ID regardless of the message topic.

In the MQ console, you can query, export, and resend dead-letter messages.

Query dead-letter messages

MQ provides two methods for querying dead-letter messages:

  • By group ID
  • By message ID

The differences between the methods are as follows:

Method Condition Type Description
By group ID Group ID + time range Range query After you specify the group ID and time range, all the qualified messages are displayed in batches. The query volume is large and only fuzzy matching can be implemented.
By message ID Group ID + message ID Exact query The group ID and message ID exactly identifies a message.

By group ID

You can batch query all the dead-letter messages of a group ID within a certain time range by specifying their group ID and time range.

Note: The time range of a dead-letter message refers to the period from the time when the maximum number of message sending retries is reached to the time when it is sent to the dead-letter queue.

The procedure is as follows:

  1. In the left-side navigation pane of the MQ console, choose Dead-Letter Queue.
  2. On the Dead-Letter Queue page, click the By Group ID tab.
  3. In the group ID text box, enter keywords and select the displayed group ID, or select the target group ID from the drop-down list.
  4. Set the start time and end time.
  5. Click Search. All dead-letter messages that meet the preceding conditions are displayed.
  6. Locate the row that contains the target dead-letter message, and click View Details in the Actions column to view the details of the message, including its basic properties, message body download link, message trace, and delivery status.

By message ID

Exact matching is implemented if you query by message ID. You can precisely locate any message by specifying its group ID and message ID.

The procedure is as follows:

  1. In the left-side navigation pane of the MQ console, choose Dead-Letter Queue.
  2. On the Dead-Letter Queue page, click the By Message ID tab.
  3. In the group ID text box, enter keywords and select the displayed group ID, or select the target group ID from the drop-down list.
  4. In the message ID text box, enter the message ID that you want to search.
  5. Click Search. All dead-letter messages that meet the preceding conditions are displayed.
  6. Locate the row that contains the target dead-letter message, and click View Details in the Actions column to view the details of the message, including its basic properties, message body download link, message trace, and delivery status.

Export dead-letter messages

If you cannot process dead-letter messages for the moment, export them from the MQ console in case that they expire.

The MQ console provides Single Export and Batch Export of dead-letter messages. The exported file is in CSV format.

The exported messages cover the following information:

Field Description
topic The message topic.
msgId The message ID.
bornHost The URL of the producer that produces the message.
bornTimestamp The time when the message is produced.
storeTimestamp The time when the message turns into a dead-letter message.
reconsumeTimes The number of consumption failures.
properties The message properties in JSON format.
body The message body in base64 coding format.
bodyCRC The message body CRC.

Single export

After you locate the row that contains the target dead-letter message using any method in the MQ console, click Export in the Actions column to export it.

Batch export

After you locate the target dead-letter messages by group ID in the MQ console, select the target dead-letter messages, and click Batch Export to export all the selected dead-letter messages.

Resend dead-letter messages

A message entering into the dead-letter message queue indicates that, for some reason, it cannot be consumed properly. As a result, you must process it specifically. After troubleshooting and bug fixing, you can resend the message in the MQ console for consumption.

Note: A dead-letter message is not deleted from the dead-letter queue immediately after being resent.

Single resend

After you locate the row that contains the target dead-letter message using any method in the MQ console, click Resend in the Actions column to resend it.

Batch resend

After you locate the target dead-letter messages by group ID in the MQ console, select the target dead-letter messages, and click Batch Resend to resend all the selected dead-letter messages.