EC2 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-ec2.md.

Critical Requirements

Do NOT:

• Install or configure the CloudWatch Agent, or any collector, on the instance — unless you are also deploying a collector (collector-ec2.md), where the CloudWatch Agent is the primary collector
• Set OTEL_TRACES_SAMPLER=xray, or any localhost:4316 / localhost:2000 endpoint — these stay forbidden in all cases
• Set OTEL_EXPORTER_OTLP_* — unless you are also deploying a collector (collector-ec2.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 instance role — unless you are also deploying a collector (collector-ec2.md), which requires CloudWatchAgentServerPolicy on the instance role
• Run cdk deploy / terraform apply, or modify a running instance in place
• Remove or reorder existing UserData commands — append in sequence
• Modify server.js or any other application source file

On IAM: instrumentation on its own needs no permissions, so this change adds none. The instance 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-ec2.md), the collector is what gets the IAM — the workload still gets none.

Before you start: gather these values

If you cannot determine a value from the IaC, ask the user. Do not guess.

• Deployment type — read the UserData and find the command that starts the application. docker run / docker start → Docker. node, npm start, yarn start → runs directly on the instance. If it is unclear, ask.
• Module format — check package.json: "type": "module" → ESM; "type": "commonjs" or no type field → CommonJS.
• <APP_DIR> — where the application code lives on the instance (look for cd, git clone, or file copy commands). Needed for the non-Docker path, because the SDK must land in <APP_DIR>/node_modules for Node’s module resolution to find it.
• <ENTRY_POINT> — the JavaScript file that starts the app (server.js, index.js, app.js).
• <SERVICE_NAME> — the application or stack name; becomes OTEL_SERVICE_NAME.
• Instance OS — Amazon Linux 2 uses yum, Amazon Linux 2023 uses dnf, Ubuntu/Debian uses apt. Look at the existing package commands in UserData or the AMI reference.

Terraform heredoc warning: when adding lines to a user_data heredoc, match the exact leading whitespace of the existing lines. <<-EOF only strips indentation when it is consistent; inconsistent indentation leaves spaces before #!/bin/bash and cloud-init fails.

The application runs directly on the instance

Step 1: Install the SDK into the application’s directory

CommonJS:

ESM — also install the instrumentation package, whose ESM hook is referenced by the loader flag:

Place this after the application’s own dependency install.

Step 2: Load the SDK at startup

Find the existing node command and add the flags plus OTEL_SERVICE_NAME.

CommonJS:

ESM:

If the application runs as a systemd service

An export in UserData does not reach a process started by a .service unit — ExecStart is a fresh process that does not inherit the UserData shell’s environment. Put the variables on the unit instead:

Then add systemctl daemon-reload and systemctl restart <SERVICE_NAME> to UserData. (Equivalently, write the KEY=VALUE pairs to a file and reference it with EnvironmentFile=.)

The application runs in a Docker container on the instance

The SDK has to be present inside the container — npm install in UserData installs on the host, where the containerized process cannot see it. There are two ways to get it there.

Option A (preferred): bind-mount the SDK from the host — no image rebuild

Copy the SDK out of the ADOT image into a host directory, then mount that directory into the application container:

Then add the mount and the environment variables to the existing docker run:

For ESM, use:

Keep every flag the existing docker run already had — ports, networks, volumes, restart policy. This option leaves the application image untouched.

Option B: install the SDK in the image

If the user prefers the SDK baked into the image, add it to the Dockerfile after the existing dependency install and change CMD:

Add -e OTEL_SERVICE_NAME=<SERVICE_NAME> to the docker run either way. This option requires rebuilding and republishing the image, so mention that trade-off when you propose it.

Verify

After the user deploys and the instance boots:

• Non-Docker: check the application’s own log destination, or journalctl -u <SERVICE_NAME> for a systemd service. Grep the literal success 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 that a healthy start always emits. /var/log/cloud-init-output.log shows whether the npm install succeeded.
• Docker: docker logs <APP_NAME>.

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 EC2 deployment.

Changes:

• UserData: installed the ADOT Node.js SDK (or staged it on the host for a bind mount, for the Docker path)
• Startup: added the node loader flags — or NODE_OPTIONS for the container — and OTEL_SERVICE_NAME
• systemd unit, if the app runs as a service: added Environment= and updated ExecStart (an export in UserData would not reach it)

Not changed: your application source, the instance role’s IAM policies, and the instance’s software — no CloudWatch Agent or collector was installed.

Next steps:

1. Review the diff.
2. Deploy and replace the instance (UserData runs at first boot only).
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-ec2.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.”