AWS ECS

This Guide Integrates:

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: