--- title: Amazon ECS description: >- A scalable, high performance container management service supporting Docker containers. breadcrumbs: Docs > Integrations > Amazon ECS --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Amazon ECS Integration version1.0.0 {% callout %} # Important note for users on the following Datadog sites: us2.ddog-gov.com {% alert level="info" %} To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator. To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com). {% /alert %} {% /callout %} {% 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/dash/integration/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.live_task_count**(gauge) | The number of tasks in the ACTIVATING, RUNNING, and DEACTIVATING lifecycle states for the cluster or service.*Shown as task* | | **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.live_task_count**(gauge) | The number of tasks in the ACTIVATING, RUNNING, and DEACTIVATING lifecycle states for the service.*Shown as task* | | **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 | 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.*` are provided by the [Amazon ECS Container Insights](https://app.datadoghq.com/integrations/amazon-ecs-container-insights) integration. ### 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 %} Additional helpful documentation, links, and articles: - [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)