--- 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.1.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.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.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.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.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.cluster.cpuutilization.samplecount**(count) | The sample count of CPU units that are used in the cluster. | | **aws.ecs.service.cpuutilization.samplecount**(count) | The sample count of CPU units that are used in the 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.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.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.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.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.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.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.active_connection_count**(gauge) | The average number of concurrent connections active from clients to the Service Connect proxies that run in tasks that share the selected discovery name.*Shown as connection* | | **aws.ecs.service.active_connection_count**(gauge) | The average number of concurrent connections active from clients to the Service Connect proxies that run in tasks that share the selected discovery name for the service.*Shown as connection* | | **aws.ecs.console_status**(gauge) | The average console status reported. | | **aws.ecs.service.console_status**(gauge) | The average console status reported for the service. | | **aws.ecs.ebsfilesystem_utilization**(gauge) | The average percentage of the Amazon EBS filesystem that is used by tasks.*Shown as percent* | | **aws.ecs.service.ebsfilesystem_utilization**(gauge) | The average percentage of the Amazon EBS filesystem that is used by tasks for the service.*Shown as percent* | | **aws.ecs.gpureservation**(gauge) | The average percentage of total available GPUs that are reserved by running tasks.*Shown as percent* | | **aws.ecs.cluster.gpureservation**(gauge) | The average percentage of total available GPUs that are reserved by running tasks in the cluster.*Shown as percent* | | **aws.ecs.grpc_request_count**(gauge) | The average number of gRPC inbound traffic requests processed by the Service Connect proxies.*Shown as request* | | **aws.ecs.service.grpc_request_count**(gauge) | The average number of gRPC inbound traffic requests processed by the Service Connect proxies for the service.*Shown as request* | | **aws.ecs.httpcode_target_2xxcount**(gauge) | The average number of HTTP response codes with numbers 200 to 299 generated by the applications in the target tasks.*Shown as response* | | **aws.ecs.service.httpcode_target_2xxcount**(gauge) | The average number of HTTP response codes with numbers 200 to 299 generated by the applications in the target tasks for the service.*Shown as response* | | **aws.ecs.httpcode_target_3xxcount**(gauge) | The average number of HTTP response codes with numbers 300 to 399 generated by the applications in the target tasks.*Shown as response* | | **aws.ecs.service.httpcode_target_3xxcount**(gauge) | The average number of HTTP response codes with numbers 300 to 399 generated by the applications in the target tasks for the service.*Shown as response* | | **aws.ecs.httpcode_target_4xxcount**(gauge) | The average number of HTTP response codes with numbers 400 to 499 generated by the applications in the target tasks.*Shown as response* | | **aws.ecs.service.httpcode_target_4xxcount**(gauge) | The average number of HTTP response codes with numbers 400 to 499 generated by the applications in the target tasks for the service.*Shown as response* | | **aws.ecs.httpcode_target_5xxcount**(gauge) | The average number of HTTP response codes with numbers 500 to 599 generated by the applications in the target tasks.*Shown as response* | | **aws.ecs.service.httpcode_target_5xxcount**(gauge) | The average number of HTTP response codes with numbers 500 to 599 generated by the applications in the target tasks for the service.*Shown as response* | | **aws.ecs.new_connection_count**(gauge) | The average number of new connections established from clients to the Service Connect proxies that run in tasks that share the selected discovery name.*Shown as connection* | | **aws.ecs.service.new_connection_count**(gauge) | The average number of new connections established from clients to the Service Connect proxies that run in tasks that share the selected discovery name for the service.*Shown as connection* | | **aws.ecs.processed_bytes**(gauge) | The average number of bytes of inbound traffic processed by the Service Connect proxies.*Shown as byte* | | **aws.ecs.service.processed_bytes**(gauge) | The average number of bytes of inbound traffic processed by the Service Connect proxies for the service.*Shown as byte* | | **aws.ecs.request_count**(gauge) | The average number of inbound traffic requests processed by the Service Connect proxies.*Shown as request* | | **aws.ecs.service.request_count**(gauge) | The average number of inbound traffic requests processed by the Service Connect proxies for the service.*Shown as request* | | **aws.ecs.request_count_per_target**(gauge) | The average number of requests received by each target that share the selected discovery name.*Shown as request* | | **aws.ecs.service.request_count_per_target**(gauge) | The average number of requests received by each target that share the selected discovery name for the service.*Shown as request* | | **aws.ecs.schedulable_containers**(gauge) | The average number of containers that can be scheduled.*Shown as container* | | **aws.ecs.cluster.schedulable_containers**(gauge) | The average number of containers that can be scheduled in the cluster.*Shown as container* | | **aws.ecs.target_processed_bytes**(gauge) | The average number of bytes processed by the Service Connect proxies for the target tasks.*Shown as byte* | | **aws.ecs.service.target_processed_bytes**(gauge) | The average number of bytes processed by the Service Connect proxies for the target tasks for the service.*Shown as byte* | | **aws.ecs.target_response_time**(gauge) | The average latency of the application request processing between the Service Connect proxy in the target task and the target application.*Shown as millisecond* | | **aws.ecs.service.target_response_time**(gauge) | The average latency of the application request processing between the Service Connect proxy in the target task and the target application for the service.*Shown as millisecond* | | **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.desired**(gauge) | The number of tasks in the cluster that are in the desired state | | **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)