AWS ECS
This Guide Integrates:
✅ Logs | ✅ Metrics | ✖️ Traces |
Installing the OpenTelemetry ECS Sidecar
The ECS sidecar container runs an OpenTelemetry collector that collects ECS task and container metrics and logs via Firelens from the application container and is preconfigured to send them to HyperDX (opens in a new tab).
To use this sidecar container in an ECS task definition, you'll need to create a
new task definition with two containers: the application container and the
OpenTelemetry sidecar container. The application container should be configured
to use the awsfirelens
log driver to forward the logs to the sidecar.
Task definition example:
{
"family": "firelens-example-otel",
"containerDefinitions": [
{
"name": "YOUR_APPLICATION_HERE",
"image": "my_container_image",
"essential": true,
"logConfiguration": {
"logDriver": "awsfirelens"
}
},
{
"name": "otel-sidecar",
"image": "public.ecr.aws/hyperdx/aws-ecs-opentelemetry-sidecar:latest",
"essential": true,
"environment": [
{
"name": "HYPERDX_API_KEY",
"value": "YOUR_HYPERDX_API_KEY"
}
],
"firelensConfiguration": {
"type": "fluentbit"
}
}
],
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "512",
"memory": "1024"
}
View the examples
folder in the repo (opens in a new tab) for more task definition examples and configuration
options.
Configuration
You'll need to set the HYPERDX_API_KEY
environment variable in the sidecar
container to your HyperDX Ingestion API key. You can view API key in your
team settings page (opens in a new tab).
By default, the service.name
is populated by the ECS task definition family
name, but this can be overridden by setting the
OTEL_RESOURCE_ATTRIBUTES="service.name=my_service"
.
To disable the collection of ECS metrics, set the
OTEL_ECS_CONTAINER_METRICS_DISABLED
environment variable to true
.
To disable the collection of ECS logs, ensure that the awsfirelens
log driver
is not set on the application container.
To debug the generated configuration, set the DEBUG_GENERATED_OTEL_CONFIG
environment variable to true
.
Collected ECS Metrics
The OpenTelemetry collector in the sidecar container collects the following
metrics from the ECS task and container via the
awsecscontainermetrics
receiver (opens in a new tab)
at a 1 minute interval:
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 | Megabytes |
ecs.task.memory.utilized | container.memory.utilized | Megabytes |
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 |
![](https://static.scarf.sh/a.png?x-pxid=8167f508-ea32-4021-a0ac-42db3c691850)