All Products
Search
Document Center

ApsaraMQ for RabbitMQ:Dead-letter exchanges

Last Updated:Sep 08, 2023

Dead-letter exchanges in ApsaraMQ for RabbitMQ are used to process messages that are negatively acknowledged by consumers or for which all retries fail. This topic introduces the terms that are used for 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 is used to route dead-letter messages. A dead-letter exchange delivers dead-letter messages to a dead-letter queue 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 rules for routing 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 may be sent to a dead-letter exchange in the following scenarios:
      • The requeue parameter is set to false, and the consumer uses basic.reject or basic.nack to send negative acknowledgements for messages.
      • The message fails to be consumed after being re-sent 16 times. For more information, see Message timeout and retry.
      • The message expires. The time that the message is stored in the queue exceeds the specified message TTL. For more information, see Message TTL.
  • 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

The following items describe the 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 pulls the message from the queue.

  4. If the consumer fails to consume the message even after the message is retried for 16 times or the consumer negatively acknowledges the message, the message becomes a dead-letter message

  5. The queue sends the dead-letter message to a dead-letter exchange based on the x-dead-letter-exchange parameter and specifies 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.

dg_dead_letter_message_flow

Usage notes

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

  • ApsaraMQ for RabbitMQ does not allow you to modify the dead-letter exchange of a queue. If you want to modify the dead-letter exchange of a queue, you must delete the queue and then create a queue and configure a dead-letter exchange for it.

Configuration methods

ApsaraMQ for RabbitMQ allows you to configure a dead-letter exchange by using one of the following methods:

Use the ApsaraMQ for RabbitMQ console

You can configure a dead-letter exchange for a queue when you create the queue in the ApsaraMQ for RabbitMQ console.

  1. Log on to the ApsaraMQ 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 vhost. From the drop-down list, select the vhost in which 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, configure the Auto Delete parameter, click Advanced Settings, configure the displayed parameters for the queue, and then click OK.

    Parameter

    Description

    Note

    Queue Name

    The name of the queue.

    • The name can contain 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.

    • A name that starts with amq. is used as a reserved field. For example, amq.test is an invalid name.

    Auto Delete

    Specifies whether the queue is deleted after the last subscription from consumers to this queue is canceled.

    • true: The queue is deleted after the last subscription from consumers to this queue is canceled.

    • false: The queue is not deleted after the last subscription from consumers to this queue is canceled.

    Advanced Settings

    Other parameters for 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 delivered.

    • DeadLetterRoutingKey: the routing key of dead-letter messages. A dead-letter exchange sends dead-letter messages to the queue whose binding key matches the routing key of the dead-letter messages.

    • MessageTTL: the message Time to Live (TTL), in milliseconds. A message that is not consumed within the specified message TTL is a dead-letter message and is sent to a dead-letter exchange. For more information, see Message TTL.

Use the CreateQueue API operation

You can 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 clients

You can also configure a dead-letter exchange for a queue when you declare the queue on an ApsaraMQ 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.

For example, if you want to declare an exchange whose name is some.exchange.name and type is direct, use the x-dead-letter-exchange parameter to specify the exchange as the dead-letter exchange and the x-dead-letter-routing-key parameter to specify demo-routing-key as the routing key of the dead-letter message.

Sample code in Java:

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);

Additional information

For information about how to delete a dead-letter exchange and bind a dead-letter exchange to a dead-letter queue, see Manage exchanges.