Overview

Get metrics from all your containers running in ECS Fargate:

• CPU/Memory usage & limit metrics
• Monitor your applications running on Fargate using Datadog integrations or custom metrics.

The Datadog Agent retrieves metrics for the task definition’s containers with the ECS task metadata endpoint. According to the ECS Documentation on that endpoint:

• This endpoint returns Docker stats JSON for all of the containers associated with the task. For more information about each of the returned stats, see ContainerStats in the Docker API documentation.

The Task Metadata endpoint is only available from within the task definition itself, which is why the Datadog Agent needs to be run as an additional container within each task definition to be monitored.

The only configuration required to enable this metrics collection is to set an environment variable ECS_FARGATE to "true" in the task definition.

Note: Network Performance Monitoring (NPM) is not supported for ECS Fargate.

Setup

The following steps cover setup of the Datadog Container Agent within AWS ECS Fargate. Note: Datadog Agent version 6.1.1 or higher is needed to take full advantage of the Fargate integration.

Tasks that do not have the Datadog Agent still report metrics with Cloudwatch, however the Agent is needed for Autodiscovery, detailed container metrics, tracing, and more. Additionally, Cloudwatch metrics are less granular, and have more latency in reporting than metrics shipped directly through the Datadog Agent.

Installation

To monitor your ECS Fargate tasks with Datadog, run the Agent as a container in same task definition as your application container. To collect metrics with Datadog, each task definition should include a Datadog Agent container in addition to the application containers. Follow these setup steps:

1. Create an ECS Fargate task
2. Create or Modify your IAM Policy
3. Run the task as a replica service

Create an ECS Fargate task

The primary unit of work in Fargate is the task, which is configured in the task definition. A task definition is comparable to a pod in Kubernetes. A task definition must contain one or more containers. In order to run the Datadog Agent, create your task definition to run your application container(s), as well as the Datadog Agent container.

The instructions below show you how to configure the task using the Amazon Web Console, AWS CLI tools, or AWS CloudFormation.

aws ecs register-task-definition --cli-input-json file://<PATH_TO_FILE>/datadog-agent-ecs-fargate.json

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
        - FARGATE
      Cpu: 256
      Memory: 512
      ContainerDefinitions:
        - Name: datadog-agent
          Image: 'public.ecr.aws/datadog/agent:latest'
          Environment:
            - Name: DD_API_KEY
              Value: <DATADOG_API_KEY>
            - Name: ECS_FARGATE
              Value: true

Run the task as a replica service

The only option in ECS Fargate is to run the task as a Replica Service. The Datadog Agent runs in the same task definition as your application and integration containers.

aws ecs create-cluster --cluster-name "<CLUSTER_NAME>"

aws ecs run-task --cluster <CLUSTER_NAME> \
--network-configuration "awsvpcConfiguration={subnets=["<PRIVATE_SUBNET>"],securityGroups=["<SECURITY_GROUP>"]}" \
--task-definition arn:aws:ecs:us-east-1:<AWS_ACCOUNT_NUMBER>:task-definition/<TASK_NAME>:1 \
--region <AWS_REGION> --launch-type FARGATE --platform-version 1.4.0

Resources:
  ECSTaskDefinition:
    #(...)
  ECSService:
    Type: 'AWS::ECS::Service'
    Properties:
      Cluster: <CLUSTER_NAME>
      TaskDefinition:
        Ref: "ECSTaskDefinition"
      DesiredCount: 1
      #(...)

To provide your Datadog API key as a secret, see Using secrets.

Installation for AWS Batch

To monitor your AWS Batch jobs with Datadog, see AWS Batch with ECS Fargate and the Datadog Agent

Create or modify your IAM policy

Add the following permissions to your Datadog IAM policy to collect ECS Fargate metrics. For more information, see the ECS policies on the AWS website.

Using secrets

As an alternative to populating the DD_API_KEY environment variable with your API key in plaintext, you can instead reference the ARN of a plaintext secret stored in AWS Secrets Manager. Place the DD_API_KEY environment variable under the containerDefinitions.secrets section of the task or job definition file. Ensure that the task/job execution role has the necessary permission to fetch secrets from AWS Secrets Manager.

Metric collection

