Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

Amazon ECS Events

Amazon ECS tracks the state of each of your task. If the state of a task changes, an event is triggered and is sent to CloudWatch Events. These events are classified as task state change events. These events and their possible causes are described in greater detail in the following sections.

Note

Amazon ECS may add other event types, sources, and details in the future. If you are programmatically deserializing event JSON data, make sure that your application is prepared to handle unknown properties to avoid issues if and when these additional properties are added.

Events contain two version fields; one in the main body of the event, and one in the detail object of the event.

  • The version in the main body of the event is set to 0 on all events. For more information about CloudWatch Events parameters, see Events and Event Patterns in the Amazon CloudWatch Events User Guide.

  • The version in the detail object of the event describes the version of the associated resource. Each time a resource changes state, this version is incremented. Because events can be sent multiple times, this field allows you to identify duplicate events (they have the same version in the detail object). If you are replicating your task state with CloudWatch Events, you can compare the version of a resource reported by the Amazon ECS APIs with the version reported in CloudWatch Events for the resource (inside the detail object) to verify that the version in your event stream is current.

Task State Change Events

The following scenarios trigger task state change events:

You call the StartTask, RunTask, or StopTask API operations (either directly, or with the AWS Management Console, AWS CLI, or SDKs).

Starting or stopping tasks creates new task resources or modifies the state of existing task resources.

The Amazon ECS service scheduler starts or stops a task.

Starting or stopping tasks creates new task resources or modifies the state of existing task resources.

The Amazon ECS container agent calls the SubmitTaskStateChange API operation.

The Amazon ECS container agent monitors the state of your tasks and it reports any state changes (for example, from PENDING to RUNNING, or from RUNNING to STOPPED.

A container in the task changes state.

The Amazon ECS container agent monitors the state of containers within tasks. For example, if a container that is running within a task stops, this container state change triggers an event.

Example Task State Change Event

Task state change events are delivered in the following format (the detail section below resembles the Task object that is returned from a DescribeTasks API operation in the Amazon Elastic Container Service API Reference). For more information about CloudWatch Events parameters, see Events and Event Patterns in the Amazon CloudWatch Events User Guide.

{ "version": "0", "id": "9bcdac79-b31f-4d3d-9410-fbd727c29fab", "detail-type": "ECS Task State Change", "source": "aws.ecs", "account": "111122223333", "time": "2016-12-06T16:41:06Z", "region": "us-east-1", "resources": [ "arn:aws:ecs:us-east-1:111122223333:task/b99d40b3-5176-4f71-9a52-9dbd6f1cebef" ], "detail": { "clusterArn": "arn:aws:ecs:us-east-1:111122223333:cluster/default", "containerInstanceArn": "arn:aws:ecs:us-east-1:111122223333:container-instance/b54a2a04-046f-4331-9d74-3f6d7f6ca315", "containers": [ { "containerArn": "arn:aws:ecs:us-east-1:111122223333:container/3305bea1-bd16-4217-803d-3e0482170a17", "exitCode": 0, "lastStatus": "STOPPED", "name": "xray", "taskArn": "arn:aws:ecs:us-east-1:111122223333:task/b99d40b3-5176-4f71-9a52-9dbd6f1cebef" } ], "createdAt": "2016-12-06T16:41:05.702Z", "desiredStatus": "RUNNING", "group": "task-group", "lastStatus": "RUNNING", "overrides": { "containerOverrides": [ { "name": "xray" } ] }, "startedAt": "2016-12-06T16:41:06.8Z", "startedBy": "ecs-svc/9223370556150183303", "updatedAt": "2016-12-06T16:41:06.975Z", "taskArn": "arn:aws:ecs:us-east-1:111122223333:task/b99d40b3-5176-4f71-9a52-9dbd6f1cebef", "taskDefinitionArn": "arn:aws:ecs:us-east-1:111122223333:task-definition/xray:2", "version": 4 } }

On this page: