Amazon ECS event capture in the console
The Amazon ECS console provides event capture functionality that stores Amazon ECS-generated events, such as service actions and task state changes, to Amazon CloudWatch Logs through EventBridge. This feature includes a query interface with filtering capabilities for monitoring and troubleshooting.
Events provide detailed information about how your service deployments, services, tasks, and instances operate. You can use this information to troubleshoot task or service deployment failures.
When you turn on event capture, you have access to all events Amazon ECS generates for a retention period of your choice, extending beyond the native limitations of the last 100 unfiltered events or stopped tasks visible for only 1 hour.
How it works
Event capture uses EventBridge to store events in a predefined Amazon CloudWatch Logs log group. The Amazon ECS console provides pre-built queries and filtering options, and correlates events to provide task lifecycles in an intuitive format.
You can query and retrieve the following types of events:
Service action events – Help identify provisioning or resource allocation issues
Task lifecycle events – Help identify why tasks or containers fail to launch or stop running
The Amazon ECS console allows you to set up event capture in one click and provides commonly used queries and filtering without requiring you to learn query languages or navigate between multiple consoles.
Event types
Event capture stores all Amazon ECS generated events in the following categories:
- Task state change events
Container stops and other termination events, which you can use for troubleshooting or to monitor task lifecycle timelines.
- Service actions
Events such as reaching steady state, failed task placement, or resource constraints.
- Service deployment state changes
Events such as in-progress, completed, or failed deployments, triggered by circuit breaker and rollback settings, to monitor the state of a service deployment.
- Container instance state changes
For workloads on EC2 and Amazon ECS Managed Instances, events show connected and disconnected status.
Log group configuration
When you turn on event capture, Amazon ECS automatically creates the following resources:
A Amazon CloudWatch Logs log group named
/aws/events/ecs/containerinsights/${clusterName}/performanceAn EventBridge rule that ingests all events from the
aws.ecssource and forwards them to the log group
You can specify a retention period for the log group from 1 day to 10 years. The default retention period is 7 days.
Considerations
Consider the following when using event capture:
Event capture stores all events for simplicity. You cannot configure rules in the Amazon ECS console to capture only specific events.
The Amazon ECS console provides predefined query criteria. For advanced queries, use Amazon CloudWatch Logs Logs Insights to query the log group directly.
Live tail functionality is not available in the Amazon ECS console. Use Amazon CloudWatch Logs directly for live tail.
When you disable event capture, the EventBridge rule is deleted.
Event capture incurs additional costs for EventBridge data ingestion, Amazon CloudWatch Logs storage, and query execution.
For information about EventBridge pricing, see EventBridge pricing
. For information about CloudWatch pricing, see CloudWatch pricing
.
Event-based troubleshooting
Use Amazon ECS generated events to answer common troubleshooting questions.
Task failure analysis
You can review STOPPED task state change events, stop codes, and container exit codes to determine why a task failed to launch or failed while running.
You can review service action events for placement failures and resource constraint information to determine why a task failed to place due to resource constraints
Common task failure scenarios
The most common abnormal task failures are related to the following issues:
CI/CD service deployment failures
Auto scaling failures
Task rebalancing failures
Abnormal container exits, such as out-of-memory (OOM) errors
Abnormal task failures produce STOPPED task state change events with an EssentialContainerExited or TaskFailedToStart stop code. You can filter by these stop codes to examine container execution and stopping behaviors.
