Containers

Troubleshooting containerized workloads with Amazon ECS Events in the AWS console

Amazon Elastic Container Service (Amazon ECS) generates detailed events, from task launches to service deployments, which are critical for maintaining reliable container operations and resolving issues efficiently.

Although Amazon ECS events are emitted to Amazon EventBridge, you need to manually configure EventBridge rules, set up Amazon CloudWatch log groups, and build custom queries to gain operational insights. In this post, we show how you can use the new event capture capability in the Amazon ECS console to automatically collect and analyze operational events. We demonstrate how to enable Amazon ECS event capture with a single click and use the integrated query interface to investigate operational scenarios such as task failures, deployment, and resource constraints issues.

This approach removes the need to manually set up event routing across multiple services or write complex CloudWatch Logs Insights queries. Whether you are investigating intermittent task failures, tracking deployment progress, or analyzing scaling patterns, you can now access all relevant event data directly from the Amazon ECS console.

Feature overview

When you enable event capture in the Amazon ECS console, the feature creates an automated pipeline that collects, stores, and makes your container infrastructure events queryable. The solution consists of three components:

  • Event collection
    • An EventBridge rule automatically captures all events from the aws.ecs source.
    • Events include task state changes, service actions, deployment states, and container instance changes.
    • The rule is scoped to your specific cluster to enable relevant event capture.
  • Event storage
    • Events are stored in a dedicated CloudWatch Logs log group: /aws/events/ecs/containerinsights/${clusterName}/performance
    • You can configure retention periods from 1 day to 10 years to match your operational needs.
    • Events are indexed for efficient querying and analysis.
  • Query interface
    • The Amazon ECS console offers built-in query capabilities
    • Pre-configured templates for common troubleshooting scenarios
    • Time-based filtering with both relative and absolute ranges
    • Hierarchical navigation from cluster to service to task level
    • CloudWatch Logs Insights for custom queries

When the feature is enabled, review the EventBridge rule pattern to make sure that it aligns with your organizations security requirements. Furthermore, AWS CloudTrail can be enabled to maintain an audit of actions taken relating to this feature.

The types of events captured include the following:

Event type Description Common use cases
Task state changes Lifecycle events for Amazon ECS tasks Troubleshoot task failures, analyze startup patterns
Service actions Service-level operations Track scaling events, monitor deployment progress
Deployment states Changes in deployment status Debug rolling updates, validate blue/green deployments
Container instance changes Amazon ECS agent and instance status Monitor cluster capacity, investigate instance health

In this walkthrough, you enable Amazon ECS Event Capture in the console, deploy sample workloads, and analyze operational events using CloudWatch Logs Insights queries.

Prerequisites

You need the following prerequisites to complete this solution:

Make sure that the principle of least privilege and resource level restriction is followed when assigning any permissions to IAM roles and users. More information on this can be found in this CloudWatch post.

To enable event capture:

  1. Open your cluster in the Amazon ECS console.
  2. Navigate to the Configurations tab.
  3. Go to the Capture ECS events section.
  4. Choose Turn On event capture.Comprehensive AWS ECS cluster management interface showcasing the configuration panel with multiple management features. The interface presents a hierarchical structure including service definitions, task management, and infrastructure settings. Key components include: Navigation tabs for Services, Tasks, Infrastructure, Configuration, and Event history ECS events section with EventBridge integration capabilities CloudFormation stack reference Capacity provider strategy settings Event capture configuration with CloudWatch integration Infrastructure monitoring and logging options The interface emphasizes AWS's integrated approach to container orchestration and monitoring, allowing users to configure event capture for comprehensive container lifecycle management.
  5. Choose your retention period.
  6. Choose Turn On to enable the feature.

When it is enabled, you should see Turned on in the Amazon ECS events capture section, and a new Event History tab is ready to use for both the cluster and service views, as shown in the following figure.Detailed Amazon ECS events management panel highlighting: Enabled event capture status with green indicator EventBridge integration for container monitoring 7-day retention period for event storage Configured CloudWatch log group with specific path (/aws/events/ecs/containerinsights/sample-bg-cluster/performance) Active EventBridge rule with sample configuration Integration with CloudWatch for event storage and querying The interface demonstrates the complete setup for ECS event monitoring and storage with specified retention policies and logging configurations.

The Event History tab offers two integrated views for comprehensive event analysis, as shown in the following figure.

Comprehensive ECS event history management interface displaying: Prominent notification that event capture requires enablement Task state change and service action event type options Customizable time range defaulting to 24 hours Advanced query criteria with multiple property filters including: Task ID Task definition family Task definition revision Deployment ID Sortable columns for event monitoring Integration with CloudWatch for event logging

