> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Awsecscontainermetrics

> OpenTelemetry receiver for Awsecscontainermetrics

# Awsecscontainermetrics Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@Aneurysm9](https://github.com/Aneurysm9)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/awsecscontainermetricsreceiver)

## Supported Telemetry

![Metrics](https://img.shields.io/badge/metrics-beta-green)

## Overview

## Overview

AWS ECS Container Metrics Receiver (`awsecscontainermetrics`) reads task metadata and [docker stats](https://docs.docker.com/engine/api/v1.30/#operation/ContainerStats) from [Amazon ECS Task Metadata Endpoint](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint.html), and generates resource usage metrics (such as CPU, memory, network, and disk) from them. To get the full list of metrics, see the [Available Metrics](#available-metrics) section below.

This receiver works only for [ECS Task Metadata Endpoint V4](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint-v4.html). Amazon ECS tasks on Fargate that use platform version 1.4.0 or later and Amazon ECS tasks on Amazon EC2 that are running at least version 1.39.0 of the Amazon ECS container agent can utilize this receiver. For more information, see [Amazon ECS Container Agent Versions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-versions.html).

## Configuration

Example:

```yaml theme={null}
receivers:
  awsecscontainermetrics:
    collection_interval: 20s
```

#### collection\_interval:

This receiver collects task metadata and container stats at a fixed interval and emits metrics to the next consumer of OpenTelemetry pipeline. `collection_interval` will determine the frequency at which metrics are collected and emitted by this receiver.

default: `20s`

## Enabling the AWS ECS Container Metrics Receiver

To enable the awsecscontainermetrics receiver, add the name under receiver section in the OpenTelemetry config file. By default, the receiver scrapes the ECS task metadata endpoint every 20s and collects all metrics (For the full list of metrics, see [Available Metrics](#available-metrics)).

The following configuration collects AWS ECS resource usage metrics by using `awsecscontainermetrics` receiver and sends them to CloudWatch using `awsemf` exporter. Check out [SETUP](https://aws-otel.github.io/docs/setup/ecs) section for configuring AWS Distro for OpenTelemetry Collector in Amazon Elastic Container Service.

```yaml theme={null}
receivers:
  awsecscontainermetrics:
exporters:
  awsemf:
      namespace: 'ECS/ContainerMetrics/OpenTelemetry'
      log_group_name: '/ecs/containermetrics/opentelemetry'

service:
  pipelines:
      metrics:
          receivers: [awsecscontainermetrics]
          exporters: [awsemf]
```

## Set Metrics Collection Interval

Customers can configure `collection_interval` under `awsecscontainermetrics` receiver to scrape and gather metrics at a specific interval. The following example configuration will collect metrics every 40 seconds.

```yaml theme={null}
receivers:
  awsecscontainermetrics:
      collection_interval: 40s
exporters:
  awsemf:
      namespace: 'ECS/ContainerMetrics/OpenTelemetry'
      log_group_name: '/ecs/containermetrics/opentelemetry'

service:
  pipelines:
      metrics:
          receivers: [awsecscontainermetrics]
          exporters: [awsemf]
```

## Collect specific metrics and update metric names

The previous configurations collect all the metrics and sends them to Amazon CloudWatch using default names. Customers can use `filter` and `metricstransform` processors to send specific metrics and rename them respectively.

The following configuration example collects only the `ecs.task.memory.utilized` metric and renames it to `MemoryUtilized` before sending to CloudWatch.

```yaml theme={null}
receivers:
  awsecscontainermetrics:
exporters:
  awsemf:
      namespace: 'ECS/ContainerMetrics/OpenTelemetry'
      log_group_name: '/ecs/containermetrics/opentelemetry'
processors:
  filter:
    metrics:
      include:
        match_type: strict
        metric_names:
          - ecs.task.memory.utilized

  metricstransform:
    transforms:
      - include: ecs.task.memory.utilized
        action: update
        new_name: MemoryUtilized

service:
  pipelines:
      metrics:
          receivers: [awsecscontainermetrics]
          processors: [filter, metricstransform]
          exporters: [awsemf]
```

## Available Metrics

Following is the full list of metrics emitted by this receiver.

| Task Level Metrics                    | Container Level Metrics                | Unit         |
| ------------------------------------- | -------------------------------------- | ------------ |
| ecs.task.memory.usage                 | container.memory.usage                 | Bytes        |
| ecs.task.memory.usage.max             | container.memory.usage.max             | Bytes        |
| ecs.task.memory.usage.limit           | container.memory.usage.limit           | Bytes        |
| ecs.task.memory.reserved              | container.memory.reserved              | MiB          |
| ecs.task.memory.utilized              | container.memory.utilized              | MiB          |
| ecs.task.cpu.usage.total              | container.cpu.usage.total              | Nanoseconds  |
| ecs.task.cpu.usage.kernelmode         | container.cpu.usage.kernelmode         | Nanoseconds  |
| ecs.task.cpu.usage.usermode           | container.cpu.usage.usermode           | Nanoseconds  |
| ecs.task.cpu.usage.system             | container.cpu.usage.system             | Nanoseconds  |
| ecs.task.cpu.usage.vcpu               | container.cpu.usage.vcpu               | vCPU         |
| ecs.task.cpu.cores                    | container.cpu.cores                    | Count        |
| ecs.task.cpu.onlines                  | container.cpu.onlines                  | Count        |
| ecs.task.cpu.reserved                 | container.cpu.reserved                 | vCPU         |
| ecs.task.cpu.utilized                 | container.cpu.utilized                 | Percent      |
| ecs.task.network.rate.rx              | container.network.rate.rx              | Bytes/Second |
| ecs.task.network.rate.tx              | container.network.rate.tx              | Bytes/Second |
| ecs.task.network.io.usage.rx\_bytes   | container.network.io.usage.rx\_bytes   | Bytes        |
| ecs.task.network.io.usage.rx\_packets | container.network.io.usage.rx\_packets | Count        |
| ecs.task.network.io.usage.rx\_errors  | container.network.io.usage.rx\_errors  | Count        |
| ecs.task.network.io.usage.rx\_dropped | container.network.io.usage.rx\_dropped | Count        |
| ecs.task.network.io.usage.tx\_bytes   | container.network.io.usage.tx\_bytes   | Bytes        |
| ecs.task.network.io.usage.tx\_packets | container.network.io.usage.tx\_packets | Count        |
| ecs.task.network.io.usage.tx\_errors  | container.network.io.usage.tx\_errors  | Count        |
| ecs.task.network.io.usage.tx\_dropped | container.network.io.usage.tx\_dropped | Count        |
| ecs.task.storage.read\_bytes          | container.storage.read\_bytes          | Bytes        |
| ecs.task.storage.write\_bytes         | container.storage.write\_bytes         | Bytes        |
| ecs.task.ephemeral\_storage.utilized  |                                        | MiB          |
| ecs.task.ephemeral\_storage.reserved  |                                        | MiB          |

## Resource Attributes and Metrics Labels

Metrics emitted by this receiver comes with a set of resource attributes. These resource attributes can be converted to metrics labels using appropriate processors/exporters (See `Full Configuration Examples` section below). Finally, these metrics labels can be set as metrics dimensions while exporting to desired destinations. Check the following table to see available resource attributes for Task and Container level metrics. Container level metrics have three additional attributes than task level metrics.

| Resource Attributes for Task Level Metrics | Resource Attributes for Container Level Metrics |
| ------------------------------------------ | ----------------------------------------------- |
| aws.ecs.cluster.name                       | aws.ecs.cluster.name                            |
| aws.ecs.task.family                        | aws.ecs.task.family                             |
| aws.ecs.task.arn                           | aws.ecs.task.arn                                |
| aws.ecs.task.id                            | aws.ecs.task.id                                 |
| aws.ecs.task.revision                      | aws.ecs.task.revision                           |
| aws.ecs.service.name                       | aws.ecs.service.name                            |
| cloud.availability\_zone                   | cloud.availability\_zone                        |
| cloud.account.id                           | cloud.account.id                                |
| cloud.region                               | cloud.region                                    |
| aws.ecs.task.pull\_started\_at             | aws.ecs.container.started\_at                   |
| aws.ecs.task.pull\_stopped\_at             | aws.ecs.container.finished\_at                  |
| aws.ecs.task.known\_status                 | aws.ecs.container.know\_status                  |
| aws.ecs.launch\_type                       | aws.ecs.launch\_type                            |
|                                            | aws.ecs.container.created\_at                   |
|                                            | container.name                                  |
|                                            | container.id                                    |
|                                            | aws.ecs.docker.name                             |
|                                            | container.image.tag                             |
|                                            | aws.ecs.container.image.id                      |
|                                            | aws.ecs.container.exit\_code                    |

## Full Configuration Examples

This receiver emits 54 unique metrics. Customer may not want to send all of them to destinations. Following sections will show full configuration files for filtering and transforming existing metrics with different processors/exporters.

### 1. Full configuration for task level metrics

The following example shows a full configuration to get most useful task level metrics. It uses `awsecscontainermetrics` receiver to collect all the resource usage metrics from ECS task metadata endpoint. It applies `filter` processor to select only 8 task-level metrics and update metric names using `metricstransform` processor. It also renames the resource attributes using `resource` processor which will be used as metric dimensions in the Amazon CloudWatch `awsemf` exporter. Finally, it sends the metrics to CloudWatch using `awsemf` exporter under the `/aws/ecs/containerinsights/{ClusterName}/performance` namespace where the `{ClusterName}` placeholder will be replaced with actual cluster name. Check the [AWS EMF Exporter](https://aws-otel.github.io/docs/getting-started/cloudwatch-metrics) documentation to see and explore the metrics in Amazon CloudWatch.

**Note:** AWS OpenTelemetry Collector has a [default configuration](https://github.com/aws-observability/aws-otel-collector/blob/main/config/ecs/container-insights/otel-task-metrics-config.yaml) backed into it for Container Insights experience which is similar to this one. Follow our [setup](https://aws-otel.github.io/docs/setup/ecs) doc to check how to use that default config.

```yaml theme={null}
receivers:
  awsecscontainermetrics: # collect 54 metrics

processors:
  filter: # filter metrics
    metrics:
      include:
        match_type: strict
        metric_names: # select only 8 task level metrics out of 52
          - ecs.task.memory.reserved
          - ecs.task.memory.utilized
          - ecs.task.cpu.reserved
          - ecs.task.cpu.utilized
          - ecs.task.network.rate.rx
          - ecs.task.network.rate.tx
          - ecs.task.storage.read_bytes
          - ecs.task.storage.write_bytes
  metricstransform: # update metric names
    transforms:
      - include: ecs.task.memory.utilized
        action: update
        new_name: MemoryUtilized
      - include: ecs.task.memory.reserved
        action: update
        new_name: MemoryReserved
      - include: ecs.task.cpu.utilized
        action: update
        new_name: CpuUtilized
      - include: ecs.task.cpu.reserved
        action: update
        new_name: CpuReserved
      - include: ecs.task.network.rate.rx
        action: update
        new_name: NetworkRxBytes
      - include: ecs.task.network.rate.tx
        action: update
        new_name: NetworkTxBytes
      - include: ecs.task.storage.read_bytes
        action: update
        new_name: StorageReadBytes
      - include: ecs.task.storage.write_bytes
        action: update
        new_name: StorageWriteBytes
  resource:
    attributes: # rename resource attributes which will be used as dimensions
      - key: ClusterName
        from_attribute: aws.ecs.cluster.name
        action: insert
      - key: aws.ecs.cluster.name
        action: delete
      - key: ServiceName
        from_attribute: aws.ecs.service.name
        action: insert
      - key: aws.ecs.service.name
        action: delete
      - key: TaskId
        from_attribute: aws.ecs.task.id
        action: insert
      - key: aws.ecs.task.id
        action: delete
      - key: TaskDefinitionFamily
        from_attribute: aws.ecs.task.family
        action: insert
      - key: aws.ecs.task.family
        action: delete
exporters:
  awsemf:
    namespace: ECS/ContainerInsights
    log_group_name: '/aws/ecs/containerinsights/{ClusterName}/performance'
    log_stream_name: '{TaskId}'  # TaskId placeholder will be replaced with actual value
    resource_to_telemetry_conversion:
      enabled: true
    dimension_rollup_option: NoDimensionRollup
    metric_declarations:
      dimensions: [ [ ClusterName ], [ ClusterName, TaskDefinitionFamily ] ]
      metric_name_selectors: [ . ]
service:
  pipelines:
    metrics:
      receivers: [awsecscontainermetrics ]
      processors: [filter, metricstransform, resource]
      exporters: [ awsemf ]
```

### 2. Full configuration for task- and container-level metrics

The following example shows a full configuration to get most useful task- and container-level metrics. It uses `awsecscontainermetrics` receiver to collect all the resource usage metrics from ECS task metadata endpoint. It applies `filter` processor to select only 8 task- and container-level metrics and update metric names using `metricstransform` processor. It also renames the resource attributes using `resource` processor which will be used as metric dimensions in the Amazon CloudWatch `awsemf` exporter. Finally, it sends the metrics to CloudWatch using `awsemf` exporter under the /`aws/ecs/containerinsights/{ClusterName}/performance` namespace where the `{ClusterName}` placeholder will be replaced with actual cluster name. Check the [AWS EMF Exporter](https://aws-otel.github.io/docs/getting-started/cloudwatch-metrics) documentation to see and explore the metrics in Amazon CloudWatch.

```yaml theme={null}
receivers:
    awsecscontainermetrics:

processors:
    filter:
        metrics:
            include:
                match_type: regexp
                metric_names:
                    - .*memory.reserved
                    - .*memory.utilized
                    - .*cpu.reserved
                    - .*cpu.utilized
                    - .*network.rate.rx
                    - .*network.rate.tx
                    - .*storage.read_bytes
                    - .*storage.write_bytes
    metricstransform:
        transforms:
            - include: ecs.task.memory.utilized
              action: update
              new_name: MemoryUtilized
            - include: ecs.task.memory.reserved
              action: update
              new_name: MemoryReserved
            - include: ecs.task.cpu.utilized
              action: update
              new_name: CpuUtilized
            - include: ecs.task.cpu.reserved
              action: update
              new_name: CpuReserved
            - include: ecs.task.network.rate.rx
              action: update
              new_name: NetworkRxBytes
            - include: ecs.task.network.rate.tx
              action: update
              new_name: NetworkTxBytes
            - include: ecs.task.storage.read_bytes
              action: update
              new_name: StorageReadBytes
            - include: ecs.task.storage.write_bytes
              action: update
              new_name: StorageWriteBytes
    resource:
        attributes:
            - key: ClusterName
              from_attribute: aws.ecs.cluster.name
              action: insert
            - key: aws.ecs.cluster.name
              action: delete
            - key: ServiceName
              from_attribute: aws.ecs.service.name
              action: insert
            - key: aws.ecs.service.name
              action: delete
            - key: TaskId
              from_attribute: aws.ecs.task.id
              action: insert
            - key: aws.ecs.task.id
              action: delete
            - key: TaskDefinitionFamily
              from_attribute: aws.ecs.task.family
              action: insert
            - key: aws.ecs.task.family
              action: delete
            - key: ContainerName
              from_attribute: container.name
              action: insert
            - key: container.name
              action: delete                  
exporters:
    awsemf:
        namespace: ECS/ContainerInsights
        log_group_name:  '/aws/ecs/containerinsights/{ClusterName}/performance'
        log_stream_name: '{TaskId}'
        resource_to_telemetry_conversion:
            enabled: true
        dimension_rollup_option: NoDimensionRollup
        metric_declarations:
            - dimensions: [[ClusterName], [ClusterName, TaskDefinitionFamily]]
              metric_name_selectors: 
                - MemoryUtilized 
                - MemoryReserved 
                - CpuUtilized
                - CpuReserved
                - NetworkRxBytes
                - NetworkTxBytes
                - StorageReadBytes
                - StorageWriteBytes
            - dimensions: [[ClusterName], [ClusterName, TaskDefinitionFamily, ContainerName]]
              metric_name_selectors: [container.*]
     
service:
    pipelines:
        metrics:
            receivers: [awsecscontainermetrics]
            processors: [filter, metricstransform, resource]
            exporters: [awsemf]
```

## Reference

1. [Setup OpenTelemetry Collector on Amazon ECS](https://aws-otel.github.io/docs/setup/ecs)
2. [Getting Started with ECS Container Metrics Receiver in the OpenTelemetry Collector](https://aws-otel.github.io/docs/components/ecs-metrics-receiver)

## Configuration

### Example Configuration

```yaml theme={null}
awsecscontainermetrics:
awsecscontainermetrics/collection_interval_settings:
  collection_interval: 10s
```

***

*Last generated: 2026-07-06*