AWS ECS metrics
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