Ecs Node.js

Read instrumentation.md first — it defines what is out of scope (OTLP endpoints, Application Signals). Deploying a collector is a separate, optional step — collector-ecs.md.

Prerequisites

• An existing ECS service running a Node.js application
• The task definition available to edit — as CDK, Terraform, CloudFormation, or raw JSON

Critical Requirements

Do NOT:

• Add a CloudWatch Agent sidecar container, or any collector sidecar — unless you are also deploying a collector (collector-ecs.md), where the CloudWatch Agent sidecar is the primary collector
• Set OTEL_EXPORTER_OTLP_* — leave the SDK’s default endpoint in place — unless you are also deploying a collector (collector-ecs.md), which sets OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_EXPORTER_OTLP_PROTOCOL deliberately
• Set OTEL_AWS_APPLICATION_SIGNALS_*, OTEL_AWS_SERVICE_EVENTS_*, or OTEL_AWS_DYNAMIC_INSTRUMENTATION_*
• Add CloudWatchAgentServerPolicy or AWSXRayDaemonWriteAccess to the task role — unless you are also deploying a collector (collector-ecs.md), which requires CloudWatchAgentServerPolicy on the task role
• Run cdk deploy, terraform apply, or aws ecs update-service automatically
• Modify server.js or any other application source file

On IAM: instrumentation on its own needs no permissions, so this change adds none. The task may later need permission to reach wherever telemetry is sent — that belongs with the destination, not this guide. If you deploy a collector instead (collector-ecs.md), the collector is what gets the IAM — the workload still gets none.

Determine the module format first

The NODE_OPTIONS value differs between CommonJS and ESM. Check package.json:

• "type": "module" → ESM
• "type": "commonjs" or no type field → CommonJS (default)

If the project uses import syntax in its entrypoint without "type": "module", ask the user rather than guessing.

Step 1: Add a shared volume to the task definition

A bind mount (a volume with only a name) is all that is needed — no EFS, no host path.

Step 2: Add the ADOT init container

essential: false matters — the init container exits after the copy, and an essential container exiting would stop the whole task.

Step 3: Configure the application container

For ESM applications, replace the NODE_OPTIONS value with:

Set OTEL_SERVICE_NAME from the existing ECS service or container name. Optionally add OTEL_RESOURCE_ATTRIBUTES for attributes such as deployment.environment=production.

Step 4: Make the application wait for the init container

Without this, the application can start before the SDK finishes copying and NODE_OPTIONS will point at a file that does not exist yet.

Raw task definition JSON

If the task definition is managed as JSON (or through Terraform’s container_definitions), the same four pieces are:

Terraform note: in aws_ecs_task_definition, container_definitions is jsonencode of only the containers array — volumes is a sibling HCL block, not a key inside that JSON. Pasting the whole object below into jsonencode(...) silently drops the volume, after which every mount path is missing and the app starts uninstrumented:

Verify

After the user deploys and tasks recycle:

Then check the application container’s CloudWatch Logs for the literal string AWS Distro of OpenTelemetry automatic instrumentation started successfully — not a bare -i opentelemetry, which also matches the benign @aws/aws-distro-opentelemetry-instrumentation-vercel-ai Failed to register VercelAISpanProcessor line a healthy start always emits. Until a receiver exists at the default OTLP endpoint, exporter connection errors are expected — that is the next step, not a failure of instrumentation.

Completion

Tell the user:

“I’ve wired ADOT Node.js auto-instrumentation into your ECS task definition.

Changes:

• Added a bind mount volume, opentelemetry-auto-instrumentation-node
• Added a non-essential init container that copies the ADOT Node.js SDK into that volume
• Added NODE_OPTIONS (module format: CommonJS/ESM) and OTEL_SERVICE_NAME to the application container, plus the volume mount and a SUCCESS dependency on init

Not changed: your application image, your application source, the task role’s IAM policies, and the service’s sidecars — no CloudWatch Agent or collector was added.

Next steps:

1. Review the diff.
2. Deploy and let the tasks recycle.
3. Telemetry has nowhere to go yet. No OTLP endpoint was configured, so the SDK is using its default (localhost:4318). Two ways to fix that: deploy an OTel Collector alongside it and export to that (collector-ecs.md), or point OTEL_EXPORTER_OTLP_ENDPOINT at an OTLP endpoint you already have.

Let me know if you’d like adjustments before you deploy.”