---
title: AWS ECS metrics
slug: telemetry-pipeline/aws-ecs-metrics
docTags: 
createdAt: 2025-04-21T00:49:19.834Z
---

## AWS ECS Metrics Source

The AWS ECS Metrics source collects **container-level metrics** for tasks running on **Amazon ECS** and **AWS Fargate**. It retrieves runtime statistics directly from the ECS task metadata endpoint and emits them as metrics into the telemetry pipeline.

This source is designed for cloud-native workloads where container metrics are required without direct access to the Docker daemon or host-level instrumentation.

## Collection Model

The source periodically scrapes the **ECS task metadata endpoint** exposed to running containers.

Key aspects of the collection model:

- Pull-based metric collection 
- No persistent state between scrapes 
- Compatible with both ECS on EC2 and AWS Fargate 
- Requires no additional agents or host permissions 

Metrics are emitted in batches at each scrape interval.

## ECS Metadata Endpoint Discovery

### endpoint (optional, string)

Defines the base URI of the ECS task metadata endpoint.

If not explicitly set, the endpoint is **automatically discovered** based on the ECS metadata version available in the runtime environment.

Automatic discovery follows this order:

- Version 4 via ECS\_CONTAINER\_METADATA\_URI\_V4 
- Version 3 via ECS\_CONTAINER\_METADATA\_URI 
- Version 2 via the default link-local address 

This allows the same configuration to work across different ECS and Fargate environments.

## Metadata Endpoint Versioning

### version (optional, string)

Specifies which version of the ECS task metadata endpoint to use.

Supported versions:

- **v2** – Legacy endpoint 
- **v3** – Enhanced task metadata 
- **v4** – Latest endpoint with extended container statistics 

If not specified, the version is automatically selected based on available environment variables.

## Metric Namespacing

### namespace (optional, string)

Defines the namespace under which all emitted metrics are published.

When set:

- Metrics are grouped logically 
- Name collisions with other sources are avoided 
- Integration with monitoring backends is simplified 

If left empty, namespacing is disabled.

## Scrape Interval

### scrape\_interval\_secs (optional, uint)

Controls how frequently the source scrapes container metrics from the ECS metadata endpoint.

Shorter intervals:

- Provide higher metric resolution 
- Increase scrape overhead 

Longer intervals:

- Reduce overhead 
- Lower metric granularity 

The interval applies uniformly to all containers within the task.

## Metrics Scope

The source collects **container runtime metrics**, including but not limited to:

- CPU usage 
- Memory usage 
- Network I/O 
- Container lifecycle statistics 

Metrics are collected per container within each ECS task.

## Reliability and Delivery Semantics

- Metrics are collected with **at-least-once delivery** 
- Duplicate samples may occur under retry conditions 
- No acknowledgement tracking is performed at the source level 
- Downstream systems should tolerate duplicate datapoints 

## Security Model

- Uses ECS-provided metadata endpoints 
- No credentials are required 
- No external network access is needed 
- Access is restricted to the task’s own metadata 

This aligns with AWS’s security model for containerized workloads.

## Common Use Cases

- Observability for ECS and Fargate workloads 
- Container-level performance monitoring 
- Cost and capacity analysis 
- Integration with Prometheus-style metric backends 
- Sidecar-based telemetry collection without host access