After the Datadog Agent is setup as described above, the ecs_fargate check collects metrics with autodiscovery enabled. Add Docker labels to your other containers in the same task to collect additional metrics.

Although the integration works on Linux and Windows, some metrics are OS dependent. All metrics exposed when running on Windows are also exposed on Linux, but there are some metrics that are only available on Linux. See Data Collected for the list of metrics provided by this integration. The list also specifies which metrics are Linux-only.

For details on collecting integration metrics, see Integration Setup for ECS Fargate.

DogStatsD

Metrics are collected with DogStatsD through UDP port 8125.

Other environment variables

For environment variables available with the Docker Agent container, see the Docker Agent page. Note: Some variables are not be available for Fargate.

For global tagging, it is recommended to use DD_DOCKER_LABELS_AS_TAGS. With this method, the Agent pulls in tags from your container labels. This requires you to add the appropriate labels to your other containers. Labels can be added directly in the task definition.

Format for the Agent container:

{
  "name": "DD_DOCKER_LABELS_AS_TAGS",
  "value": "{\"<LABEL_NAME_TO_COLLECT>\":\"<TAG_KEY_FOR_DATADOG>\"}"
}

Example for the Agent container:

{
  "name": "DD_DOCKER_LABELS_AS_TAGS",
  "value": "{\"com.docker.compose.service\":\"service_name\"}"
}

CloudFormation example (YAML):

      ContainerDefinitions:
        - #(...)
          Environment:
            - Name: DD_DOCKER_LABELS_AS_TAGS
              Value: "{\"com.docker.compose.service\":\"service_name\"}"

Note: You should not use DD_HOSTNAME since there is no concept of a host to the user in Fargate. Using this tag can cause your tasks to appear as APM Hosts in the Infrastructure list, potentially impacting your billing. Instead, DD_TAGS is traditionally used to assign host tags. As of Datadog Agent version 6.13.0, you can also use the DD_TAGS environment variable to set global tags on your integration metrics.

Crawler-based metrics

In addition to the metrics collected by the Datadog Agent, Datadog has a CloudWatch based ECS integration. This integration collects the Amazon ECS CloudWatch Metrics.

As noted there, Fargate tasks also report metrics in this way:

The metrics made available will depend on the launch type of the tasks and services in your clusters or batch jobs. If you are using the Fargate launch type for your services then CPU and memory utilization metrics are provided to assist in the monitoring of your services.

Since this method does not use the Datadog Agent, you need to configure the AWS integration by checking ECS on the integration tile. Then, Datadog pulls these CloudWatch metrics (namespaced aws.ecs.* in Datadog) on your behalf. See the Data Collected section of the documentation.

If these are the only metrics you need, you could rely on this integration for collection using CloudWatch metrics. Note: CloudWatch data is less granular (1-5 min depending on the type of monitoring you have enabled) and delayed in reporting to Datadog. This is because the data collection from CloudWatch must adhere to AWS API limits, instead of pushing it to Datadog with the Agent.

Datadog’s default CloudWatch crawler polls metrics once every 10 minutes. If you need a faster crawl schedule, contact Datadog support for availability. Note: There are cost increases involved on the AWS side as CloudWatch bills for API calls.

Log collection

You can monitor Fargate logs by using either:

• The AWS FireLens integration built on Datadog’s Fluent Bit output plugin to send logs directly to Datadog
• Using the awslogs log driver to store the logs in a CloudWatch Log Group, and then a Lambda function to route logs to Datadog

Datadog recommends using AWS FireLens because you can configure Fluent Bit directly in your Fargate tasks.

Note: Log collection with Fluent Bit and FireLens is not supported for AWS Batch on ECS Fargate.

Fluent Bit and FireLens

Configure the AWS FireLens integration built on Datadog’s Fluent Bit output plugin to connect your FireLens monitored log data to Datadog Logs. You can find a full sample task definition for this configuration here.

