Datadog Agent on AWS ECS

Run the Datadog Agent as a sidecar container in your ECS task definitions to collect metrics, logs, events, and traces from containerized workloads. The agent forwards all telemetry to Kloudfuse over HTTPS.

Prerequisites

Create an IAM Role for ECS Tasks

Create an IAM role for the ECS tasks so the Datadog Agent can collect metrics, logs, and traces and interact with AWS services.

In the AWS Console, navigate to IAM and create a new Role with the following specifications:

Field Value

Trusted entity

ECS (Elastic Container Service)

Policy

Custom, or use AWS-managed policies:
AmazonEC2ContainerServiceforEC2Role (ECS task communication)
CloudWatchFullAccess (metrics)
AWSXRayDaemonWriteAccess (tracing)
CloudWatch Logs policy (log access)

ECS Task Definition

Add the Datadog Agent as a sidecar container in your ECS task definition. The following example task definition configures the agent to forward all signals to Kloudfuse:

{
  "containerDefinitions": [
    {
      "name": "datadog-agent",
      "image": "public.ecr.aws/datadog/agent:latest",
      "cpu": 100,
      "memory": 512,
      "essential": true,
      "environment": [
        { "name": "DD_API_KEY",                             "value": "kloudfuse" },
        { "name": "DD_URL",                                 "value": "https://<kloudfuse-hostname>/ingester" },
        { "name": "DD_LOGS_ENABLED",                        "value": "true" },
        { "name": "DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL",   "value": "true" },
        { "name": "DD_LOGS_CONFIG_FORCE_USE_HTTP",          "value": "true" },
        { "name": "DD_LOGS_CONFIG_LOGS_DD_URL",             "value": "<kloudfuse-hostname>:443" }
      ],
      "mountPoints": [
        { "sourceVolume": "docker_sock",      "containerPath": "/var/run/docker.sock" },
        { "sourceVolume": "cgroup",           "containerPath": "/host/sys/fs/cgroup" },
        { "sourceVolume": "proc",             "containerPath": "/host/proc" },
        { "sourceVolume": "pointdir",         "containerPath": "/opt/datadog-agent/run", "readOnly": false },
        { "sourceVolume": "containers_root",  "containerPath": "/var/lib/docker/containers", "readOnly": true }
      ],
      "linuxParameters": {
        "initProcessEnabled": true
      }
    }
  ],
  "family": "datadog-agent-task",
  "taskRoleArn": "arn:aws:iam::<aws-account-id>:role/<custom-ecs-iam-role>",
  "executionRoleArn": "arn:aws:iam::<aws-account-id>:role/<custom-ecs-iam-role>",
  "compatibilities": ["EXTERNAL", "EC2"]
}
json

Collect Metrics

The Datadog Agent automatically collects ECS-specific metrics — CPU, memory, disk, network, and ECS task-level utilization — with no additional configuration once the sidecar is running.

Collect Logs

To collect logs from all ECS task containers, set DD_LOGS_ENABLED=true and DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL=true in the agent container environment (included in the task definition above).

The agent uses the Docker log driver to collect logs from all containers in the task:

{
  "name": "DD_LOGS_ENABLED",
  "value": "true"
}
json

Collect Events

The ECS Agent collects container lifecycle events (start, stop, restart) with minimal configuration. Add tracing libraries to your application containers to capture application-level events and send them to the Datadog Agent sidecar.

Collect Traces

To enable APM tracing, set DD_APM_ENABLED=true in the agent container environment:

{
  "name": "DD_APM_ENABLED",
  "value": "true"
}
json

On ECS Fargate, the Datadog Agent automatically detects and enables APM for applications with tracing libraries installed (Python, Node.js, Java, Go, etc.).

Add the appropriate tracing library to your application container and configure it to send traces to the agent sidecar:

{
  "name": "DD_AGENT_HOST",
  "value": "localhost"
},
{
  "name": "DD_TRACE_ENABLED",
  "value": "true"
}
json

External References