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 related to dead-letter exchanges, describes the routing process, configuration methods, and limits on dead-letter exchanges, and provides links to the 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.rejectorbasic.nackto send negative acknowledgments (NACKs) for messages.The message fails to be consumed after being re-sent 16 times. For more information, see Consumption retry policies.
The message expires. The time for which 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:
A producer sends a message to an exchange.
The exchange routes the message to a queue.
A consumer pulls the message from the queue.
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.
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.
The dead-letter exchange routes the message to a dead-letter queue.
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, create another queue, and then configure a dead-letter exchange for the new queue.
Configuration methods
ApsaraMQ for RabbitMQ allows you to configure a dead-letter exchange by using one of the following methods:
Console
You can configure a dead-letter exchange for a queue when you create the queue in the ApsaraMQ for RabbitMQ console.
Log on to the ApsaraMQ for RabbitMQ console.
In the Resource Distribution section of the Overview page, select the region where your instance resides.
On the Instances page, click the name of the instance that you want to manage.
In the left-side navigation tree, click Queues.
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.
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
Usage notes
Queue Name
The queue name.
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 change its name. If you want to change the name of a queue, delete the queue and create another queue.
amq. is a reserved field and cannot be used as the prefix of an exchange name. For example, you cannot use amq.test as the name of an exchange.
Auto Delete
Specifies whether the queue is automatically deleted after the last subscription from consumers to the 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 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 routing key matches the routing key of the dead-letter messages.
MessageTTL: the message 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.
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.
Client
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);Dead-letter header
The following table describes the information that is included in the header of a dead-letter message.
Header | Description |
x-first-death-exchange | The exchange to which the message belongs when the message first becomes a dead-letter message. |
x-first-death-queue | The queue to which the message belongs when the message first becomes a dead-letter message. |
x-first-death-reason | The reason why the message first becomes a dead-letter message. |
x-death-total | The number of times that the message becomes a dead-letter message. |
x-death | The array that contains more detailed information about the dead-letter message.
|
The following items describe the possible causes for a message to become a dead-letter message:
expired: The message is expired.
nack: The message is negatively acknowledged and is not requeued.
reject: The message is rejected and is not requeued.
exceed consumer times: The number of times that the message is consumed exceeds the limit.
Enable the TTL feature for a dead-letter queue
After a dead-letter message is sent to a dead-letter queue, the time-to-live (TTL) feature is automatically disabled. This ensures that dead-letter messages in the dead-letter queue are not routed to other dead-letter queues or automatically deleted after the TTL expires. You can enable the TTL feature for dead-letter queues in an instance in the ApsaraMQ for RabbitMQ console. After you enable the TTL feature, dead-letter messages in a dead-letter queue are routed to other dead-letter queues after the specified TTL expires.
Limits on instances
You can enable the TTL feature only for dead-letter queues in Enterprise Edition, Enterprise Platinum Edition, and serverless instances.
Procedure
On the Instances page in the ApsaraMQ for RabbitMQ console, click the name of the instance that you want to manage.
On the Instance Details page, click the Limits tab.
Click Activate next to TTL Feature Supported to enable the TTL feature for dead-letter queues.
When you configure a dead-letter queue, a message loop may occur. For example, if you specify Queue B as the dead-letter queue of Queue A and specify Queue A as the dead-letter queue of Queue B, dead-letter messages are routed in a loop. If no message is rejected in the message routing process and message loop is detected, the TTL feature no longer takes effect on the related dead-letter messages.
A dead-letter message can be routed between queues for up to 16 times. If this limit is reached, the TTL feature no longer takes effect on the related dead-letter messages.
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.