1. Add the Fluent Bit FireLens log router container in your existing Fargate task. For more information about enabling FireLens, see the dedicated AWS Firelens docs. For more information about Fargate container definitions, see the AWS docs on Container Definitions. AWS recommends that you use the regional Docker image. Here is an example snippet of a task definition where the Fluent Bit image is configured:

   {
     "essential": true,
     "image": "amazon/aws-for-fluent-bit:stable",
     "name": "log_router",
     "firelensConfiguration": {
       "type": "fluentbit",
       "options": { "enable-ecs-log-metadata": "true" }
     }
   }
   

   If your containers are publishing serialized JSON logs over stdout, you should use this extra FireLens configuration to get them correctly parsed within Datadog:

   {
     "essential": true,
     "image": "amazon/aws-for-fluent-bit:stable",
     "name": "log_router",
     "firelensConfiguration": {
       "type": "fluentbit",
       "options": {
         "enable-ecs-log-metadata": "true",
         "config-file-type": "file",
         "config-file-value": "/fluent-bit/configs/parse-json.conf"
       }
     }
   }
   

   This converts serialized JSON from the log: field into top-level fields. See the AWS sample Parsing container stdout logs that are serialized JSON for more details.

2. Next, in the same Fargate task define a log configuration for the desired containers to ship logs. This log configuration should have AWS FireLens as the log driver, and with data being output to Fluent Bit. Here is an example snippet of a task definition where the FireLens is the log driver, and it is outputting data to Fluent Bit:

{
  "logConfiguration": {
    "logDriver": "awsfirelens",
    "options": {
      "Name": "datadog",
      "apikey": "<DATADOG_API_KEY>",
      "Host": "http-intake.logs.datadoghq.com",
      "dd_service": "firelens-test",
      "dd_source": "redis",
      "dd_message_key": "log",
      "dd_tags": "project:fluentbit",
      "TLS": "on",
      "provider": "ecs"
    }
  }
}

{
  "logConfiguration": {
    "logDriver": "awsfirelens",
    "options": {
      "Name": "datadog",
      "apikey": "<DATADOG_API_KEY>",
      "Host": "http-intake.logs.us3.datadoghq.com",
      "dd_service": "firelens-test",
      "dd_source": "redis",
      "dd_message_key": "log",
      "dd_tags": "project:fluentbit",
      "TLS": "on",
      "provider": "ecs"
    }
  }
}

{
  "logConfiguration": {
    "logDriver": "awsfirelens",
    "options": {
      "Name": "datadog",
      "apikey": "<DATADOG_API_KEY>",
      "Host": "http-intake.logs.us5.datadoghq.com",
      "dd_service": "firelens-test",
      "dd_source": "redis",
      "dd_message_key": "log",
      "dd_tags": "project:fluentbit",
      "TLS": "on",
      "provider": "ecs"
    }
  }
}

{
  "logConfiguration": {
    "logDriver": "awsfirelens",
    "options": {
      "Name": "datadog",
      "apikey": "<DATADOG_API_KEY>",
      "Host": "http-intake.logs.datadoghq.eu",
      "dd_service": "firelens-test",
      "dd_source": "redis",
      "dd_message_key": "log",
      "dd_tags": "project:fluentbit",
      "TLS": "on",
      "provider": "ecs"
    }
  }
}

{
  "logConfiguration": {
    "logDriver": "awsfirelens",
    "options": {
      "Name": "datadog",
      "apikey": "<DATADOG_API_KEY>",
      "Host": "http-intake.logs.ddog-gov.datadoghq.com",
      "dd_service": "firelens-test",
      "dd_source": "redis",
      "dd_message_key": "log",
      "dd_tags": "project:fluentbit",
      "TLS": "on",
      "provider": "ecs"
    }
  }
}

The dd_service, dd_source, and dd_tags can be adjusted for your desired tags.

3. Whenever a Fargate task runs, Fluent Bit sends the container logs to Datadog with information about all of the containers managed by your Fargate tasks. You can see the raw logs on the Log Explorer page, build monitors for the logs, and use the Live Container view.

