Amazon Simple Queue Service
Developer Guide (API Version 2012-11-05)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Using Amazon SQS Dead Letter Queues

Amazon SQS now provides support for dead letter queues. A dead letter queue is a queue that other (source) queues can target to send messages that for some reason could not be successfully processed. A primary benefit of using a dead letter queue is the ability to sideline and isolate the unsuccessfully processed messages. You can then analyze any messages sent to the dead letter queue to try and determine why they were not successfully processed.

To specify a dead letter queue, you can use the AWS Management Console or the query API. This must be done for each (source) queue that will send messages to a dead letter queue. You can have multiple (source) queues target a single dead letter queue.

Important

You must use the same AWS account to create the queue which will be used as a dead letter queue and the other (source) queues that will send messages to the dead letter queue. Dead letter queues also must reside in the same region as the other queues that use the dead letter queue. For example, if you created a queue in the US East (N. Virginia) region and you want to use a dead letter queue with that queue, then both queues must be in the US East (N. Virginia) region.

Setting up Dead Letter Queue with the AWS Management Console

You can use the AWS Management Console to configure dead letter queue functionality so that messages, which for some reason could not be successfully processed, are sent to a specified dead letter queue. This is accomplished by first selecting the source queue's Use Redrive Policy check box for existing and newly created queues.

Next, enter the name of the queue to which messages will be sent from the source queues.

You then set the Maximum Receives to a value between 1 and 1000.

The following figure shows the MySourceQueue queue, which has the Redrive Policy configured to have messages sent to the MyDeadLetterQueue queue.

Using Dead Letter Queue with the Amazon SQS API

To specify a dead letter queue with the query API, you call either the CreateQueue or SetQueueAttributes actions and set the maxReceiveCount and deadLetterTargetArn parameters for the RedrivePolicy queue attribute.

You can set maxReceiveCount to a value between 1 and 1000. The deadLetterTargetArn value is the Amazon Resource Name (ARN) of the queue that will receive the dead letter messages.

The following Java example shows how to use SetQueueAttributes to set the maxReceiveCount and deadLetterTargetArn parameters for the RedrivePolicy queue attribute. This example is based on the SimpleQueueServiceSample.java sample from the AWS SDK for Java.

First, a string is set that contains JSON formatted parameters and values for the RedrivePolicy queue attribute:

String redrivePolicy = "{\"maxReceiveCount\":\"5\", \"deadLetterTargetArn\":\"arn:aws:sqs:us-east-1:123456789012:MyDeadLetterQueue\"}";
        

Next, SetQueueAttributesRequest is used to set the RedrivePolicy queue attribute:

SetQueueAttributesRequest queueAttributes = new SetQueueAttributesRequest();
Map<String,String> attributes = new HashMap<String,String>();            
attributes.put("RedrivePolicy", redrivePolicy);            
queueAttributes.setAttributes(attributes);
queueAttributes.setQueueUrl(myQueueUrl);
sqs.setQueueAttributes(queueAttributes);
        

An API query request for this example should look similar to the following:

http://sqs.us-east-1.amazonaws.com/123456789012/MySourceQueue 
?Action=SetQueueAttributes
&Attribute.1.Value=%7B%22maxReceiveCount%22%3A%225%22%2C+%22deadLetterTargetArn%22%3A%22arn%3Aaws%3Asqs%3Aus-east-1%3A123456789012%3AMyDeadLetterQueue%22%7D
&Version=2012-11-05
&Attribute.1.Name=RedrivePolicy
        

The API query response should look similar to the following:

<SetQueueAttributesResponse xmlns="http://queue.amazonaws.com/doc/2012-11-05/">
    <ResponseMetadata>
        <RequestId>40945605-b328-53b5-aed4-1cc24a7240e8</RequestId>
    </ResponseMetadata>
</SetQueueAttributesResponse>