Configuring a dead-letter queue for EventBridge Scheduler - EventBridge Scheduler

Configuring a dead-letter queue for EventBridge Scheduler

EventBridge Scheduler supports dead-letter queues using Amazon SQS. When a schedule fails to invoke its target, EventBridge Scheduler delivers a dead-letter event to the resource you specify, allowing you to troubleshoot issues with your schedule or targets. If you've configured a retry policy for your schedule, EventBridge Scheduler delivers the dead-letter event after exhausting the maximum number of retries you set in the retry policy.

The following topics describe how you can configure an Amazon SQS queue as a DLQ for your schedule, set up the permissions EventBridge Scheduler needs to deliver messages to Amazon SQS, and receive dead-letter events from the DLQ.

Create an Amazon SQS queue

Before you can configure a DLQ for your schedule, you must create an Amazon SQS queue. For instructions on creating a queue using the Amazon SQS console, see Creating an Amazon SQS queue in the Amazon Simple Queue Service Developer Guide.

Note

EventBridge Scheduler does not support using a FIFO queue as your schedule's DLQ.

You can use the following AWS CLI command to create a queue.

$ aws sqs create-queue --queue-name queue-name

If successful, you'll see the QueueURL in the output.

{
    "QueueUrl": "https://sqs.us-west-2.amazonaws.com/123456789012/scheduler-dlq-test"
}

After you've created the queue, note the queue ARN. You'll need the ARN when you specify a DLQ for your EventBridge Scheduler schedule. You can find your queue ARN in the Amazon SQS console, or by using the get-queue-attributes AWS CLI command.

$ aws sqs get-queue-attributes --queue-url your-dlq-url --attribute-names QueueArn

If successful, you'll see the queue ARN in the output.

{
    "Attributes": {
        "QueueArn": "arn:aws:sqs:us-west-2:123456789012:scheduler-dlq-test"
    }
}

In the next section, you'll add the required permissions to your schedule execution role to allow EventBridge Scheduler to deliver dead-letter events to Amazon SQS.

Set up execution role permissions

To allow EventBridge Scheduler to deliver dead-letter events to Amazon SQS, your schedule execution role needs the following permission policy.

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "sqs:SendMessage" ], "Effect": "Allow", "Resource": "*" } ] }
Note

Your schedule execution role might already have the required permissions attached if you use EventBridge Scheduler to invoke an Amazon SQS API target.

In the next section, you'll use the EventBridge Scheduler console and specify a DLQ for your schedule.

Specify a DLQ in the EventBridge Scheduler console

You can use the EventBridge Scheduler console when you create a new schedule, or edit an existing schedule, to specify a DLQ.

To specify a DLQ using the console
  1. Sign in to the AWS Management Console, then choose the following link to open the EventBridge Scheduler section of the EventBridge conosle: https://us-west-2.console.aws.amazon.com/scheduler/home?region=us-west-2#home

    Note

    You can switch your Region by using the AWS Management Console's Region selector.

  2. On the EventBridge Scheduler console, either create a new schedule, or choose an existing schedule from your list of schedules to edit.

  3. On the Settings page, for Dead-letter queue (DLQ), do one of the following:

    • Choose Select an Amazon SQS queue in my AWS account as a DLQ, then choose the queue ARN for your DLQ from the dropdown list.

    • Choose Specify an Amazon SQS queue in other AWS accounts as a DLQ, then enter the queue ARN for your DLQ. If you choose a queue in another AWS account, the EventBridge Scheduler console will not be able to display the queue ARNs in a dropdown list.

  4. Review your selections, then choose Create schedule or Save schedule to finish configuring a DLQ.

  5. (Optional) To view a schedule's DLQ details, choose the name of the schedule from the list, then choose the Dead-letter queue tab on the Schedule detail page.

In the next section, you'll use the AWS CLI to recieve a dead-letter event from the DLQ.

Check the dead-letter event

To receive a dead-letter event from your schedule's DLQ, you can use the receive-message command as shown in the following. You can receive more messages by specifying the number using the --max-number-of-messages attribute.

$ aws sqs receive-message --queue-url your-dlq-url --attribute-names All --message-attribute-names All --max-number-of-messages 1

If successful, you'll see the following output.

