--- title: Install the DDOT Collector on ECS Fargate description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: >- Docs > OpenTelemetry in Datadog > Send OpenTelemetry Data to Datadog > Datadog Distribution of OpenTelemetry Collector > Install > Install the DDOT Collector on ECS Fargate --- # Install the DDOT Collector on ECS Fargate {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site). (). {% /alert %} {% /callout %} ## Overview{% #overview %} Follow this guide to deploy the Datadog Distribution of OpenTelemetry (DDOT) Collector alongside the Datadog Agent on Amazon ECS Fargate. Because ECS Fargate does not support host-based deployments, the Datadog Agent runs as a sidecar container in the same ECS task as your application. {% alert level="info" %} **Need additional OpenTelemetry components?** If you need components beyond those included in the default package, follow [Use Custom OpenTelemetry Components](https://docs.datadoghq.com/opentelemetry/setup/ddot_collector/custom_components) to extend the Datadog Agent's capabilities. For a list of components included by default, see [OpenTelemetry Collector components](https://docs.datadoghq.com/opentelemetry/agent/#opentelemetry-collector-components). {% /alert %} ## Requirements{% #requirements %} To complete this guide, you need the following: **Datadog account**: 1. [Create a Datadog account](https://www.datadoghq.com/free-datadog-trial/) if you don't have one. 1. Find or create your [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys/). **AWS**: - An AWS account with access to Amazon ECS Fargate. - The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) configured with permissions to create and manage ECS task definitions and services. **Network**: When using the Datadog SDK with OpenTelemetry API support, telemetry is routed to different components depending on the signal source. Ensure the following ports are accessible on your Datadog Agent or Collector: | Signal Source | Protocol | Port | Destination Component | | ------------------------- | -------------------- | ----------- | --------------------------------------------- | | OTel Metrics and Logs API | OTLP (gRPC/HTTP) | 4317 / 4318 | Datadog Agent OTLP Receiver or DDOT Collector | | Datadog Tracing | Datadog trace intake | 8126 (TCP) | Datadog Trace Agent | | Runtime Metrics | DogStatsD | 8125 (UDP) | DogStatsD Server | ## Install the Datadog Agent with OpenTelemetry Collector{% #install-the-datadog-agent-with-opentelemetry-collector %} {% alert level="info" %} This installation is required for both Datadog SDK + DDOT and OpenTelemetry SDK + DDOT configurations. While the Datadog SDK implements the OpenTelemetry API, it still requires the DDOT Collector to process and forward OTLP metrics and logs. {% /alert %} ### Create an ECS task definition{% #create-an-ecs-task-definition %} On ECS Fargate, the Datadog Agent and your application run as containers within the same ECS task. Create an ECS task definition that includes both containers. {% alert level="info" %} The Datadog Agent image must be `public.ecr.aws/datadog/agent:latest-full`. The `latest-full` image includes the DDOT Collector. The standard `latest` image does not. {% /alert %} Use the following task definition as a starting point: In the `task-definition.json` file: ```json { "family": "", "containerDefinitions": [ { "name": "datadog-agent", "image": "public.ecr.aws/datadog/agent:latest-full", "essential": true, "cpu": 0, "environment": [ { "name": "ECS_FARGATE", "value": "true" }, { "name": "DD_LOGS_ENABLED", "value": "true" }, { "name": "DD_OTELCOLLECTOR_ENABLED", "value": "true" }, { "name": "DD_SITE", "value": "" }, { "name": "DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL", "value": "true" } ], "secrets": [ { "name": "DD_API_KEY", "valueFrom": "" } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/", "awslogs-create-group": "true", "awslogs-region": "", "awslogs-stream-prefix": "ecs" } }, "mountPoints": [], "portMappings": [], "volumesFrom": [] }, { "name": "", "image": "", "essential": true, "cpu": 0, "environment": [ { "name": "OTEL_SERVICE_NAME", "value": "" }, { "name": "OTEL_RESOURCE_ATTRIBUTES", "value": "service.version=,deployment.environment.name=" } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/", "awslogs-create-group": "true", "awslogs-region": "", "awslogs-stream-prefix": "ecs" } }, "mountPoints": [], "portMappings": [], "volumesFrom": [] } ], "executionRoleArn": "", "networkMode": "awsvpc", "volumes": [], "requiresCompatibilities": [ "FARGATE" ], "cpu": "256", "memory": "512" } ``` Replace the following placeholders: - ``: A name for your ECS task definition family. - ``: The ARN of the AWS Secrets Manager secret or SSM Parameter Store parameter that contains your Datadog API key. The task execution role must have `secretsmanager:GetSecretValue` (Secrets Manager) or `ssm:GetParameters` (SSM) permission to retrieve the secret. - ``: Your [Datadog site](https://docs.datadoghq.com/getting_started/site). Your site is . (Ensure the correct **DATADOG SITE** is selected on the right.) - ``: The AWS region where your ECS tasks run (for example, `us-east-1`). - ``: The name of your application container. - ``: Your application container image. - ``: The name of your service. - ``: The version of your service. - ``: Your deployment environment (for example, `production`). - ``: The ARN of your ECS task execution IAM role. ### Configure ECS resource detection{% #configure-ecs-resource-detection %} The DDOT Collector's `infraattributes` processor enriches your telemetry with ECS infrastructure tags when the `aws.ecs.task.arn` resource attribute is present. To provide this attribute, add the ECS resource detector to your OpenTelemetry SDK. The ECS resource detector automatically populates the following attributes: - `aws.ecs.task.arn` - `aws.ecs.launchtype` (set to `fargate`) - `cloud.provider` Refer to your language's OpenTelemetry SDK documentation to add the ECS resource detector. For example: - **Go**: [go.opentelemetry.io/contrib/detectors/aws/ecs](https://pkg.go.dev/go.opentelemetry.io/contrib/detectors/aws/ecs#NewResourceDetector) - **All languages**: See the [ECS resource detector documentation](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/resourcedetectionprocessor/internal/aws/ecs/documentation.md) in the OpenTelemetry Collector contrib repository. ## Send your telemetry to Datadog{% #send-your-telemetry-to-datadog %} To send your telemetry data to Datadog: 1. Instrument your application 1. Configure the application 1. Correlate observability data 1. Run your application ### Instrument the application{% #instrument-the-application %} Instrument your application [using the OpenTelemetry API](https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/otel_instrumentation/). {% collapsible-section %} Example application instrumented with the OpenTelemetry API As an example, you can use the [Calendar sample application](https://github.com/DataDog/opentelemetry-examples/tree/main/apps/rest-services/java/calendar) that's already instrumented for you. The following code instruments the [CalendarService.getDate()](https://github.com/DataDog/opentelemetry-examples/blob/main/apps/rest-services/java/calendar/src/main/java/com/otel/service/CalendarService.java#L27-L48) method using the OpenTelemetry annotations and API: In the `CalendarService.java` file: ```java @WithSpan(kind = SpanKind.CLIENT) public String getDate() { Span span = Span.current(); span.setAttribute("peer.service", "random-date-service"); ... } ``` {% /collapsible-section %} ### Configure the application{% #configure-the-application %} Because the DDOT Collector runs as a sidecar container in the same ECS task, your application sends OTLP data to `localhost`. Add the following environment variables to your application container in the task definition: In the `task-definition.json` file: ```json { "name": "OTEL_EXPORTER_OTLP_ENDPOINT", "value": "http://localhost:4317" }, { "name": "OTEL_EXPORTER_OTLP_PROTOCOL", "value": "grpc" } ``` ### Correlate observability data{% #correlate-observability-data %} [Unified service tagging](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging) ties observability data together in Datadog so you can navigate across metrics, traces, and logs with consistent tags. The `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` environment variables in the task definition above configure unified service tagging. ### Run the application{% #run-the-application %} 1. Register the task definition with AWS: ```bash aws ecs register-task-definition --cli-input-json file://task-definition.json ``` 1. If you don't have an ECS cluster, create one: ```bash aws ecs create-cluster --cluster-name ``` 1. Create an ECS service to run the task: ```bash aws ecs create-service \ --cluster \ --service-name \ --task-definition \ --desired-count 1 \ --launch-type FARGATE \ --network-configuration "awsvpcConfiguration={subnets=[],securityGroups=[],assignPublicIp=ENABLED}" ``` Replace `` with your ECS cluster name, `` with a name for your ECS service, `` with your subnet IDs (comma-separated), and `` with your security group IDs. If you are updating an existing service to a new task definition revision, run: ```bash aws ecs update-service \ --cluster \ --service \ --task-definition ``` After the task starts, unified service tagging is fully enabled for your metrics, traces, and logs. ### Validate the deployment{% #validate-the-deployment %} 1. Verify that your ECS task is running and both containers are in `RUNNING` state: ```shell aws ecs describe-tasks \ --cluster \ --tasks \ --query "tasks[0].containers[*].{name:name,status:lastStatus}" \ --output table ``` Use Datadog to explore the observability data for your application. ### Logs{% #logs %} View logs to monitor and troubleshoot application and system operations. {% image source="https://datadog-docs.imgix.net/images/opentelemetry/embedded_collector/logs.3399501b14c5a2c7bf9ab8dd4aa8bf52.png?auto=format" alt="View logs from the Log Explorer." /%} ### Traces{% #traces %} View traces and spans to observe the status and performance of requests processed by your application, with infrastructure metrics correlated in the same trace. {% image source="https://datadog-docs.imgix.net/images/opentelemetry/embedded_collector/traces.0dfe8b50575dbfcea5b0d06131826db9.png?auto=format" alt="View traces from the Trace Explorer." /%} ### Runtime metrics{% #runtime-metrics %} Monitor your runtime (JVM) metrics for your applications. {% image source="https://datadog-docs.imgix.net/images/opentelemetry/embedded_collector/metrics.1f91a119276f91ecfb2976f16eed58ef.png?auto=format" alt="View JVM metrics from the JVM Metrics dashboard" /%} ### Collector health metrics{% #collector-health-metrics %} View metrics from the DDOT Collector to monitor the Collector health. {% image source="https://datadog-docs.imgix.net/images/opentelemetry/embedded_collector/dashboard.f6e65b6b9a8708b1a7e172da215947af.png?auto=format" alt="View Collector health metrics from the OTel dashboard." /%} ## Further reading{% #further-reading %} - [Use Custom OpenTelemetry Components with Datadog Agent](https://docs.datadoghq.com/opentelemetry/setup/ddot_collector/custom_components)