Using the Dead Letter Channel

The Dead Letter Channel (DLC) is a subset of a queue, specifically designed to persist messages that are typically marked for deletion. When a message is sent to a consumer, if the message fails to deliver, it will be routed to the DLC. This provides you with a choice on whether to delete, retrieve or reroute the messages from the DLC.

Messages can get routed to the DLC for several reasons. Listed below are some of them.

• The subscriber does not acknowledge a message.

• Network partitioning (split brain condition) may have occurred while delivering the message, which has interrupted the message flow. See how network partitioning is handled in a deployment of the Message Broker profile

• Messages may be continuously sent to a single session, which exceeds the maximum number of deliveries allowed.

• The JMS selectors enabled for the message do not match the selectors in the subscription.

• The message has expired before the delivery.
• Message delivery rules may fail. For example, the subscriber may have enabled the no-local option.

A DLC queue is created when the first subscription is made for a specific domain (super user or tenant). By default, the message broker retries a defined number of times when a subscriber does not acknowledge a message. Once the retry count has been breached, the message is removed from the queue and placed in the DLC. The default number of retries is set to 10, however, this value is configurable. See the section on configuring the message retry count for more information.

Browsing through the DLC Queue

All messages that have breached the retry count will be dumped into the DLC queue. The content of the queue can be viewed by following the steps below.

1. Log in to the Management Console.
2. Click Dead Letter Channel - > Browse in the Main tab.
3. The DLC browser is displayed in the right side of the pane, as shown below. The message count specifies the number of messages in the DLC queue. 
   
4. Click Browse to view details of each message stored in the DLC. The Destination column shows the name of the original queue.  
5. You can choose to delete, restore or reroute one or more messages:
   • Delete: Permanently delete the message from the broker.
   • Restore: Re-insert the message to the queue from which the message originated.
   • ReRoute: Allows you to select a destination of choice instead of restoring the message to the original queue. When you click ReRoute, a pop-up menu appears, as shown below:

     

     Select the queue name to which the message should be re-routed and click OK. The message is then moved to the relevant queue.

   • ReRoute All: This option will be available if you have the relevant configuration enabled for the product: The <allowReRouteAllInDLC> property in the broker.xml file should be set to true before the broker is started. You can click this option to reroute all messages in the DLC to a destination (queue) of your choice.

Handling multitenancy

To ensure that messages can be distinguished per tenant, a separate DLC is created for every new tenant in the system. The signature of the DLC queue is similar to the example shown below.

{tenant_name}/DeadLetterChannel

This ensures that only the messages exchanged through queues in a specific tenant domain are inserted to the DLC queue.

Configuring the message retry count

The message retry count can be configured as follows:

1. Open the broker.xml file located in the <EI_HOME>/wso2/broker/conf folder.

2. Locate the maximumRedeliveryAttempts attribute and change the value accordingly. See the following example.

   <maximumRedeliveryAttempts>15</maximumRedeliveryAttempts>