{
    "Messages": [
        {
            "MessageId": "2aeg3510-fe3a-4f5a-ab6a-6906560eaf7e",
            "ReceiptHandle": "AQEBkNKTdOMrWgHKPoITRBwrPoK3eCSZIcZwVqCY0BZ+FfTcORFpopJbtCqj36VbBTlHreM8+qM/m5jcwqSlAlGmIJO/hYmMgn/+dwIty9izE7HnpvRhhEyHxbeTZ5V05RbeasYaBdNyi9WLcnAHviDh6MebLXXNWoFyYNsxdwJuG0f/w3htX6r3dxpXvvFNPGoQb8ihY37+u0gtsbuIwhLtUSmE8rbldEEwiUfi3IJ1zEZpUS77n/k1GWrMrnYg0Gx/BuaLzOrFi2F738XI/Hnh45uv3ca6OYwS1ojPQ1LtX2URg1haV5884FYlaRvY8jRlpCZabTkYRTZKSXG5KNgYZnHpmsspii6JNkjitYVFKPo0H91w5zkHlSx3REAuWk7m3r7PmOMvTNPMhctbD3CkTw==",
            "MD5OfBody": "07adc3fc889d6107d8bb8fda42fe0573",
            "Body": "{\"MessageBody\":\"Hello, world!",\"QueueUrl\":\"https://sqs.us-west-2.amazonaws.com/123456789012/does-not-exist\"}",
            "Attributes": {
                "SenderId": "AROA2DZE3W4CTL5ZR7EIN:ff00212d8c453aaaae644bc6846d4723",
                "ApproximateFirstReceiveTimestamp": "1652499058144",
                "ApproximateReceiveCount": "2",
                "SentTimestamp": "1652490733042"
            },
            "MD5OfMessageAttributes": "f72c1d78100860e00403d849831d4895",
            "MessageAttributes": {
                "ERROR_CODE": {
                    "StringValue": "AWS.SimpleQueueService.NonExistentQueue",
                    "DataType": "String"
                },
                "ERROR_MESSAGE": {
                    "StringValue": "The specified queue does not exist for this wsdl version.",
                    "DataType": "String"
                },
                "EXECUTION_ID": {
                    "StringValue": "ad06616e51cdf74a",
                    "DataType": "String"
                },
                "EXHAUSTED_RETRY_CONDITION": {
                    "StringValue": "MaximumEventAgeInSeconds",
                    "DataType": "String"
                }
                "IS_PAYLOAD_TRUNCATED": {
                    "StringValue": "false",
                    "DataType": "String"
                },
                "RETRY_ATTEMPTS": {
                    "StringValue": "0",
                    "DataType": "String"
                },
                "SCHEDULED_TIME": {
                    "StringValue": "2022-05-14T01:12:00Z",
                    "DataType": "String"
                },
                "SCHEDULE_ARN": {
                    "StringValue": "arn:aws:scheduler:us-west-2:123456789012:schedule/DLQ-test",
                    "DataType": "String"
                },
                "TARGET_ARN": {
                    "StringValue": "arn:aws:scheduler:::aws-sdk:sqs:sendMessage",
                    "DataType": "String"
                }
            }
        }
    ]
}

Note the following attributes in the dead-letter event to help you identify and troubleshoot possible reasons why target inovcation has failed.

  • ERROR_CODE – Contains the error code that EventBridge Scheduler receives from the target's service API. In the preceding example, the error code returned by Amazon SQS is AWS.SimpleQueueService.NonExistentQueue. If the schedule fails to invoke a target due to an issue with EventBridge Scheduler, you'll see the following error code instead: AWS.Scheduler.InternalServerError.

  • ERROR_MESSAGE – Contains the error message that EventBridge Scheduler receives from the target's service API. In the preceding example, the error message returned by Amazon SQS is The specified queue does not exist for this wsdl version. If the schedule fails due to an issue with EventBridge Scheduler, you'll see the following error message instead: Unexpected error occurred while processing the request.

  • TARGET_ARN – The ARN of the target that your schedule invokes, in the following service ARN format: arn:aws:scheduler:::aws-sdk:service:apiAction.

  • EXHAUSTED_RETRY_CONDITION – Indicates why the event was delivered to the DLQ. This attribute will be present if the error from the target API is a retryable error, and not a permanent error. The attribute can contain the values MaximumRetryAttempts if EventBridge Scheduler sent it to the DLQ after it exceeded the maximum retry attempts you configured for the schedule, or MaximumEventAgeInSeconds, if the event is older than the maximum age you configured on the schedule and is still failing to deliver.

In the preceding example, we can determine, based on the error code, and error message provided, that the target queue we specified for the schedule does not exist.