Dead-letter queues are used to process messages that cannot be consumed any more. This topic describes how to query, export, and resend dead-letter messages that have entered the dead-letter queue, helping you manage dead-letter messages to prevent required messages from not being processed.

Background

When a message fails to be consumed for the first time, Message Queue for Apache RocketMQ automatically retries. If the message still cannot be consumed after the maximum number of retries is reached, the message cannot be properly consumed. In this case, Message Queue for Apache RocketMQ sends the message to a particular queue corresponding to the consumer instead of discarding it immediately.

In Message Queue for Apache RocketMQ, a message that cannot be properly consumed is called a dead-letter message, which is stored in a particular queue named dead-letter queue.

Features

Dead-letter messages have the following features:

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

Dead-letter queues have the following features:

  • A 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 of the corresponding group ID regardless of the message topic.

In the Message Queue for Apache RocketMQ console, you can query, export, and resend dead-letter messages.

Methods for querying dead-letter messages

Message Queue for Apache RocketMQ provides the following two methods for querying dead-letter messages:

Query method Condition Type Description
By group ID Group ID and time range Range query By specifying a group ID and a time range, you can retrieve all the messages that meet the conditions in batches. This type of query has a large query volume and implements only fuzzy matching.
By message ID Group ID and message ID Exact match query You can precisely locate any message by specifying its group ID and message ID.

Query dead-letter messages

  1. Log on to the Message Queue for Apache RocketMQconsole. In the top navigation bar, select the region, such as China (Hangzhou).
  2. On the Instances page, find the target instance and click Details in the Actions column.
  3. In the left-side navigation pane, click Dead-letter Queue.
  4. On the Dead-letter Queuepage, click any tab. On the tab that appears, enter related information and click Search to query messages.
    • Search 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.

      Notice The production 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 for sending this message is reached.

      All dead-letter messages that meet the filter conditions are displayed.

      DL-by-groupid
    • 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.

      All dead-letter messages that meet the filter conditions are displayed.

      DL-by-messageid
  5. Find the dead-letter message you want to view and click View Details in the Actions column to view the details.msg_detail
  6. (Optional) By clicking Consumption Verification, you can push a specified message to a specified online client to check whether the client consumes the message as expected in terms of logic and result.
    Notice The consumption verification function is only for verifying whether the consumption logic on the client is normal and does not affect a normal message receiving process. Therefore, information such as the consumption status of the message does not change after consumption verification.
    consume-validate

Export dead-letter messages

If you cannot process dead-letter messages for the moment, export them from the Message Queue for Apache RocketMQ console in case they expire.

The Message Queue for Apache RocketMQ console allows you to export a single dead-letter message or export dead-letter messages in batches. 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 produced the message.
bornTimestamp The time when the message was produced.
storeTimestamp The time when the message was stored in the Message Queue for Apache RocketMQ broker.
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.
  • Export a single dead-letter message

    In the Message Queue for Apache RocketMQ console, find the target dead-letter message and click Export in the Actions column.

  • Export dead-letter messages in batches

    In the Message Queue for Apache RocketMQ console, find the dead-letter messages by group ID, select the target dead-letter messages, and click Bulk Export to export all the selected dead-letter messages.

Resend dead-letter messages

The entrance of a message 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 the fault, you can resend the message in the Message Queue for Apache RocketMQ console to the consumer.

Notice A dead-letter message is not deleted from the dead-letter queue immediately after being resent.
  • Resend a single dead-letter message

    In the Message Queue for Apache RocketMQ console, find the target dead-letter message and click Resend in the Actions column.

  • Resend dead-letter messages in batches

    In the Message Queue for Apache RocketMQ console, find the dead-letter messages by group ID, select the target dead-letter messages, and click Bulk Resend to resend all the selected dead-letter messages.