# Monitor Amazon ECS using CloudWatch You can monitor your Amazon ECS resources using Amazon CloudWatch, which collects and processes raw data from Amazon ECS into readable, near real-time metrics. These statistics are recorded for a period of two weeks so that you can access historical information and gain a better perspective on how your clusters or services are performing. Amazon ECS metric data is automatically sent to CloudWatch in 1-minute periods. For more information about CloudWatch, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). Amazon ECS provides free metrics for clusters and services. For an additional cost, you can turn on Amazon ECS CloudWatch Container Insights for your cluster for per-task metrics, including CPU, memory, and EBS filesystem utilization. For more information about Container Insights, see [Monitor Amazon ECS containers using Container Insights with enhanced observability](cloudwatch-container-insights.md). ## Considerations The following should be considered when using Amazon ECS CloudWatch metrics. + Any Amazon ECS service hosted on Fargate has CloudWatch CPU and memory utilization metrics automatically, so you don't need to take any manual steps. + For any Amazon ECS task or service hosted on Amazon EC2 instances, the Amazon EC2 instance requires version `1.4.0` or later (Linux) or `1.0.0` or later (Windows) of the container agent for CloudWatch metrics to be generated. However, we recommend using the latest container agent version. For information about checking your agent version and updating to the latest version, see [Updating the Amazon ECS container agent](ecs-agent-update.md). + The minimum Docker version for reliable CloudWatch metrics is Docker version `20.10.13` and newer. + Your Amazon EC2 instances also require the `ecs:StartTelemetrySession` permission on the IAM role that you launch your Amazon EC2 instances with. If you created your Amazon ECS container instance IAM role before CloudWatch metrics were available for Amazon ECS, you might need to add this permission. For information about the container instance IAM role and attaching the managed IAM policy for container instances, see [Amazon ECS container instance IAM role](instance_IAM_role.md). + You can disable CloudWatch metrics collection on your Amazon EC2 instances by setting `ECS_DISABLE_METRICS=true` in your Amazon ECS container agent configuration. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md). ## Recommended metrics Amazon ECS provides free CloudWatch metrics you can use to monitor your resources. The CPU and memory reservation and the CPU, memory, and EBS filesystem utilization across your cluster as a whole, and the CPU, memory, and EBS filesystem utilization on the services in your clusters can be measured using these metrics. For your GPU workloads, you can measure your GPU reservation across your cluster. The infrastructure your Amazon ECS tasks are hosted on in your clusters determines which metrics are available. For tasks hosted on Fargate infrastructure, Amazon ECS provides CPU, memory, and EBS filesystem utilization metrics to assist in the monitoring of your services. For tasks hosted on EC2 instances, Amazon ECS provides CPU, memory, and GPU reservation metrics and CPU and memory utilization metrics at the cluster and service level. You need to monitor the Amazon EC2 instances that make your underlying infrastructure separately. For more information about monitoring your Amazon EC2 instances, see [Monitoring Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/monitoring_ec2.html) in the *Amazon EC2 User Guide*. For information about the recommended alarms to use with Amazon ECS, see one of the following in the *Amazon CloudWatch Logs User Guide*: + [Amazon ECS](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ECS) + [Amazon ECS with Container Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#ECS-ContainerInsights) # Viewing Amazon ECS metrics After you have resources running in your cluster, you can view the metrics on the Amazon ECS and CloudWatch consoles. The Amazon ECS console provides a 24-hour maximum, minimum, and average view of your cluster and service metrics. The CloudWatch console provides a fine-grained and customizable display of your resources, as well as the number of running tasks in a service. ## Amazon ECS console Amazon ECS service CPU and memory utilization metrics are available on the Amazon ECS console. The view provided for service metrics shows the average, minimum, and maximum values for the previous 24-hour period, with data points available in 5-minute intervals. For more information, see [Amazon ECS service utilization metrics](service_utilization.md). 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. Select the cluster that you want to view metrics for. 1. Determine the metrics to view. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/viewing_cloudwatch_metrics.html) ## CloudWatch console For Fargate, Amazon ECS service metrics can also be viewed on the CloudWatch console. The console provides the most detailed view of Amazon ECS metrics, and you can tailor the views to suit your needs. You can view the service utilization and service RUNNING task count. For EC2 capacity providers, Amazon ECS cluster and service metrics can also be viewed on the CloudWatch console. The console provides the most detailed view of Amazon ECS metrics, and you can tailor the views to suit your needs. For information about how to view the metrics, see [View available metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) the *Amazon CloudWatch User Guide*. # Amazon ECS CloudWatch metrics You can use CloudWatch usage metrics to provide visibility into your accounts usage of resources. Use these metrics to visualize your current service usage on CloudWatch graphs and dashboards. Amazon ECS sends metrics to CloudWatch at one-minute intervals. These metrics are collected for resources that have tasks in the `RUNNING` state. If a cluster, service, or other resource has no running tasks, no metrics will be reported for that resource during that period. For example, if you have a cluster with one service but that service has no tasks in a `RUNNING` state, there will be no metrics sent to CloudWatch. Similarly, if you have two services and one of them has running tasks while the other doesn't, only the metrics for the service with running tasks would be sent. **** | Metric | Description | Valid Dimension | Useful Statistics | Unit | | --- | --- | --- | --- | --- | | CPUReservation | The percentage of CPU units that are reserved in the cluster or service. The CPU reservation ( filtered by `ClusterName`) is measured as the total CPU units that are reserved by Amazon ECS tasks on the cluster, divided by the total CPU units for all of the Amazon EC2 instances registered in the cluster. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect CPU reservation metrics. The metric is only supported for tasks hosted on an Amazon EC2 instance. | ClusterName. | Average, Minimum, Maximum | Percent | | CPUUtilization | The percentage of CPU units that is used by the cluster or service or Managed Daemon. The cluster-level CPU utilization ( filtered by `ClusterName`) is measured as the total CPU units that are in use by Amazon ECS tasks on the cluster, divided by the total CPU units for all of the Amazon EC2 instances registered in the cluster. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect CPU reservation metrics. The cluster-level metric is only supported for tasks hosted on an Amazon EC2 instance. The service-level CPU utilization ( filtered by `ClusterName`, `ServiceName`) is measured as the total CPU units in use by the tasks that belong to the service, divided by the total number of CPU units that are reserved for the tasks that belong to the service. The service-level metric is supported for tasks hosted on Amazon EC2 instances and Fargate. The daemon-level CPU utilization (filtered by `ClusterName`, `ServiceName`) is measured as the total CPU units in use by the tasks that belong to the Managed Daemon, divided by the total number of CPU units that are reserved for the tasks that belong to the Managed Daemon. | ClusterName, ServiceName | Average, Minimum, Maximum | Percent | | MemoryReservation | The percentage of memory that is reserved by running tasks in the cluster. Cluster memory reservation is measured as the total memory that is reserved by Amazon ECS tasks on the cluster, divided by the total amount of memory for all of the Amazon EC2 instances registered in the cluster. This metric can only be filtered by `ClusterName`. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect memory reservation metrics. The cluster level memory reservation metric is only supported for tasks hosted on an Amazon EC2 instance. When calculating memory utilization, if `MemoryReservation` is specified, it's used in the calculation instead of total memory. | ClusterName. | Average, Minimum, Maximum | Percent | | MemoryUtilization | The percentage of memory in use by the cluster or service or Managed Daemon. The cluster-level memory utilization (filtered by `ClusterName`) is measured as the total memory in use by Amazon ECS tasks on the cluster, divided by the total memory for all of the Amazon EC2 instances registered in the cluster. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect memory utilization metrics. The cluster-level metric is only supported for tasks hosted on an Amazon EC2 instance. The service-level memory utilization (filtered by `ClusterName`, `ServiceName`) is measured as the total memory in use by the tasks that belong to the service, divided by the total memory reserved for the tasks that belong to the service. The service-level metric is supported for tasks hosted on Amazon EC2 instances and Fargate. The daemon-level memory utilization (filtered by `ClusterName`, `ServiceName`) is measured as the total memory in use by the tasks that belong to the Managed Daemon, divided by the total memory reserved for the tasks that belong to the Managed Daemon. | ClusterName, ServiceName | Average, Minimum, Maximum | Percent | | EBSFilesystemUtilization | The percentage of the Amazon EBS filesystem that is used by tasks in a service. The service level EBS filesystem utilization metric (filtered by `ClusterName`, `ServiceName`) is measured as the total amount of the EBS filesystem in use by the tasks that belong to the service, divided by the total amount of EBS filesystem storage that is allocated for all tasks that belong to the service. The service level EBS filesystem utilization metric is only available for tasks hosted on Amazon EC2 instances (using container agent version `1.79.0` ) and Fargate (using platform version `1.4.0`) that have an EBS volume attached. For tasks hosted on Fargate, there is space on the disk that is only used by Fargate. There is no cost associated with the space Fargate uses, but you will see this additional storage using tools like `df`. | ClusterName, ServiceName | Average, Minimum, Maximum | Percent | | GPUReservation | The percentage of total available GPUs that are reserved by running tasks in the cluster. The cluster level GPU reservation metric is measured as the number of GPUs reserved by Amazon ECS tasks on the cluster, divided by the total number of GPUs that was available on all of the Amazon EC2 instances with GPUs registered in the cluster. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect GPU reservation metrics. | ClusterName | Average, Minimum, Maximum | Percent | | ActiveConnectionCount | The total number of concurrent connections active from clients to the Amazon ECS Service Connect proxies that run in tasks that share the selected `DiscoveryName`. This metric is only available if you have configured Amazon ECS Service Connect. Valid dimensions: `DiscoveryName` and `DiscoveryName, ServiceName, ClusterName`. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | NewConnectionCount | The total number of new connections established from clients to the Amazon ECS Service Connect proxies that run in tasks that share the selected `DiscoveryName`. This metric is only available if you have configured Amazon ECS Service Connect. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | ProcessedBytes | The total number of bytes of inbound traffic processed by the Service Connect proxies. This metric is only available if you have configured Amazon ECS Service Connect. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Bytes | | RequestCount | The number of inbound traffic requests processed by the Service Connect proxies. This metric is only available if you have configured Amazon ECS Service Connect. You also need to configure `appProtocol` in the port mapping in your task definition. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | GrpcRequestCount | The number of gRPC inbound traffic requests processed by the Service Connect proxies. This metric is only available if you have configured Amazon ECS Service Connect and the `appProtocol` is `GRPC` in the port mapping in the task definition. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | HTTPCode\$1Target\$12XX\$1Count | The number of HTTP response codes with numbers 200 to 299 generated by the applications in these tasks. These tasks are the targets. This metric only counts the responses sent to the Service Connect proxies by the applications in these tasks, not responses sent directly. This metric is only available if you have configured Amazon ECS Service Connect and the `appProtocol` is `HTTP` or `HTTP2` in the port mapping in the task definition. Valid dimensions:. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | HTTPCode\$1Target\$13XX\$1Count | The number of HTTP response codes with numbers 300 to 399 generated by the applications in these tasks. These tasks are the targets. This metric only counts the responses sent to the Service Connect proxies by the applications in these tasks, not responses sent directly. This metric is only available if you have configured Amazon ECS Service Connect and the `appProtocol` is `HTTP` or `HTTP2` in the port mapping in the task definition. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | HTTPCode\$1Target\$14XX\$1Count | The number of HTTP response codes with numbers 400 to 499 generated by the applications in these tasks. These tasks are the targets. This metric only counts the responses sent to the Service Connect proxies by the applications in these tasks, not responses sent directly. This metric is only available if you have configured Amazon ECS Service Connect and the `appProtocol` is `HTTP` or `HTTP2` in the port mapping in the task definition. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | HTTPCode\$1Target\$15XX\$1Count | The number of HTTP response codes with numbers 500 to 599 generated by the applications in these tasks. These tasks are the targets. This metric only counts the responses sent to the Service Connect proxies by the applications in these tasks, not responses sent directly. This metric is only available if you have configured Amazon ECS Service Connect and the `appProtocol` is `HTTP` or `HTTP2` in the port mapping in the task definition. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | RequestCountPerTarget | The average number of requests received by each target that share the selected `DiscoveryName`. This metric is only available if you have configured Amazon ECS Service Connect. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average | Count | | TargetProcessedBytes | The total number of bytes processed by the Service Connect proxies. This metric is only available if you have configured Amazon ECS Service Connect. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Bytes | | TargetResponseTime | The latency of the application request processing. The time elapsed, in milliseconds, after the request reached the Service Connect proxy in the target task until a response from the target application is received back to the proxy. This metric is only available if you have configured Amazon ECS Service Connect. | TargetDiscoveryName and TargetDiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum | Milliseconds | | ClientTLSNegotiationErrorCount | The total number of times the TLS connection failed. This metric is only used when TLS is enabled. This metric is only available if you have configured Amazon ECS Service Connect. | DiscoveryName and DiscoveryName, ServiceName, ClusterName | Average, Minimum, Maximum, Sum | Count | | TargetTLSNegotiationErrorCount | The total number of times the TLS connection failed due to missing client certificates, failed AWS Private CA verifications, or failed SAN verifications. This metric is only used when TLS is enabled. This metric is only available if you have configured Amazon ECS Service Connect. | ServiceName, ClusterName, TargetDiscoveryName and TargetDiscoveryName | Average, Minimum, Maximum, Sum | Count | ## Dimensions for Amazon ECS metrics Amazon ECS metrics use the `AWS/ECS` namespace and provide metrics for the following dimensions. Amazon ECS only sends metrics for resources that have tasks in the `RUNNING` state. For example, if you have a cluster with one service in it but that service has no tasks in a `RUNNING` state, there will be no metrics sent to CloudWatch. If you have two services and one of them has running tasks and the other doesn't, only the metrics for the service with running tasks would be sent. **** | Dimension | Definition | | --- | --- | | ClusterName | This dimension filters the data that you request for all resources in a specified cluster. All Amazon ECS metrics are filtered by `ClusterName`. | | ServiceName | This dimension filters the data that you request for all resources in a specified service or daemon within a specified cluster. For daemon metrics, the `ServiceName` dimension value has the prefix `daemon:` followed by the daemon name. For example, a daemon named `my-daemon` would have a `ServiceName` dimension value of `daemon:my-daemon`. | | DiscoveryName | This dimension filters the data that you request for traffic metrics to a specified Service Connect discovery name across all Amazon ECS clusters. Note that a specific port in a running container can have multiple discovery names. | | DiscoveryName, ServiceName, ClusterName | This dimension filters the data that you request for traffic metrics to a specified Service Connect discovery name across tasks that have this discovery name and that are created by this service in this cluster. Use this dimension to see the inbound traffic metrics for a specific service, if you have reused the same discovery name in multiple services in different namespaces. Note that a specific port in a running container can have multiple discovery names. | | TargetDiscoveryName | This dimension filters the data that you request for traffic metrics to a specified Service Connect discovery name across all Amazon ECS clusters. Different from `DiscoveryName`, these traffic metrics only measure inbound traffic to this `DiscoveryName` that come from other Amazon ECS tasks that have a Service Connect configuration in this namespace. This includes tasks made by services with either a client-only or client-server Service Connect configuration. Note that a specific port in a running container can have multiple discovery names. | | TargetDiscoveryName, ServiceName, ClusterName | This dimension filters the data that you request for traffic metrics to a specified Service Connect discovery name but only counts traffic from tasks created by this service in this cluster. Use this dimension to see the inbound traffic metrics that come from a specific client in another service. Different from `DiscoveryName, ServiceName, ClusterName`, these traffic metrics only measure inbound traffic to this `DiscoveryName` that come from other Amazon ECS tasks that have a Service Connect configuration in this namespace. This includes tasks made by services with either a client-only or client-server Service Connect configuration. Note that a specific port in a running container can have multiple discovery names. | # AWS Fargate usage metrics You can use CloudWatch usage metrics to provide visibility into your accounts usage of resources. Use these metrics to visualize your current service usage on CloudWatch graphs and dashboards. AWS Fargate usage metrics correspond to AWS service quotas. You can configure alarms that alert you when your usage approaches a service quota. For more information about Fargate service quotas, [Amazon ECS endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/ecs-service.html) in the *Amazon Web Services General Reference*.. AWS Fargate publishes the following metrics in the `AWS/Usage` namespace. | Metric | Description | | --- | --- | | `ResourceCount` | The total number of the specified resource running on your account. The resource is defined by the dimensions associated with the metric. | The following dimensions are used to refine the usage metrics that are published by AWS Fargate. | Dimension | Description | | --- | --- | | `Service` | The name of the AWS service containing the resource. For AWS Fargate usage metrics, the value for this dimension is `Fargate`. | | `Type` | The type of entity that is being reported. Currently, the only valid value for AWS Fargate usage metrics is `Resource`. | | `Resource` | The type of resource that is running. The type of resource that is running. Currently, the only valid value for AWS Fargate usage metrics is `vCPU` which returns information about the running instances. | | `Class` | The class of resource being tracked. The class of resource being tracked. For AWS Fargate usage metrics with vCPU as the value of the Resource dimension, the valid values are `Standard/OnDemand` and `Standard/Spot`. | You can use the Service Quotas console to visualize your usage on a graph and configure alarms that alert you when your AWS Fargate usage approaches a service quota. For information about how to create a CloudWatch alarm to notify you when you're close to a quota value threshold, see [Service Quotas and Amazon CloudWatch ](https://docs.aws.amazon.com/servicequotas/latest/userguide/configure-cloudwatch.html)alarms in the *Service Quotas User Guide* . # Amazon ECS cluster reservation metrics Cluster reservation metrics are measured as the percentage of CPU, memory, and GPUs that are reserved by all Amazon ECS tasks on a cluster when compared to the aggregate CPU, memory, and GPUs that were registered for each active container instance in the cluster. Only container instances in `ACTIVE` or `DRAINING` status will affect cluster reservation metrics. This metric is used only on clusters with tasks or services hosted on EC2 instances. It's not supported on clusters with tasks hosted on AWS Fargate. ``` (Total CPU units reserved by tasks in cluster) x 100 Cluster CPU reservation = -------------------------------------------------------------- (Total CPU units registered by container instances in cluster) ``` ``` (Total MiB of memory reserved by tasks in cluster x 100) Cluster memory reservation = ------------------------------------------------------------------ (Total MiB of memory registered by container instances in cluster) ``` ``` (Total GPUs reserved by tasks in cluster x 100) Cluster GPU reservation = ------------------------------------------------------------------ (Total GPUs registered by container instances in cluster) ``` When you run a task in a cluster, Amazon ECS parses its task definition and reserves the aggregate CPU units, MiB of memory, and GPUs that are specified in its container definitions. Each minute, Amazon ECS calculates the number of CPU units, MiB of memory, and GPUs that are currently reserved for each task that is running in the cluster. The total amount of CPU, memory, and GPUs reserved for all tasks running on the cluster is calculated, and those numbers are reported to CloudWatch as a percentage of the total registered resources for the cluster. If you specify a soft limit (`memoryReservation`) in the task definition, it's used to calculate the amount of reserved memory. Otherwise, the hard limit (`memory`) is used. The total MiB of memory reserved by tasks in a cluster also includes temporary file system (`tmpfs`) volume size and `sharedMemorySize` if defined in the task definition. For more information about hard and soft limits, shared memory size, and tmpfs volume size, see [Task Definition Parameters](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions). For example, a cluster has two active container instances registered: a `c4.4xlarge` instance and a `c4.large` instance. The `c4.4xlarge` instance registers into the cluster with 16,384 CPU units and 30,158 MiB of memory. The `c4.large` instance registers with 2,048 CPU units and 3,768 MiB of memory. The aggregate resources of this cluster are 18,432 CPU units and 33,926 MiB of memory. If a task definition reserves 1,024 CPU units and 2,048 MiB of memory, and ten tasks are started with this task definition on this cluster (and no other tasks are currently running), a total of 10,240 CPU units and 20,480 MiB of memory are reserved. This is reported to CloudWatch as 55% CPU reservation and 60% memory reservation for the cluster. The following illustration shows the total registered CPU units in a cluster and what their reservation and utilization means to existing tasks and new task placement. The lower (Reserved, used) and center (Reserved, not used) blocks represent the total CPU units that are reserved for the existing tasks that are running on the cluster, or the `CPUReservation` CloudWatch metric. The lower block represents the reserved CPU units that the running tasks are actually using on the cluster, or the `CPUUtilization` CloudWatch metric. The upper block represents CPU units that are not reserved by existing tasks; these CPU units are available for new task placement. Existing tasks can use these unreserved CPU units as well, if their need for CPU resources increases. For more information, see the [cpu](task_definition_parameters.md#ContainerDefinition-cpu) task definition parameter documentation. ![\[Cluster CPU reservation and utilization\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/images/telemetry.png) # Amazon ECS cluster utilization metrics The cluster utilization metrics are available for CPU, memory, and, when there is an EBS volume attached to your tasks, EBS filesystem utilization. These metrics are only available for clusters with tasks or services hosted on Amazon EC2 instances. They're not supported on clusters with tasks hosted on AWS Fargate. ## Amazon ECS cluster level CPU and memory utilization metrics The CPU and memory utilization is measured as the percentage of CPU and memory that is used by all tasks on a cluster when compared to the aggregate CPU and memory that was registered for each active Amazon EC2 instances registered to the cluster. Only Amazon EC2 instances in `ACTIVE` or `DRAINING` status will affect cluster utilization metrics. ``` (Total CPU units used by tasks in cluster) x 100 Cluster CPU utilization = -------------------------------------------------------------- (Total CPU units registered by container instances in cluster) ``` ``` (Total MiB of memory used by tasks in cluster x 100) Cluster memory utilization = ------------------------------------------------------------------ (Total MiB of memory registered by container instances in cluster) ``` Each minute, the Amazon ECS container agent on each Amazon EC2 instance calculates the number of CPU units and MiB of memory that is currently being used for each task that is running on that Amazon EC2 instance, and this information is reported back to Amazon ECS. The total amount of CPU and memory used for all tasks running on the cluster is calculated, and those numbers are reported to CloudWatch as a percentage of the total registered resources for the cluster. For example, a cluster has two active Amazon EC2 instances registered, a `c4.4xlarge` instance and a `c4.large` instance. The `c4.4xlarge` instance registers into the cluster with `16,384` CPU units and `30,158` MiB of memory. The `c4.large` instance registers with `2,048` CPU units and `3,768` MiB of memory. The aggregate resources of this cluster are `18,432` CPU units and `33,926` MiB of memory. If ten tasks are running on this cluster and each task consumes `1,024` CPU units and `2,048` MiB of memory, a total of `10,240` CPU units and `20,480` MiB of memory are used on the cluster. This is reported to CloudWatch as 55% CPU utilization and 60% memory utilization for the cluster. ## Amazon ECS cluster-level Amazon EBS filesystem utilization The cluster level EBS filesystem utilization metric is measured as the total amount of the EBS filesystem in use by the tasks running on the cluster, divided by the total amount of EBS filesystem storage that was allocated for all of the tasks in the cluster. ``` (Total GB of EBS filesystem used by tasks in cluster x 100) Cluster EBS filesystem utilization = --------------------------------------------------------------- (Total GB of EBS filesystem allocated to tasks in cluster) ``` # Amazon ECS service utilization metrics The service utilization metrics are available for CPU, memory, and, when there is an EBS volume attached to your tasks, EBS filesystem utilization. The service level metrics are supported for services with tasks hosted on both Amazon EC2 instances and Fargate. ## Service level CPU and memory utilization The CPU and memory utilization is measured as the percentage of CPU and memory that is used by the Amazon ECS tasks that belong to a service on a cluster when compared to the CPU and memory that is specified in the service's task definition. When viewing these metrics in CloudWatch, you can choose different statistics: + **Average**: The average utilization across all tasks in the service. This is calculated using the formula below. + **Minimum**: The utilization of the task with the lowest resource usage in the service. This represents the percentage of CPU or memory used by the least resource-intensive task compared to what was specified in the task definition. + **Maximum**: The utilization of the task with the highest resource usage in the service. This represents the percentage of CPU or memory used by the most resource-intensive task compared to what was specified in the task definition. The following formulas show how the Average statistic is calculated: ``` (Total CPU units used by tasks in service) x 100 Service CPU utilization = -------------------------------------------------------------- (Total CPU units specified in the task definition) x (Number of tasks in the service) ``` ``` (Total MiB of memory used by tasks in service x 100) Service memory utilization = ------------------------------------------------------------------ (Total MiB of memory specified in the task definition) x (Number of tasks in the service) ``` **Note** The formulas above apply only to the Average statistic. The Minimum and Maximum statistics represent the individual task with the lowest and highest resource utilization, respectively, rather than an aggregate calculation across all tasks. Amazon ECS collects metrics every 20 seconds. Each minute, the Amazon ECS container agent calculates the number of CPU units and MiB of memory that are currently being used for each running task owned by the service. This information is reported back to Amazon ECS. The total amount of CPU and memory used for all tasks owned by the service that are running on the cluster is calculated, and those numbers are reported to CloudWatch as a percentage of the total resources that are specified for the service in the service's task definition. The minimum and maximum values are the smallest and largest of the 20 second metrics. The average is the aggregate of the 3 values. If you specify a soft limit (`memoryReservation`), it's used to calculate the amount of reserved memory. Otherwise, the hard limit (`memory`) is used. For more information about hard and soft limits, see [Task size](task_definition_parameters.md#task_size). For example, the task definition for a service specifies a total of 512 CPU units and 1,024 MiB of memory (with the hard limit `memory` parameter) for all of its containers. The service has a desired count of 1 running task, the service is running on a cluster with 1 `c4.large` container instance (with 2,048 CPU units and 3,768 MiB of total memory), and there are no other tasks running on the cluster. Although the task specifies 512 CPU units, because it is the only running task on a container instance with 2,048 CPU units, it can use up to four times the specified amount (2,048 / 512). However, the specified memory of 1,024 MiB is a hard limit and it can't be exceeded, so in this case, service memory utilization can't exceed 100%. If the previous example used the soft limit `memoryReservation` instead of the hard limit `memory` parameter, the service's tasks could use more than the specified 1,024 MiB of memory as needed. In this case, the service's memory utilization could exceed 100%. If your application has a sudden spike in memory utilization for a short amount of time, you will not see the service memory utilization increasing because Amazon ECS collects multiple data points every minute, and then aggregates them to one data point that is sent to CloudWatch. If this task is performing CPU-intensive work during a period and using all 2,048 of the available CPU units and 512 MiB of memory, the service reports 400% CPU utilization and 50% memory utilization. If the task is idle and using 128 CPU units and 128 MiB of memory, the service reports 25% CPU utilization and 12.5% memory utilization. **Note** In this example, the CPU utilization will only go above 100% when the CPU units are defined at the container level. If you define CPU units at the task level, the utilization will not go above the defined task-level limit. ## Service level EBS filesystem utilization The service level EBS filesystem utilization is measured as the total amount of the EBS filesystem in use by the tasks that belong to the service, divided by the total amount of EBS filesystem storage that is allocated for all tasks that belong to the service. ## Service `RUNNING` task count You can use CloudWatch metrics to view the number of tasks in your services that are in the `RUNNING` state. For example, you can set a CloudWatch alarm for this metric to alert you if the number of running tasks in your service falls below a specified value. ### Service `RUNNING` task count in Amazon ECS CloudWatch Container Insights A "Number of Running Tasks" (`RunningTaskCount`) metric is available per cluster and per service when you use Amazon ECS CloudWatch Container Insights. You can use Container Insights for all new clusters created by opting in to the `containerInsights` account setting, on individual clusters by turning on the cluster settings during cluster creation, or on existing clusters by using the UpdateClusterSettings API. Metrics collected by CloudWatch Container Insights are charged as custom metrics. For more information about CloudWatch pricing, see [CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). To view this metric, see [Amazon ECS Container Insights Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-view-metrics.html) in the *Amazon CloudWatch User Guide*. # Amazon ECS service utilization metrics use cases Service utilization metrics use cases The following list provides information about when to use the Amazon ECS metrics. + **Resource utilization monitoring**: Use average statistics to monitor CPU and memory consumption patterns, establish performance baselines, and detect gradual performance degradation trends. + **Cost optimization**: Use average statistics to monitor resource usage, right-size containers, adjust reservations based on usage patterns, and implement scheduled scaling. + **Performance benchmarking**: Use average statistics to compare metrics between service revisions, establish performance KPIs, and validate optimization improvements. + **Resource floor detection**: Use average statistics to identify minimum resource needs during idle periods, set appropriate reservations, and detect abnormal drops. + **Anomaly detection**: Use minimum statistics to spot unusual resource utilization drops that indicate potential problems, such as initialization failures or unexpected idle periods. + **Scaling policy refinement**: Use minimum statistics to establish optimal scale-in thresholds based on minimum viable utilization to prevent aggressive scaling. + **Capacity planning**: Use maximum statistics to set appropriate task sizes and plan infrastructure with sufficient headroom for traffic spikes. + **Performance bottleneck identification**: Use maximum statistics to detect resource saturation points, identify bottlenecks, and determine when to increase task size. + **Scaling policy configuration**: Use maximum statistics to set optimal scale-out thresholds based on peak patterns and configure burst capacity. + **SLA compliance monitoring**: Use maximum statistics to track peak response times and error rates to ensure service performance meets defined SLAs. ## Related metrics information For information about Container Insights, see [Container Insights use cases](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ecs-container-insights-use-metrics-cases.html) in the* CloudWatch User Guide*.