Dead-letter exchanges in Message Queue for RabbitMQ are used to process messages that are negatively acknowledged by consumers or have reached the upper retry limit. This topic introduces the core concepts related to dead-letter exchanges, describes the routing process, configuration methods, and limits of dead-letter exchanges, and provides links to related topics.

Core concepts

dead-letter exchange
An exchange that routes dead-letter messages to dead-letter queues based on binding keys, dead-letter routing keys, and headers attributes. All common types of exchanges, such as direct exchanges, can be used as dead-letter exchanges.
dead-letter routing key
A set of routing rules for a dead-letter message. If you do not specify a dead-letter routing key for a dead-letter message, the original routing key of the message is used as the dead-letter routing key.
dead-letter message
A message that is sent to a dead-letter exchange. A message is sent to a dead-letter exchange if one of the following situations occurs:
  • The requeue parameter is set to false, and the consumer uses basic.reject or basic.nack to negatively acknowledge the message.
  • The message is retried 16 times, but it still fails to be consumed. For more information, see Message retry.
Notice Expired messages or messages that are discarded due to limits on queue lengths do not become dead-letter messages.
dead-letter queue
A queue that is bound to a dead-letter exchange. A dead-letter queue is used to store dead-letter messages.

Routing process

Routing process of a dead-letter message:

  1. A producer sends a message to an exchange.
  2. The exchange routes the message to a queue.
  3. A consumer fetches the message from the queue.
  4. One of the following situations occurs, and the message becomes a dead-letter message: 1. The consumer fails to consume the message. Then, the message is retried 16 times but still fails to be consumed. 2. The consumer negatively acknowledges the message.
  5. The queue sends the dead-letter message to a dead-letter exchange based on x-dead-letter-exchange and sets a dead-letter routing key for the message based on x-dead-letter-routing-key.
  6. The dead-letter exchange routes the message to a dead-letter queue.
dg_dead_letter_message_flow

Configuration methods

You can use one of the following methods to configure a dead-letter exchange in Message Queue for RabbitMQ:

  • Console

    Configure a dead-letter exchange for a queue when you create the queue in the Message Queue for RabbitMQ console.

    1. Log on to the Message Queue for RabbitMQ console.
    2. In the top navigation bar, select the region where your instance resides.
    3. In the left-side navigation pane, click Queues.
    4. On the Queues page, select an instance and a vhost and click Create Queue.
    5. In the Create Queue dialog box, configure queue attributes and click OK. createdeadqueue
  • API

    Configure a dead-letter exchange for a queue when you call the CreateQueue API operation to create the queue. For more information, see CreateQueue.

  • Client

    Configure a dead-letter exchange for a queue when you declare the queue on the Message Queue for RabbitMQ client. You can use the x-dead-letter-exchange parameter to specify a dead-letter exchange and the x-dead-letter-routing-key parameter to specify a dead-letter routing key. In the following Java sample code, the queue MyQueue and the direct exchange some.exchange.name are declared. It shows how to use the x-dead-letter-exchange parameter to configure some.exchange.name as the dead-letter exchange of MyQueue and use the x-dead-letter-routing-key parameter to configure demo-routing-key as the dead-letter routing key. Java sample code:

    channel.exchangeDeclare("demo.exchange.name", "direct");
    Map<String, Object> args = new HashMap<String, Object>();
    arguments.put("x-dead-letter-exchange", "some.exchange.name");
    arguments.put("x-dead-letter-routing-key", "demo-routing-key");
    channel.queueDeclare("MyQueue", false, false, false, arguments);

Limits

  • Message Queue for RabbitMQ does not allow you to route dead-letter messages across vhosts. When you configure a dead-letter exchange for a queue, you must make sure that the dead-letter exchange resides in the same vhost as the queue.
  • Message Queue for RabbitMQ does not allow you to modify the dead-letter exchange of a queue. To modify the dead-letter exchange of a queue, you must delete the queue first. Then, create a queue and configure a dead-letter exchange for it.

References