Dead-letter exchanges in Message Queue for RabbitMQ are used to process the messages that are negatively acknowledged by consumers or for which all retries fail. This topic introduces the terms related to dead-letter exchanges, describes the routing process, configuration methods, and limits on dead-letter exchanges, and provides links to related topics.

Terms

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 regular 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

A dead-letter message involves the following routing process:

  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 the x-dead-letter-exchange parameter and sets a dead-letter routing key for the message based on the x-dead-letter-routing-key parameter.
  6. The dead-letter exchange routes the message to a dead-letter queue.
Dead-letter message flowchart

Configuration methods

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

  • Use the 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 Resource Distribution section of the Overview page, select the region where your instance resides.
    3. On the Instances page, click the name of the instance that you want to manage.
    4. In the left-side navigation pane, click Queues.
    5. On the Queues page, click Change next to the current vhost in use. From the drop-down list, select the vhost where you want to create a queue. Then, click Create Queue.
    6. In the Create Queue panel, enter a queue name in the Queue Name field and set the Auto Delete parameter. Click Advanced Settings and set the displayed parameters for the queue. Then, click OK. Create a dead-letter queue
      Table 1. Parameters
      Parameter Description Notes
      Queue Name The name of the queue.
      • The name can contain only letters, digits, hyphens (-), underscores (_), periods (.), number signs (#), forward slashes (/), and at signs (@).
      • The name must be 1 to 255 characters in length.
      • After a queue is created, you cannot modify its name. If you want to modify its name, delete the queue and create another queue.
      • The name cannot start with amq. because amq. is used as a reserved field. For example, amq.test is an invalid name.
      Auto Delete Specifies whether the queue is automatically deleted after the last subscription from consumers to this queue is canceled.
      • true: The queue is automatically deleted after the last subscription from consumers to this queue is canceled.
      • false: The queue is not automatically deleted after the last subscription from consumers to this queue is canceled.
      Advanced Settings Other parameters of the queue, such as the dead-letter exchange, dead-letter routing key, and message time-to-live (TTL).
      • DeadLetterExchange: the exchange to which dead-letter messages are sent.
      • DeadLetterRoutingKey: the routing key of a dead-letter message. A dead-letter exchange sends a dead-letter message to the queue whose binding key matches the routing key of the dead-letter message.
      • MessageTTL: the period of time for which a message can stay in a queue before it expires. Unit: milliseconds. A message that is not consumed within the message TTL is a dead-letter message. The dead-letter message is sent to a dead-letter exchange.
  • Call the create queue API operation

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

  • Use the 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. The sample code shows how to use the x-dead-letter-exchange parameter to configure some.exchange.name as the dead-letter exchange and use the x-dead-letter-routing-key parameter to configure demo-routing-key as the dead-letter routing key for the queue MyQueue. Java sample code:

    channel.exchangeDeclare("some.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);

Usage notes

  • 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