Service event analysis: Track service-specific events through chronological timelines showing deployment progressions, task placements, and scaling activities. Navigate directly from events to affected resources for rapid troubleshooting.

Task lifecycle visualization: Examine complete task execution patterns with state transitions, timestamps, stop reasons, and exit codes. Drill down to container-level details including resource allocation and network configuration for root cause analysis.

All views feature filtering by task status, stop codes, exit reasons, and custom time ranges. You can use this to quickly pinpoint issues and identify patterns across your container infrastructure.

Consider a scenario where you are looking to get insight into why tasks within your Amazon ECS service are stopping. You can find all of the tasks stopped events from the cluster using the Task state change event type, your necessary time range, and the Last status = STOPPED query criteria, as shown in the following figure.

Comprehensive ECS event history query interface showing: Navigation options for EventBridge rule and CloudWatch log group access Task state monitoring configuration with: Event type selection (Task state change selected) 24-hour time range setting Query criteria with Task ID filter Status filter set to "STOPPED" Run/Stop query controls with 60-minute timeout notice Results section displaying: One task state change event Detailed columns for Task ID, Last status, Update time, Stop reason, and Event ID Task stopped by user on October 8, 2025 Sortable columns and pagination controls The interface provides complete task monitoring capabilities with integrated AWS service connections.

You could also have a scenario where you are investigating the timeline for a given deployment, and you would like to look at how the deployment progressed. You can use the Task state change event type and the Deployment ID = query filter, as shown in the following figure.

Comprehensive ECS event history interface displaying: Service context: nginx-fargate-service within shy-zebra-8owuqq cluster Event type selection focused on task state changes Specific deployment ID filter with clear filter option Query results showing 4 related task state changes including: Task progression through multiple states (Provisioning → Pending → Running) Consistent task ID pattern across state changes Chronological progression of events on October 8, 2025 Full event tracking with unique Event IDs

Cleaning up

If you need to disable event capture, then follow these steps:

  1. Open your cluster in the Amazon ECS console.
  2. Navigate to the Configurations tab.
  3. Go to the Capture ECS events section.
  4. Choose Actions and choose Turn off event capture.
  5. Choose Turn off to disable the feature. The log group still exists, but the events are no longer generated after you turn off this feature.
  6. If the CloudWatch log group is no longer needed, then navigate to CloudWatch Logs and delete the log group that was created when the feature was turned on.

Pricing

The event capture feature uses existing AWS services and is billed according to standard EventBridge and CloudWatch Logs pricing models.

Cost optimization strategies include using targeted time ranges in queries to minimize data scanning, setting retention periods that balance operational needs with costs such as shorter retention for non-production environments, and using query results to proactively address recurring issues. These approaches, combined with monitoring usage patterns, help maximize value while managing costs.

Conclusion

The event capture capability in the Amazon ECS console streamlines operational troubleshooting by providing integrated access to your container infrastructure’s event history. With a single click you can now automatically capture all Amazon ECS events without manual Amazon EventBridge configuration, query and analyze events directly from the Amazon ECS console, track task lifecycles, service deployments, and scaling activities, all while maintaining operational visibility with configurable retention periods.

Enable event capture on your ECS clusters today and unlock the full potential of Amazon ECS event observability. Transform how your team troubleshoots issues, enhances performance, and maintains reliability with comprehensive event history, all one click away in the Amazon ECS console.

To learn more about enabling event capture and retrieval from the console, visit the documentation and start building your operational excellence practice today.

Before enabling this solution in a production environment, you must conduct a thorough security assessment and implement more security controls appropriate for your workload. We also recommend reviewing and complying with your organization’s security policies and consulting with your security team for production hardening.

About the authors

Rohan Mangal is a seasoned DevOps engineer with 15 years in cloud platforms. At AWS, he specializes in Amazon EKS, ECS, Fargate, and HPC, with deep expertise in cloud-native architectures, production-grade MLOps on Kubernetes, and day-2 operations. He solves complex architectural challenges for customers, delivering reusable IaC blueprints, GitOps pipelines, and operational playbooks for secure, cost-efficient production rollouts.

Nataizya Sikasote has a strong interest in containers (specifically ECS and Kubernetes) and hands-on development experience in Python and infrastructure as code using CloudFormation and CDK, he brings a comprehensive understanding of both the technical and operational aspects of modern container platforms. Nataizya enjoys enabling customers to build, deploy, and scale containerized applications effectively on AWS.

Stacey Hou is a Senior Product Manager – Technical at AWS, where she focuses on GenAI initiatives and observability for Amazon Elastic Container Service (ECS). She works closely with customers and engineering teams to drive innovations that simplify the experience of building, operating, and troubleshooting containerized applications.