--- title: Amazon ECS Managed Instances description: >- Install and configure the Datadog Agent on Amazon Elastic Container Service Managed Instances breadcrumbs: Docs > Containers > Amazon ECS > Amazon ECS Managed Instances --- # Amazon ECS Managed Instances Datadog Container Monitoring enables visibility into applications running on [Amazon ECS Managed Instances](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ManagedInstances.html). ### How it works{% #how-it-works %} To monitor your ECS Managed Instances with Datadog, run the Datadog Agent as a **daemon task**. A daemon task allows ECS to automatically deploy to each host as managed instances join your cluster. This enables full visibility into all containers on the instance without requiring changes to your application task definitions. ## Setup{% #setup %} {% alert level="info" %} This setup requires Datadog Agent 7.77.0+. {% /alert %} The following instructions assume that you have configured an ECS Managed Instances cluster. See the [Amazon ECS Managed Instances documentation for creating a cluster](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-managed-instances.html). 1. Create a daemon task definition file 1. Register the daemon task definition 1. Create the daemon ### Create a daemon task definition file{% #create-a-daemon-task-definition-file %} This ECS daemon task definition launches the Datadog Agent container with the necessary configurations. 1. Download [datadog-agent-ecs-managed-instances-daemon.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs-managed-instances-daemon.json). This file provides minimal configuration for core infrastructure monitoring. For more sample task definition files with various features enabled, see the Set up additional Agent features section on this page. 1. Modify the task definition file: - Set the `DD_API_KEY` environment variable by replacing `` with the [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) for your account. Alternatively, you can also [supply the ARN of a secret stored in AWS Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-tutorial.html). - Set the `DD_SITE` environment variable to your [Datadog site](https://docs.datadoghq.com/getting_started/site/). Your site is: 1. (Optional) To add an Agent health check, add the following to your ECS task definition: ```json "healthCheck": { "retries": 3, "command": ["CMD-SHELL","agent health"], "timeout": 5, "interval": 30, "startPeriod": 15 } ``` ### Register the daemon task definition{% #register-the-daemon-task-definition %} {% tab title="AWS Console" %} 1. Log in to your [AWS Console](https://aws.amazon.com/console) and navigate to the Elastic Container Service section. 1. Select **Task Definitions** in the navigation pane. On the **Create new task definition** menu, select **Create new task definition with JSON**. 1. In the JSON editor box, paste the contents of your daemon task definition file. 1. Select **Create**. {% /tab %} {% tab title="AWS CLI" %} Use the [AWS CLI](https://aws.amazon.com/cli) to execute the following command: ```bash aws ecs register-daemon-task-definition --cli-input-json file:// ``` {% /tab %} ### Create the daemon{% #create-the-daemon %} The daemon is attached to a capacity provider and deploys automatically to each managed instance in that capacity provider. {% tab title="AWS Console" %} 1. Log in to your [AWS Web Console](https://aws.amazon.com/console) and navigate to the Elastic Container Service section. 1. Choose the cluster to run the Datadog Agent on. 1. On the **Daemons** tab, click **Create**. 1. For **Daemon Task Definition**, select the task definition created in the previous steps. 1. Enter a **Daemon name**. 1. For **Capacity Provider**, choose the capacity provider tied to the cluster. 1. Fill in the rest of the optional fields based on your preference. 1. Click **Create**. {% /tab %} {% tab title="AWS CLI" %} Use the [AWS CLI](https://aws.amazon.com/cli) to execute the following command: ```bash aws ecs create-daemon \ --daemon-name \ --daemon-task-definition-arn \ --capacity-provider-arns ``` {% /tab %} ## Set up additional Datadog Agent features{% #set-up-additional-datadog-agent-features %} ### Metrics collection{% #metrics-collection %} To enable integrations, add Docker label annotations to your application containers in the ECS task definition. #### Add an integration{% #add-an-integration %} ##### Update the task definition{% #update-the-task-definition %} {% tab title="AWS Console" %} 1. Log in to your [AWS Web Console](https://aws.amazon.com/console) and navigate to the ECS section. 1. Choose the cluster the Datadog Agent is running on. 1. Click the **Tasks** tab, then click the **Task definition** name containing the Datadog Agent container. 1. Click the **Create new revision** button. 1. Select the application container you want to monitor and click **Edit**. 1. Under **Docker labels**, add the following: | Key | Value | | ----------------------------- | ----------------------------------------------- | | com.datadoghq.ad.instances | `[{"host": "%%host%%", "port": }]` | | com.datadoghq.ad.check_names | `[""]` | | com.datadoghq.ad.init_configs | `[{}]` | Click the **Update** button, then click the **Create** button. {% /tab %} {% tab title="AWS CLI" %} Add `dockerLabels` to your application container in the task definition JSON, then register the new revision using the [AWS CLI](https://aws.amazon.com/cli): ```json { "containerDefinitions": [ { "name": "", "dockerLabels": { "com.datadoghq.ad.instances": "[{\"host\": \"%%host%%\", \"port\": }]", "com.datadoghq.ad.check_names": "[\"\"]", "com.datadoghq.ad.init_configs": "[{}]" } } ] } ``` ```bash aws ecs register-task-definition --cli-input-json file:// ``` {% /tab %} ##### Update the service{% #update-the-service %} {% tab title="AWS Console" %} 1. Within the cluster, click the **Services** tab, then click the **Service Name**. 1. Click the **Update** button. 1. For **Task Definition**, choose the latest **Revision** from the dropdown menu. 1. Click the **Update Service** button. {% /tab %} {% tab title="AWS CLI" %} Use the [AWS CLI](https://aws.amazon.com/cli) to update the service with the new task definition revision: ```bash aws ecs update-service --cluster \ --service \ --task-definition ``` {% /tab %} #### Examples{% #examples %} {% tab title="AWS Console" %} Use the following table to enter the Docker labels with the [AWS Web Console](https://aws.amazon.com/console) for a Redis container: | Key | Value | | ----------------------------- | -------------------------------------- | | com.datadoghq.ad.instances | `[{"host": "%%host%%", "port": 6379}]` | | com.datadoghq.ad.check_names | `["redisdb"]` | | com.datadoghq.ad.init_configs | `[{}]` | {% /tab %} {% tab title="AWS CLI" %} Use the following JSON under `containerDefinitions` to configure a Redis container with Docker labels through the [AWS CLI](https://aws.amazon.com/cli): ```json { "name": "redis", "image": "redis:latest", "essential": true, "dockerLabels": { "com.datadoghq.ad.instances": "[{\"host\": \"%%host%%\", \"port\": 6379}]", "com.datadoghq.ad.check_names": "[\"redisdb\"]", "com.datadoghq.ad.init_configs": "[{}]" } } ``` {% /tab %} #### Alternative: Mount a configuration file{% #alternative-mount-a-configuration-file %} To provide a custom integration configuration, you can also mount a configuration file directly onto the Datadog Agent container. Create the following file structure: ``` |- datadog |- Dockerfile |- conf.d |-redis.yaml ``` The `redis.yaml` file contains the configurations for the [Redis](https://docs.datadoghq.com/integrations/redis/?tab=ecs) integration. In the `redis.yaml` file: ```yaml ad_identifiers: - redis init_config: instances: - host: %%host%% port: 6379 ``` The `Dockerfile` is used to build a Datadog Agent image and include the `redis.yaml` file at the correct location: In the `Dockerfile` file: ```Dockerfile FROM public.ecr.aws/datadog/agent:latest COPY conf.d/ /etc/datadog-agent/conf.d/ ``` After the image is built and pushed to an image registry, reference the custom image in the ECS task definition: ``` { "containerDefinitions": [ { "image": "//:", "name": "datadog-agent", ... } ], ... } ``` ### Trace collection (APM){% #trace-collection-apm %} Instrument your application based on your setup: | Language | | ----------------------------------------------------------------------------------------------------------------------------------------- | | [Java](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/java?tab=containers#automatic-instrumentation) | | [Python](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/python?tab=containers#instrument-your-application) | | [Ruby](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/ruby#instrument-your-application) | | [Go](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/go/?tab=containers#activate-go-integrations-to-create-spans) | | [Node.js](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/nodejs?tab=containers#instrument-your-application) | | [PHP](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/php?tab=containers#automatic-instrumentation) | | [C++](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/cpp?tab=containers#instrument-your-application) | | [.NET Core](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/dotnet-core?tab=containers#custom-instrumentation) | | [.NET Framework](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/dotnet-framework?tab=containers#custom-instrumentation) | #### UDS{% #uds %} The recommended method is Unix Domain Socket (UDS). The daemon Agent exposes its socket on the host filesystem, which application tasks access by mounting the same host path. Consult the sample [datadog-agent-ecs-managed-instances-daemon-apm.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs-managed-instances-daemon-apm.json) file for a complete daemon task definition. **Update the daemon task definition** to add the `dd-sockets` host volume and mount: ```json { "containerDefinitions": [ { "name": "datadog-agent", ... "mountPoints": [ ... { "containerPath": "/var/run/datadog", "readOnly": false, "sourceVolume": "dd-sockets" } ] } ], "volumes": [ ... { "host": { "sourcePath": "/var/run/datadog" }, "name": "dd-sockets" } ] } ``` The Agent maintains socket files at `/var/run/datadog/apm.socket` and `/var/run/datadog/dsd.socket`. **Update each application task definition** to mount the same host path and configure the tracer: ```json { "containerDefinitions": [ { "name": "", ... "environment": [ { "name": "DD_TRACE_AGENT_URL", "value": "unix:///var/run/datadog/apm.socket" } ], "mountPoints": [ { "containerPath": "/var/run/datadog", "readOnly": true, "sourceVolume": "dd-sockets" } ] } ], "volumes": [ { "host": { "sourcePath": "/var/run/datadog" }, "name": "dd-sockets" } ] } ``` ### Log collection{% #log-collection %} Container log collection through the agent is not supported in daemon mode on ECS Managed Instances. To collect container logs, use one of the following alternatives: - **AWS FireLens**: Configure a Fluent Bit sidecar in your application task definitions. See the [ECS Fargate log collection documentation](https://docs.datadoghq.com/integrations/ecs_fargate/?tab=awscli#log-collection) for setup instructions. - **`awslogs` log driver**: Route logs to Amazon CloudWatch Logs and forward them to Datadog using the [CloudWatch Logs Lambda forwarder](https://docs.datadoghq.com/logs/guide/send-aws-services-logs-with-the-datadog-lambda-function/) or a subscription filter. ### Process collection{% #process-collection %} To collect Live Process information for all your containers and send it to Datadog, update the daemon task definition with the `DD_PROCESS_AGENT_ENABLED` environment variable: ```json { "containerDefinitions": [ { "name": "datadog-agent", ... "environment": [ ... { "name": "DD_PROCESS_AGENT_ENABLED", "value": "true" } ] } ] } ``` ### Cloud Network Monitoring{% #cloud-network-monitoring %} {% alert level="danger" %} This feature is only available for Linux. {% /alert %} Consult the sample [datadog-agent-ecs-managed-instances-daemon-sysprobe.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs-managed-instances-daemon-sysprobe.json) file for a complete task definition. Update your existing daemon task definition to include the following configuration: ```json { "containerDefinitions": [ { "name": "datadog-agent", ... "environment": [ ... { "name": "DD_SYSTEM_PROBE_NETWORK_ENABLED", "value": "true" } ], "linuxParameters": { "capabilities": { "add": [ "SYS_ADMIN", "SYS_RESOURCE", "SYS_PTRACE", "NET_ADMIN", "NET_BROADCAST", "NET_RAW", "IPC_LOCK", "CHOWN" ] } }, "mountPoints": [ ... { "containerPath": "/sys/kernel/debug", "sourceVolume": "debug", "readOnly": false } ] } ], "volumes": [ ... { "name": "debug", "host": { "sourcePath": "/sys/kernel/debug" } } ] } ``` For more information, see the [Cloud Network Monitoring](https://docs.datadoghq.com/network_monitoring/cloud_network_monitoring/) documentation. ## Migrate from sidecar to daemon setup{% #migrate-from-sidecar-to-daemon-setup %} Follow these steps to migrate from the legacy sidecar deployment to the daemon deployment. ### 1. Set up the daemon Follow the Setup instructions on this page to create and register a daemon task definition, then create the daemon on your cluster. ### 2. Remove the Datadog Agent sidecar from application task definitions For each application task definition that includes a `datadog-agent` sidecar container, remove the `datadog-agent` entry from `containerDefinitions`. ### 3. Update APM configuration The daemon Agent exposes its trace socket on the host filesystem rather than through a shared in-task volume. Update each application task definition to use the host path. **Remove** the shared empty volume (`"host": {}`) that was used in the sidecar setup and **replace** it with a host path volume: ```json { "containerDefinitions": [ { "name": "", "environment": [ { "name": "DD_TRACE_AGENT_URL", "value": "unix:///var/run/datadog/apm.socket" } ], "mountPoints": [ { "containerPath": "/var/run/datadog", "readOnly": true, "sourceVolume": "dd-sockets" } ] } ], "volumes": [ { "host": { "sourcePath": "/var/run/datadog" }, "name": "dd-sockets" } ] } ``` If you were previously collecting traces over UDP (using the sidecar's `localhost` address), switch to UDS using the configuration above. ### 4. Update process collection The sidecar setup used `pidMode: task` to enable process collection. The daemon setup uses the `DD_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED` environment variable instead. Remove the `pidMode` parameter from your application task definitions. Then confirm the daemon task definition includes: ```json { "name": "DD_PROCESS_CONFIG_PROCESS_COLLECTION_ENABLED", "value": "true" } ``` ### 5. Register and deploy the updated task definitions After completing the changes above, register each updated application task definition and redeploy the associated services. {% tab title="AWS Console" %} 1. In the AWS Console, navigate to **Elastic Container Service** > **Task Definitions**. 1. Select your application task definition and click **Create new revision with JSON**. 1. Apply your changes and click **Create**. 1. Navigate to the service using this task definition, click **Update**, select the new revision, and click **Update Service**. {% /tab %} {% tab title="AWS CLI" %} ```bash aws ecs register-task-definition --cli-input-json file:// aws ecs update-service --cluster --service --task-definition ``` {% /tab %} ## Sidecar setup (legacy){% #sidecar-setup-legacy %} {% alert level="warning" %} Daemon scheduling is the recommended deployment method for ECS Managed Instances. New deployments should use the daemon setup instead. {% /alert %} In the sidecar deployment model, the Datadog Agent runs as an additional container within each application task definition. ### Create the task definition file{% #create-the-task-definition-file %} 1. Download [datadog-agent-ecs-managed-instances-sidecar.json](https://docs.datadoghq.com/resources/json/datadog-agent-ecs-managed-instances-sidecar.json). This file provides minimal configuration for core infrastructure monitoring. 1. Modify the task definition file: - Set the `DD_API_KEY` environment variable by replacing `` with the [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) for your account. Alternatively, you can also [supply the ARN of a secret stored in AWS Secrets Manager](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data-tutorial.html). - Set the `DD_SITE` environment variable to your [Datadog site](https://docs.datadoghq.com/getting_started/site/). Your site is: ### Register the task definition{% #register-the-task-definition %} {% tab title="AWS Console" %} 1. Log in to your [AWS Console](https://aws.amazon.com/console) and navigate to the Elastic Container Service section. 1. Select **Task Definitions** in the navigation pane. On the **Create new task definition** menu, select **Create new task definition with JSON**. 1. In the JSON editor box, paste the contents of your task definition file. 1. Select **Create**. {% /tab %} {% tab title="AWS CLI" %} Use the [AWS CLI](https://aws.amazon.com/cli) to execute the following command: ```bash aws ecs register-task-definition --cli-input-json file:// ``` {% /tab %} ### Run the task as a replica service{% #run-the-task-as-a-replica-service %} {% tab title="AWS Console" %} 1. Log in to your [AWS Web Console](https://aws.amazon.com/console) and navigate to the Elastic Container Service section. 1. Choose the cluster to run the Datadog Agent on. 1. On the **Services** tab, click **Create**. 1. For **Task Definition**, select the task created in the previous steps. 1. Enter a **Service name**. 1. For **Launch type**, choose **Capacity Provider** and select the Managed Instance capacity provider tied to the cluster. 1. For **Number of tasks**, enter `1`. Click **Next step**. 1. Fill in the rest of the optional fields based on your preference. 1. Click **Create service**. {% /tab %} {% tab title="AWS CLI" %} Use the [AWS CLI](https://aws.amazon.com/cli) to execute the following command: ```bash aws ecs create-service --cluster \ --service-name \ --task-definition \ --desired-count 1 ``` {% /tab %} ### Trace collection (APM){% #trace-collection-apm-1 %} #### UDP{% #udp %} To collect traces over UDP, do not set `DD_AGENT_HOST`. Keep the default `localhost` value. #### UDS{% #uds-1 %} To collect traces over UDS: 1. Add an empty volume onto the task definition using the `volumes` parameter. 1. Mount the volume onto the agent and application container using the `mountPoints` parameter. 1. Configure the environmental variable `DD_DOGSTATSD_SOCKET` on the application container and set it to `/var/run/datadog/dsd.socket`. **Example**: Container definitions that configure collecting traces over UDS ```json { "containerDefinitions": [ { "image": "datadog/agent:latest", "mountPoints": [ { "containerPath": "/var/run/datadog", "readOnly": false, "sourceVolume": "dd-sockets" } ], "name": "datadog-agent", ... }, { "environment": [ { "name": "DD_DOGSTATSD_SOCKET", "value": "/var/run/datadog/dsd.socket" } ], "mountPoints": [ { "containerPath": "/var/run/datadog", "readOnly": false, "sourceVolume": "dd-sockets" } ], "name": "app", ... } ], "volumes": [ { "host": {}, "name": "dd-sockets" } ] } ``` ### Process collection{% #process-collection-1 %} You can monitor processes in ECS Managed Instances in Datadog by using the [Live Processes page](https://docs.datadoghq.com/process). To enable process collection, add the [`PidMode` parameter](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#task_definition_pidmode) in the task definition and set it to `task` as follows: ```json "pidMode": "task" ``` ## Troubleshooting{% #troubleshooting %} Need help? Contact [Datadog support](https://docs.datadoghq.com/help/). ## Further reading{% #further-reading %} - [Collect your application logs](https://docs.datadoghq.com/agent/amazon_ecs/logs/) - [Collect your application traces](https://docs.datadoghq.com/agent/amazon_ecs/apm/) - [Collect ECS metrics](https://docs.datadoghq.com/agent/amazon_ecs/data_collected/#metrics) - [Assign tags to all data emitted by a container](https://docs.datadoghq.com/agent/amazon_ecs/tags/) - [Catch and remediate ECS issues faster with default monitors and the ECS Explorer](https://www.datadoghq.com/blog/ecs-default-monitors/)