# Amazon ECS event capture in the console
<a name="task-lifecycle-events"></a>

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
<a name="task-lifecycle-events-overview"></a>

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
<a name="task-lifecycle-events-types"></a>

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
<a name="task-lifecycle-events-log-group"></a>

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}/performance`
+ An EventBridge rule that ingests all events from the `aws.ecs` source 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
<a name="task-lifecycle-events-limitations"></a>

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](https://aws.amazon.com/eventbridge/pricing/).

  For information about CloudWatch pricing, see [CloudWatch pricing](https://aws.amazon.com/cloudwatch/pricing/).

## Event-based troubleshooting
<a name="task-lifecycle-events-troubleshooting"></a>

Use Amazon ECS generated events to answer common troubleshooting questions.

### Task failure analysis
<a name="task-lifecycle-events-task-failures"></a>

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
<a name="task-lifecycle-events-common-issues"></a>

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.

# Turn on event capture for an existing Amazon ECS cluster
<a name="turn-on-event-capture-existing-cluster"></a>

You can enable event capture on an existing Amazon ECS cluster to store Amazon ECS-generated events in Amazon CloudWatch Logs through EventBridge. This feature helps you monitor and troubleshoot task failures, service deployments, and other cluster activities.

After you enable event capture, Amazon ECS creates the following resources:
+ A Amazon CloudWatch Logs log group named `/aws/events/ecs/containerinsights/${clusterName}/performance`
+ An EventBridge rule that captures all events from the `aws.ecs` source

A **History** tab displays in the cluster view, allowing you to query task lifecycle events and service actions. Event capture begins immediately and stores all Amazon ECS-generated events according to your specified retention period.

## Prerequisites
<a name="turn-on-event-capture-prerequisites"></a>
+ An existing Amazon ECS cluster
+ Appropriate IAM permissions to modify cluster settings and create Amazon CloudWatch Logs resources

## Turn on event capture using the console
<a name="turn-on-event-capture-procedure"></a>

1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. In the navigation pane, choose **Clusters**.

1. Select the cluster where you want to enable event capture.

   The cluster details page displays.

1. Choose **Configuration**.

1. In the **ECS events** section, choose **Turn on event capture**.

   The **Turn on event capture** dialog box displays.

1. For **Expire event**, choose the retention period for the Amazon CloudWatch Logs log group. The default is 7 days.

1. Choose **Turn on**.

# Viewing Amazon ECS service and task state change events
<a name="viewing-state-events"></a>

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 to enhance 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.

You can use any of the following criteria to filter the events:
+  Deployment ID (This is only available on the service detail page) 
+ Start time
+ End time 
+ Service name (only applicable on cluster detail page, on service detail page, this will be default to current service) 
+ Task ID 
+ Task Last status 
+ Task definition family 
+ Task definition revision 

## Viewing events at the cluster-level
<a name="view-cluster-procedure"></a>

1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. Choose **Clusters**.

   The clusters list page displays.

1. Choose the cluster.

   The cluster details page displays.

1. Under **History**, determine the events to view.

   1. To view service action events, choose **Service action events**.

   1. To view task state change events, choose **Task state change events**.

   1. (Optional) In **Query criteria**, enter the filters for the events that you want to view.

1. Choose **Run query**.

   The events display in a list.

1. To view the full details of the event, choose the event.

## Viewing at the service-level
<a name="tasks-procedure"></a>

1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. On the **Clusters** page, choose the cluster.

1. On the cluster details page, in the **Services** section, choose the service.

   The service details page displays.

1. Under **History**, determine the events to view.

   1. To view service action events, choose **Service action events**.

   1. To view task state change events, choose **Task state change events**.

   1. (Optional) In **Query criteria**, enter the filters for the events that you want to view.

1. Choose **Run query**.

   The events display in a list.

1. To view the full details of the event, choose the event.