--- title: Amazon ECS description: >- A scalable, high performance container management service supporting Docker containers. breadcrumbs: Docs > Integrations > Amazon ECS --- # Amazon ECS {% alert level="warning" %} Looking to deploy the containerized Datadog Agent to your ECS cluster? See the [Amazon ECS Agent documentation](https://docs.datadoghq.com/agent/amazon_ecs.md). {% /alert %} ## Overview{% #overview %} Amazon ECS on EC2 is a highly scalable, high performance container management service for Docker containers running on EC2 instances. Collect ECS metrics automatically from CloudWatch using the Amazon ECS Datadog integration. Expand on those metrics by querying the ECS API for ECS events, tags, and the status of container instances, tasks, and services. ## Setup{% #setup %} ### Installation{% #installation %} If you haven't already, set up the [Amazon Web Services integration](https://docs.datadoghq.com/integrations/amazon_web_services.md?tab=automaticcloudformation#setup) first. ### Metric collection{% #metric-collection %} 1. Follow the AWS Integration [role delegation setup](https://docs.datadoghq.com/integrations/amazon_web_services.md?tab=automaticcloudformation#setup) instructions. 1. Ensure the following permissions for your [Datadog IAM policy](https://docs.datadoghq.com/integrations/amazon_web_services.md#datadog-aws-iam-policy) are set to collect Amazon ECS metrics. For more information on ECS policies, read [Actions, resources, and condition keys for Amazon Elastic Container Service](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazonelasticcontainerservice.html) in the AWS documentation. | AWS Permission | Description | | -------------------------------- | ------------------------------------------------------------- | | `ecs:ListClusters` | Returns a list of existing clusters. | | `ecs:ListContainerInstances` | Returns a list of container instances in a specified cluster. | | `ecs:ListServices` | Lists the services that are running in a specified cluster. | | `ecs:DescribeContainerInstances` | Describes Amazon ECS container instances. | In the [AWS integration page](https://app.datadoghq.com/integrations/amazon-web-services), ensure that `ECS` is enabled under the `Metric Collection` tab. When metric collection is enabled, an [out-of-the-box dashboard](https://app.datadoghq.com/screen/integration/82/aws-ecs) that provides detailed information about your ECS metrics is available for this integration. See [Monitoring ECS with Datadog](https://www.datadoghq.com/blog/monitoring-ecs-with-datadog/#get-comprehensive-visibility-with-datadog-dashboards) for more details. ## Data collected{% #data-collected %} ### Metrics{% #metrics %} | | | | | **aws.ecs.cpureservation**(gauge) | The percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cpureservation.maximum**(gauge) | The maximum percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cpureservation.minimum**(gauge) | The minimum percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cpureservation.samplecount**(count) | The sample count of CPU units that are reserved by running tasks in the cluster. | | **aws.ecs.cpuutilization**(gauge) | The percentage of CPU units that are used in the cluster or service filtered by ClusterName and ServiceName.*Shown as percent* | | **aws.ecs.cpuutilization.maximum**(gauge) | The maximum percentage of CPU units that are used in the cluster or service.*Shown as percent* | | **aws.ecs.cpuutilization.minimum**(gauge) | The minimum percentage of CPU units that are used in the cluster or service.*Shown as percent* | | **aws.ecs.cpuutilization.samplecount**(count) | The sample count of CPU units that are used in the cluster or service. | | **aws.ecs.memory\_reservation**(gauge) | The percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.memory\_reservation.maximum**(gauge) | The maximum percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.memory\_reservation.minimum**(gauge) | The minimum percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.memory\_utilization**(gauge) | The percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.memory\_utilization.maximum**(gauge) | The maximum percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.memory\_utilization.minimum**(gauge) | The minimum percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.cluster.cpureservation**(gauge) | The percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.cpureservation.maximum**(gauge) | The maximum percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.cpureservation.minimum**(gauge) | The minimum percentage of CPU units that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.cpuutilization**(gauge) | The percentage of CPU units that are used in the cluster or service filtered by ClusterName.*Shown as percent* | | **aws.ecs.cluster.cpuutilization.maximum**(gauge) | The maximum percentage of CPU units that are used in the cluster or service.*Shown as percent* | | **aws.ecs.cluster.cpuutilization.minimum**(gauge) | The minimum percentage of CPU units that are used in the cluster or service.*Shown as percent* | | **aws.ecs.cluster.memory\_reservation**(gauge) | The percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.memory\_reservation.maximum**(gauge) | The maximum percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.memory\_reservation.minimum**(gauge) | The minimum percentage of memory that is reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.cluster.memory\_utilization**(gauge) | The percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.cluster.memory\_utilization.maximum**(gauge) | The maximum percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.cluster.memory\_utilization.minimum**(gauge) | The minimum percentage of memory that is used in the cluster or service.*Shown as percent* | | **aws.ecs.pending\_tasks\_count**(gauge) | The number of tasks on the container instance that are in the PENDING status.*Shown as task* | | **aws.ecs.registered\_cpu**(gauge) | The number of CPU units registered on the container instance | | **aws.ecs.registered\_memory**(gauge) | The number of Memory units registered on the container instance | | **aws.ecs.remaining\_cpu**(gauge) | The number of CPU units remaining on the container instance | | **aws.ecs.remaining\_memory**(gauge) | The number of Memory units remaining on the container instance | | **aws.ecs.running\_tasks\_count**(gauge) | The number of tasks on the container instance that are in the RUNNING status.*Shown as task* | | **aws.ecs.service.cpuutilization**(gauge) | Average percentage of CPU units that are used in the service.*Shown as percent* | | **aws.ecs.service.cpuutilization.maximum**(gauge) | Maximum percentage of CPU units that are used in the service.*Shown as percent* | | **aws.ecs.service.cpuutilization.minimum**(gauge) | Minimum percentage of CPU units that are used in the service.*Shown as percent* | | **aws.ecs.service.desired**(gauge) | The number of tasks in the cluster that are in the desired state | | **aws.ecs.service.memory\_utilization**(gauge) | Average percentage of memory that is used in the service.*Shown as percent* | | **aws.ecs.service.memory\_utilization.maximum**(gauge) | Maximum percentage of memory that is used in the service.*Shown as percent* | | **aws.ecs.service.memory\_utilization.minimum**(gauge) | Minimum percentage of memory that is used in the service.*Shown as percent* | | **aws.ecs.service.pending**(gauge) | The number of tasks in the cluster that are in the pending state*Shown as task* | | **aws.ecs.service.running**(gauge) | The number of tasks in the cluster that are in the running state*Shown as task* | | **aws.ecs.services**(gauge) | The number of services running per cluster | | **ecs.containerinsights.container\_instance\_count**(count) | The number of EC2 instances running the Amazon ECS agent that are registered with a cluster.*Shown as instance* | | **ecs.containerinsights.container\_instance\_count.maximum**(count) | The maximum number of EC2 instances running the Amazon ECS agent that are registered with a cluster.*Shown as instance* | | **ecs.containerinsights.container\_instance\_count.minimum**(count) | The minimum number of EC2 instances running the Amazon ECS agent that are registered with a cluster.*Shown as instance* | | **ecs.containerinsights.container\_instance\_count.samplecount**(count) | A sample count of EC2 instances running the Amazon ECS agent that are registered with a cluster.*Shown as instance* | | **ecs.containerinsights.container\_instance\_count.sum**(count) | The sum of EC2 instances running the Amazon ECS agent that are registered with a cluster.*Shown as instance* | | **ecs.containerinsights.cpu\_reserved**(gauge) | The CPU units reserved by tasks in the specified resource for the chosen dimension. | | **ecs.containerinsights.cpu\_reserved.maximum**(gauge) | The maximum CPU units reserved by tasks in the specified resource for the chosen dimension. | | **ecs.containerinsights.cpu\_reserved.minimum**(gauge) | The minimum CPU units reserved by tasks in the specified resource for the chosen dimension. | | **ecs.containerinsights.cpu\_reserved.samplecount**(gauge) | A sample count of CPU units reserved by tasks in the specified resource for the chosen dimension. | | **ecs.containerinsights.cpu\_reserved.sum**(gauge) | The sum of CPU units reserved by tasks in the specified resource for the chosen dimension. | | **ecs.containerinsights.cpu\_utilized**(gauge) | The CPU units used by tasks in the specified resource for the chosen dimension.*Shown as percent* | | **ecs.containerinsights.cpu\_utilized.maximum**(gauge) | The maximum CPU units used by tasks in the specified resource for the chosen dimension.*Shown as percent* | | **ecs.containerinsights.cpu\_utilized.minimum**(gauge) | The minimum CPU units used by tasks in the specified resource for the chosen dimension.*Shown as percent* | | **ecs.containerinsights.cpu\_utilized.samplecount**(gauge) | A sample count of CPU units used by tasks in the specified resource for the chosen dimension.*Shown as percent* | | **ecs.containerinsights.cpu\_utilized.sum**(gauge) | The sum of CPU units used by tasks in the specified resource for the chosen dimension.*Shown as percent* | | **ecs.containerinsights.deployment\_count**(count) | The number of deployments in an Amazon ECS service. | | **ecs.containerinsights.deployment\_count.maximum**(count) | The maximum number of deployments in an Amazon ECS service. | | **ecs.containerinsights.deployment\_count.minimum**(count) | The minimum number of deployments in an Amazon ECS service. | | **ecs.containerinsights.deployment\_count.samplecount**(count) | A sample count of the deployments in an Amazon ECS service. | | **ecs.containerinsights.deployment\_count.sum**(count) | The sum of deployments in an Amazon ECS service. | | **ecs.containerinsights.desired\_task\_count**(count) | The number of desired tasks for an Amazon ECS service.*Shown as task* | | **ecs.containerinsights.desired\_task\_count.maximum**(count) | The maximum number of desired tasks for an Amazon ECS service.*Shown as task* | | **ecs.containerinsights.desired\_task\_count.minimum**(count) | The minimum number of desired tasks for an Amazon ECS service.*Shown as task* | | **ecs.containerinsights.desired\_task\_count.samplecount**(count) | A sample count of desired tasks for an Amazon ECS service.*Shown as task* | | **ecs.containerinsights.desired\_task\_count.sum**(count) | The sum of desired tasks for an Amazon ECS service.*Shown as task* | | **ecs.containerinsights.memory\_reserved**(gauge) | The memory reserved by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_reserved.maximum**(gauge) | The maximum memory reserved by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_reserved.minimum**(gauge) | The minimum memory reserved by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_reserved.samplecount**(gauge) | A sample count of memory reserved by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_reserved.sum**(gauge) | The sum of memory reserved by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_utilized**(gauge) | The memory being used by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_utilized.maximum**(gauge) | The maximum memory being used by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_utilized.minimum**(gauge) | The minimum memory being used by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_utilized.samplecount**(gauge) | A sample count of memory being used by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.memory\_utilized.sum**(gauge) | The sum of memory being used by tasks in the specified resource for the chosen dimension.*Shown as megabyte* | | **ecs.containerinsights.pending\_task\_count**(count) | The number of tasks currently in the PENDING state.*Shown as task* | | **ecs.containerinsights.pending\_task\_count.maximum**(count) | The maximum number of tasks currently in the PENDING state.*Shown as task* | | **ecs.containerinsights.pending\_task\_count.minimum**(count) | The minimum number of tasks currently in the PENDING state.*Shown as task* | | **ecs.containerinsights.pending\_task\_count.samplecount**(count) | A sample count of tasks currently in the PENDING state.*Shown as task* | | **ecs.containerinsights.pending\_task\_count.sum**(count) | The sum of tasks currently in the PENDING state.*Shown as task* | | **ecs.containerinsights.running\_task\_count**(count) | The number of tasks currently in the RUNNING state.*Shown as task* | | **ecs.containerinsights.running\_task\_count.maximum**(count) | The maximum number of tasks currently in the RUNNING state.*Shown as task* | | **ecs.containerinsights.running\_task\_count.minimum**(count) | The minimum number of tasks currently in the RUNNING state.*Shown as task* | | **ecs.containerinsights.running\_task\_count.samplecount**(count) | A sample count of tasks currently in the RUNNING state.*Shown as task* | | **ecs.containerinsights.running\_task\_count.sum**(count) | The sum of tasks currently in the RUNNING state.*Shown as task* | | **ecs.containerinsights.service\_count**(count) | The number of services in the cluster.*Shown as service* | | **ecs.containerinsights.service\_count.maximum**(count) | The maximum number of services in the cluster.*Shown as service* | | **ecs.containerinsights.service\_count.minimum**(count) | The minimum number of services in the cluster.*Shown as service* | | **ecs.containerinsights.service\_count.samplecount**(count) | A sample count of services in the cluster.*Shown as service* | | **ecs.containerinsights.service\_count.sum**(count) | The sum of services in the cluster.*Shown as service* | | **ecs.containerinsights.storage\_read\_bytes**(gauge) | The number of bytes read from storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_read\_bytes.maximum**(gauge) | The maximum number of bytes read from storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_read\_bytes.minimum**(gauge) | The minimum number of bytes read from storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_read\_bytes.samplecount**(gauge) | A sample count of bytes read from storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_read\_bytes.sum**(gauge) | The sum of bytes read from storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_write\_bytes**(gauge) | The number of bytes written to storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_write\_bytes.maximum**(gauge) | The maximum number of bytes written to storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_write\_bytes.minimum**(gauge) | The minimum number of bytes written to storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_write\_bytes.samplecount**(gauge) | A sample count of bytes written to storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.storage\_write\_bytes.sum**(gauge) | The sum of bytes written to storage in the specified resource for the chosen dimension.*Shown as byte* | | **ecs.containerinsights.task\_count**(count) | The number of tasks running in the service.*Shown as task* | | **ecs.containerinsights.task\_count.maximum**(count) | The maximum number of tasks running in the service.*Shown as task* | | **ecs.containerinsights.task\_count.minimum**(count) | The minimum number of tasks running in the service.*Shown as task* | | **ecs.containerinsights.task\_count.samplecount**(count) | A sample count of tasks running in the service.*Shown as task* | | **ecs.containerinsights.task\_count.sum**(count) | The sum of tasks running in the service.*Shown as task* | | **ecs.containerinsights.task\_set\_count**(count) | The number of task sets in the service.*Shown as task* | | **ecs.containerinsights.task\_set\_count.maximum**(count) | The maximum number of task sets in the service.*Shown as task* | | **ecs.containerinsights.task\_set\_count.minimum**(count) | The minimum number of task sets in the service.*Shown as task* | | **ecs.containerinsights.task\_set\_count.samplecount**(count) | A sample count of task sets in the service.*Shown as task* | | **ecs.containerinsights.task\_set\_count.sum**(count) | The sum of task sets in the service.*Shown as task* | Each of the metrics retrieved from AWS is assigned the same tags that appear in the AWS console, including but not limited to hostname, security-groups, and more. **Note**: Metrics prefixed with `ecs.containerinsights.*` can be collected by enabling `Collect custom metrics` under the `Metric Collection` tab of the [AWS Integration page](https://app.datadoghq.com/integrations/amazon-web-services). ### Events{% #events %} To reduce noise, the Amazon ECS integration is automatically set up to include only events that contain the following words: `drain`, `error`, `fail`, `insufficient memory`, `pending`, `reboot`, `terminate`. See example events below: To remove the inclusion list and receive all events from your Datadog Amazon ECS integration, reach out to [Datadog support](https://docs.datadoghq.com/help/). ### Service Checks{% #service-checks %} **aws.ecs.agent\_connected** Whether the ECS Agent is connected. *Statuses: ok, critical* ## Troubleshooting{% #troubleshooting %} Need help? Contact [Datadog support](https://docs.datadoghq.com/help/). ## Further Reading{% #further-reading %} - [Key ECS metrics to monitor](https://www.datadoghq.com/blog/amazon-ecs-metrics) - [Amazon ECS on AWS Fargate](https://docs.datadoghq.com/integrations/ecs_fargate.md)