How do I troubleshoot an Amazon EventBridge rule with Amazon ECS?

Resolution

When you use an EventBridge rule to invoke an Amazon ECS task, Amazon EventBridge calls the RunTask API to run the tasks on your behalf.

The EventBridge rule might fail to invoke your Amazon ECS task because of the following reasons:

• The EventBridge rule configuration is incorrect.
• The EventBridge rule's target configuration is incorrect.
• The AWS Identity and Management (IAM) permissions to activate the role are inadequate or absent.

Check the EventBridge rule configuration

Check whether the EventBridge rule is in ENABLED state or not. If it's in a DISABLED state, then reactivate the rule and perform tests to see if the rule creates a task. You can check whether the rule is turned on or turned off using the following ways:

Use the Amazon EventBridge console

1. Open the Amazon EventBridge console.
2. In the navigation panel, choose Rules. Under Select Event bus, select the event bus that's associated with the rule.
3. Choose the rule, and then see the Status to identify the rule status.

Use AWS CLI

1. Run the following command by passing event rule name and region. In the command output, check the State parameter to identify the rule status.

   aws events describe-rule --name "DailyLambdaFunction" --region "us-eas

   Note: If you receive errors when you run the AWS Command Line Interface (AWS CLI) commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

Make sure that the event pattern is correct and that it matches the events coming from the event source. If needed, verify the event pattern using EventBridge Sandbox.

Check the EventBridge rule's target configuration

1. Check if the ECS Cluster, TaskDefinition, and Network configuration parameters for the target associated with the EventBridge rule are accurate and working.
2. Verify that the EventBridge IAM role has the required permissions. For more information, see Amazon ECS CloudWatch Events IAM Role.
3. If the target parameters are incorrect or the IAM role is missing the required permissions, the EventBridge rule fails to invoke the ECS task. Inspect the following metrics to identify the cause:

• TriggeredRules: Check for datapoints that indicate whether the incoming events triggered the EventBridge rule.
• Invocations: Watch the datapoints that determine how many times the rule was invoked and then attempted to run the ECS task.
• FailedInvocations: Review this metric that shows the number of times the rule invocations resulted in failures. High values here might indicate that the target was misconfigured. You can view these metrics with the SUM statistic.

5. Use AWS CloudTrail to further analyze the reason for failed RunTask API calls:

6. Log in to the AWS Management Console, and then open the CloudTrail console.

7. In the navigation panel, choose Event history.

8. Filter the results by choosing Event name under the Lookup attributes dropdown list. Then, enter RunTask as an attribute in the text box. This value filters out the events related to the RunTask API.

9. Choose the time range in the time range filter based on when the ECS task was expected to run.
   Note: The preset values for time range are 30 minutes, 1 hour, 3 hours, and 12 hours. To specify a custom time range, choose Absolute range.

10. Choose the event from the result and scroll to the Event record section to see the JSON event record. Look for a failure reason under errorCode and errorMessage.

Use EventBridge DLQ

The Amazon EventBridge rule supports dead-letter queues (DLQ). DLQ uses the Amazon Simple Queue Service (Amazon SQS) to store failed invocation events in a standard queue that you specify. When the event rule doesn't invoke its target, EventBridge delivers a JSON payload containing invocation details and responses from the target to DLQ. Analyze the failed event delivery in the DLQ to resolve the issue.

Related information

How can I troubleshoot issues with Amazon EventBridge rules?

How can I use a dead-letter queue to troubleshoot FailedInvocations for EventBridge rules?