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

  1. Log on to the Message Queue for Apache RocketMQ console.
  2. In the left-side navigation pane, click Instances.
  3. In the top navigation bar, select a region, for example, China (Hangzhou).
  4. On the Instances page, find the instance, click More in the Actions column, and then select Dead-letter Queues from the drop-down list.
  5. 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.

      dead_letter_group_id
    • 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.

      dead_letter_message_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.

Notice A dead-letter message is not deleted from the dead-letter queue immediately after the message is resent.
  • 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.