Overview

The Datadog Agent and Datadog Amazon ECS integration can retrieve ECS resources for the ECS Explorer. This feature enables you to monitor the status of EC2 and Fargate tasks, services, and other ECS components across all of your AWS accounts. You can view resource specifications for tasks within a service and correlate them with related logs, metrics, profiling, and more.

Prerequisites

• AWS resource collection: Required for collecting ECS resources.
• ECS on EC2 integration: Required for monitoring clusters using the EC2 launch type.
• ECS on Fargate integration: Required for monitoring clusters using the Fargate launch type.
• Datadog Agent version >= 7.58.0: Recommended for a shorter refresh rate on the ECS Explorer page.

Setup

Ensure you have enabled AWS resource collection, the ECS on EC2 integration, and the ECS on Fargate integration.

Note: The collection interval for these integrations is approximately 24 hours. To achieve a shorter collection interval of 15 seconds, it is recommended to install the Datadog Agent in your ECS cluster.

{
  "containerDefinitions": [
    {
      "name": "datadog-agent",
      "environment": [
        {
          "name": "DD_ECS_TASK_COLLECTION_ENABLED",
          "value": "true"
        }
        # (...)
      ]
      # (...)
    }
  ],
# (...)
}

ecs_task_collection_enabled: true

Usage

Views

Use the Select Resources dropdown menu in the top left corner of the page to switch between Tasks, Services, Clusters, and other ECS resources.

Each view includes a data table for organizing information by fields such as status, name, and AWS tags, along with a detailed Cluster Map to provide an overview of your tasks and ECS clusters.

Refer to Query filter details for information on filtering these views.

Group by functionality and facets

Group tasks by tags for an aggregated view that helps you find information more efficiently. You can group tasks using the Group by bar located at the top right of the page or by clicking on a specific tag and finding the group by function in the context menu, as illustrated below.

Additionally, use facets on the left side of the page to filter or group resources according to your interests, such as tasks with Fargate launch type.

Cluster map

The cluster map provides a comprehensive view of your tasks and ECS clusters, allowing you to see all resources on one screen with customizable groups and filters. You can also select which metrics to color the nodes.

To examine resources from the cluster map, click on any circle or group to display a detailed panel.

Information panel

Click on any row in the table or any object in the Cluster Map to display detailed information about a specific resource in a side panel.

The Task Definition tab in the side panel shows the complete task definition.

For task definitions, it also provides a history of seven days, allowing you to view all task definition revisions used by running tasks over the past week and compare changes between them.

Other tabs provide additional information for troubleshooting the selected resource:

• Related Resources: View all related resources in a tree structure.
• Logs: Access logs from your container or resource. Click on any log entry to view the full log details in the Log Explorer.
• Metrics: View live metrics for your container or resource. You can maximize any graph for full-screen viewing, share a snapshot, or export it from this tab.
• APM: Access traces from your container or resource, including details such as date, service, duration, method, and status code.
• Processes: See all processes running in the resource’s containers.
• Network: View network performance metrics for a container or resource, including source and destination, sent and received volume, and throughput. Use the Destination field to filter by tags like DNS or ip_type, or use the Group by filter to group network data by tags, such as task_name or service.
• Monitors: View monitors that are tagged, scoped, or grouped for this resource.

Query filter details

You can refine displayed resources by entering a query in the Filter by search bar at the top left of the page. The query filtering operates similarly to the filtering in the Kubernetes Explorer.

AWS tags

In the ECS Explorer, you can use tag# to search across both Datadog tags and AWS tags.

Extracted tags

In addition to the tags you have configured in your Datadog Agent, Datadog generates additional tags based on resource attributes, which can assist in your searching and grouping needs. These tags are conditionally added to resources when relevant.

All resources

All resources include the following tags:

• aws_account: AWS account ID
• region: AWS account region
• <resource_name>_arn: Resource ARN tags, such as task_arn, task_definition_arn, service_arn, and more.
• ecs_<resource_name>: Resource name tags, such as ecs_task, ecs_task_definition, ecs_service, and more.

Relationships

Related Resources are tagged in relation to one another. Some examples include:

• A task belonging to the “XYZ” service, with an ARN of XYZ-ARN, can have tags ecs_service:xyz and service_arn:xyz-arn.
• A service that is part of the “XYZ” cluster, identified by the ARN XYZ-ARN, can have tags ecs_cluster:xyz and cluster_arn:xyz-arn.

Tip: Use the filter query autocomplete feature to explore available related resource tags. Type ecs_ to see suggested results.

Resource specific tags

Some resources have specific tags. The following tags are available in addition to the shared tags mentioned above.

Notes and known issues

• Installing the Datadog Agent in your cluster affects how often the ECS Explorer refreshes: