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 methodConditionTypeDescription
By group IDGroup ID + Time RangeRange queryYou 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 IDGroup ID + Message IDExact matchYou 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 ApsaraMQ for RocketMQ console. In the left-side navigation pane, click Instances.
  2. In the top navigation bar, select a region. Example: China (Hangzhou). Then, click the ID of the instance that you want to manage.
  3. 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.

      Dead-letter queues
    • 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.

      Dead-letter queues

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.

FieldDescription
instanceIdThe ID of the ApsaraMQ for RocketMQ instance.
topicThe topic to which the message belongs.
msgIdThe message ID.
bornHostThe URL of the producer that produced the message.
bornTimestampThe timestamp when the message was produced.
storeTimestampThe timestamp when the message was stored in the ApsaraMQ for RocketMQ server.
reconsumeTimesThe number of consumption failures.
propertiesThe message properties in the JSON format.
bodyThe message body that is encoded in Base64.
bodyCRCThe 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.

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