aws ecs register-task-definition --cli-input-json file://<PATH_TO_FILE>/datadog-agent-ecs-fargate.json

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              apikey: <DATADOG_API_KEY>
              Host: http-intake.logs.datadoghq.com
              dd_service: test-service
              dd_source: test-source
              TLS: 'on'
              provider: ecs
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              apikey: <DATADOG_API_KEY>
              Host: http-intake.logs.us3.datadoghq.com
              dd_service: test-service
              dd_source: test-source
              TLS: 'on'
              provider: ecs
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              apikey: <DATADOG_API_KEY>
              Host: http-intake.logs.us5.datadoghq.com
              dd_service: test-service
              dd_source: test-source
              TLS: 'on'
              provider: ecs
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              apikey: <DATADOG_API_KEY>
              Host: http-intake.logs.datadoghq.eu
              dd_service: test-service
              dd_source: test-source
              TLS: 'on'
              provider: ecs
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Resources:
  ECSTaskDefinition:
    Type: 'AWS::ECS::TaskDefinition'
    Properties:
      NetworkMode: awsvpc
      RequiresCompatibilities:
          - FARGATE
      Cpu: 256
      Memory: 1GB
      ContainerDefinitions:
        - Name: tomcat-test
          Image: 'tomcat:jdk8-adoptopenjdk-openj9'
          LogConfiguration:
            LogDriver: awsfirelens
            Options:
              Name: datadog
              apikey: <DATADOG_API_KEY>
              Host: http-intake.logs.ddog-gov.datadoghq.com
              dd_service: test-service
              dd_source: test-source
              TLS: 'on'
              provider: ecs
          MemoryReservation: 500
        - Name: log_router
          Image: 'amazon/aws-for-fluent-bit:stable'
          Essential: true
          FirelensConfiguration:
            Type: fluentbit
            Options:
              enable-ecs-log-metadata: true
          MemoryReservation: 50

Note: Use a TaskDefinition secret to avoid exposing the apikey in plain text.

AWS log driver

Monitor Fargate logs by using the awslogs log driver and a Lambda function to route logs to Datadog.

1. Define the log driver as awslogs in the application container in the task or job you want to collect logs from. Consult the AWS Fargate developer guide for instructions.

2. This configures your Fargate tasks or jobs to send log information to Amazon CloudWatch Logs. The following shows a snippet of a task/job definition where the awslogs log driver is configured:

   {
     "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-group": "/ecs/fargate-task|job-definition",
         "awslogs-region": "us-east-1",
         "awslogs-stream-prefix": "ecs"
       }
     }
   }
   

   For more information about using the awslogs log driver in your task or job definitions to send container logs to CloudWatch Logs, see Using the awslogs Log Driver. This driver collects logs generated by the container and sends them to CloudWatch directly.

3. Finally, use the Datadog Lambda Log Forwarder function to collect logs from CloudWatch and send them to Datadog.

Trace collection

2. Instrument your application based on your setup:

   Note: With Fargate APM applications, do not set DD_AGENT_HOST - the default of localhost works.

   Language
   Java
   Python
   Ruby
   Go
   Node.js
   PHP
   C++
   .NET Core
   .NET Framework

   See more general information about Sending Traces to Datadog.

3. Ensure your application is running in the same task or job definition as the Datadog Agent container.

Process collection

You can monitor processes in ECS Fargate in Datadog by using the Live Processes page. To enable process collection, add the PidMode parameter in the Task Definition and set it to task as follows:

"pidMode": "task"

To filter processes by ECS, use the AWS Fargate Containers facet or enter fargate:ecs in the search query on the Live Processes page.

Out-of-the-box tags

The Agent can autodiscover and attach tags to all data emitted by the entire task or an individual container within this task or job. The list of tags automatically attached depends on the Agent’s cardinality configuration.

Data Collected

Metrics

Events

The ECS Fargate check does not include any events.

Service Checks

fargate_check
Returns CRITICAL if the Agent is unable to connect to Fargate, otherwise returns OK.
Statuses: ok, critical

Troubleshooting

Need help? Contact Datadog support.

Further Reading

• Blog post: Monitor AWS Fargate applications with Datadog
• FAQ: Integration Setup for ECS Fargate
• Blog post: Monitor your Fargate container logs with FireLens and Datadog
• Blog post: Key metrics for monitoring AWS Fargate
• Blog post: How to collect metrics and logs from AWS Fargate workloads
• Blog post: AWS Fargate monitoring with Datadog
• Blog post: Graviton2-powered AWS Fargate deployments
• Blog post: Monitor AWS Fargate for Windows containerized apps
• Blog post: Monitor processes running on AWS Fargate with Datadog
• Blog post: Monitor AWS Batch on Fargate with Datadog