How do I configure CloudWatch Container Insights to monitor my ECS tasks and container deployment?

5 minute read

I want to configure Amazon CloudWatch Container Insights to monitor my Amazon Elastic Container Service (Amazon ECS) tasks and container deployment. How can I do this?

Short description

Container Insights collects metrics at the cluster, task, and service levels. These metrics include the use of resources such as CPU, memory, disk, and network, and they are available in CloudWatch automatic dashboards.

You can configure Amazon ECS to enable all new clusters for Container Insights by default. Or, you can enable Container Insights on individual clusters using the cluster settings during cluster creation. You can also enable Container Insights on existing clusters using the AWS Command Line Interface (AWS CLI).


Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent version of the AWS CLI.

Modify account settings

Enable Container Insights for all new clusters created by opting in to the Container Insights account setting.

Modify account settings using the CloudWatch console

  1. Open the Amazon ECS console.
  2. In the navigation pane, choose the Region that you want to modify account settings for.
  3. Choose Account Settings.
  4. In the CloudWatch Container Insights section, you can select or deselect the check box for each accunt setting for the authenticated AWS Identity and Access Management (IAM) user and role. Choose Save after you finish.
  5. On the confirmation screen, choose Confirm to save the selection.

When you log in as the AWS account root user, you can change the account's default setting. Or you can change the setting of any specific IAM user or IAM role in the account.

Modify the default account settings for all IAM users or roles on your account (AWS CLI)

Use this command to modify the default account setting for all IAM users or roles on your account. The resulting changes apply to the entire AWS account unless an IAM user or role explicitly overrides these settings.

aws ecs put-account-setting-default --name containerInsights --value enabled --region <REGION_NAME>

For more information, see Modifying account settings.

Create a cluster with Container Insights enabled

You can use either the Amazon ECS console or the AWS CLI to enable Container Insights during cluster creation.

Create a cluster with Container Insights enabled using the console

Note: Be sure that you use the new Amazon ECS console (v2) to complete these steps. If you want to use the classic console, see Creating a cluster using the classic console.

  1. Open the new Amazon ECS console.
  2. In the navigation pane, choose the Region you want to create your cluster in.
  3. Choose Clusters, and then choose Create cluster.
  4. In the Cluster configuration section, choose the required settings to create your cluster.
  5. Expand Monitoring, and then turn on Use Container Insights.
  6. Choose Create.

Create a cluster with Container Insights enabled using the AWS CLI

To create a new cluster with Container Insights enabled, run this command:

aws ecs create-cluster --cluster-name <CLUSTER_NAME> --settings "name=containerInsights,value=enabled" --region <REGION_NAME>

Enable Container Insights on an existing Amazon ECS cluster

To enable Container Insights on an existing cluster, run this command:

aws ecs update-cluster-settings --cluster <CLUSTER_NAME> --settings name=containerInsights,value=enabled --region <REGION_NAME>

Container Insights considerations

When you use CloudWatch Container Insights, be aware of the following:

  • When you use an Amazon Elastic Compute Cloud (Amazon EC2) launch type, your task doesn't need to have container CPU resource configurations. To show CPU utilization metrics at ECS task level, define the CPU parameter at task level or container level in the task definition.
  • Network metrics are available for all tasks that run on AWS Fargate. Network metrics are also available for tasks that run on Amazon EC2 instances using either the bridge or awsvpc network modes.
  • To collect instance-level metrics from ECS clusters that are hosted on an EC2 instance, deploy the CloudWatch agent.

Use CloudWatch Logs Insights to view Container Insights data

The metrics collected by Containers Insights for Amazon ECS isn't granular enough to allow tracking of single tasks. This is because the metrics available are all aggregated and averaged at the task definition family level. To do a deeper analysis of the performance data that is collected, use CloudWatch Logs Insights queries.

Container Insights performance metrics are automatically collected in the form of logs using performance log events. Open to the CloudWatch Logs insights console and select a log group in this format:


For example, this query displays task-level usage for CPU and memory:

stats avg(CpuUtilized) as CPU, avg(MemoryUtilized) as Mem by TaskId
| filter Type="Task"
| sort Mem, CPU desc

Related information

Amazon ECS Container Insights metrics

Setting up Container Insights on Amazon ECS for cluster- and service-level metrics

Deploying the CloudWatch agent to collect EC2 instance-level metrics on Amazon ECS

Viewing Container Insights metrics

AWS OFFICIALUpdated 2 years ago