---
title: Amazon ECS Tag Extraction
description: >-
  Configure automatic tag extraction from container labels and environment
  variables in Amazon ECS
breadcrumbs: Docs > Containers > Amazon ECS > Amazon ECS Tag Extraction
---

# Amazon ECS Tag Extraction

## Overview{% #overview %}

The Datadog Agent can create and assign tags to all metrics, traces, and logs emitted by a container based on its labels or environment variables.

## Out-of-the-box tags{% #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. The list of tags attached automatically depends on the agent [cardinality configuration](https://docs.datadoghq.com/getting_started/tagging/assigning_tags/?tab=containerizedenvironments#environment-variables).

| Tag                   | Cardinality  | Source  |
| --------------------- | ------------ | ------- |
| `container_name`      | High         | Docker  |
| `container_id`        | High         | Docker  |
| `docker_image`        | Low          | Docker  |
| `image_name`          | Low          | Docker  |
| `short_image`         | Low          | Docker  |
| `image_tag`           | Low          | Docker  |
| `aws_account`         | Low          | ECS API |
| `cluster_arn`         | Low          | ECS API |
| `service_arn`         | Low          | ECS API |
| `region`              | Low          | ECS API |
| `ecs_cluster_name`    | Low          | ECS API |
| `ecs_container_name`  | Low          | ECS API |
| `ecs_service_name`    | Low          | ECS API |
| `task_arn`            | Orchestrator | ECS API |
| `task_definition_arn` | Orchestrator | ECS API |
| `task_family`         | Low          | ECS API |
| `task_name`           | Low          | ECS API |
| `task_version`        | Low          | ECS API |

## Unified service tagging{% #unified-service-tagging %}

As a best practice in containerized environments, Datadog recommends using unified service tagging when assigning tags. Unified service tagging ties Datadog telemetry together through the use of three standard tags: `env`, `service`, and `version`. To learn how to configure your environment with unified tagging, see the [Amazon ECS unified service tagging documentation](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/?tab=ecs#containerized-environment).

## Resource tag collection{% #resource-tag-collection %}

If you do not have unified service tagging enabled, complete the following steps to collect ECS resource tags:

1. Verify your [Amazon ECS container instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html) are associated with an IAM role. This can be done when creating a new cluster with the ECS cluster creation wizard or in the launch configuration used by an autoscaling group.

1. Update the IAM role used by your [Amazon ECS container instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html) with: `ecs:ListTagsForResource`.

1. Update your [datadog-agent-ecs.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs.json) file ([datadog-agent-ecs1.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs1.json) if you are using an original Amazon Linux AMI) to enable resource tag collection by adding the following environment variable:

   ```json
       {
         "name": "DD_ECS_COLLECT_RESOURCE_TAGS_EC2",
         "value": "true"
       }
       
```

### Notes{% #notes %}

- Ensure the IAM role is associated with your [Amazon ECS container instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html) and not the task role of the Datadog agent container.
- ECS resource tags can be collected from EC2 instances, but not from AWS Fargate.
- This feature requires Datadog Agent v6.17+ or v7.17+.
- The Agent supports ECS tag collection from the `tasks`, `services`, and `container instances` ECS resources.
- If AWS tags are not appearing in Datadog, ensure that the tags are applied both to the instance and the corresponding AWS cloud resource.

## Further reading{% #further-reading %}

- [Getting started with tags](https://docs.datadoghq.com/getting_started/tagging/)
- [Using tags with Datadog](https://docs.datadoghq.com/getting_started/tagging/using_tags/)
- [Limit data collection to a subset of containers only](https://docs.datadoghq.com/agent/guide/autodiscovery-management/)