Ecs Java

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 Java 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 agent’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 the application’s .java files or its build configuration

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.

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

The Java init container copies a single jar, not a directory tree — the copy command differs from the other languages.

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

If JAVA_TOOL_OPTIONS is already set

If the container already sets JAVA_TOOL_OPTIONS, append the -javaagent flag to the existing value rather than overwriting it — losing existing JVM flags (heap settings, GC options, other agents) will change how the application runs:

Check the existing container environment before writing this value.

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 JVM can start before the jar finishes copying, and -javaagent pointing at a missing file makes the JVM fail to start.

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. The JVM prints a Picked up JAVA_TOOL_OPTIONS: line on startup listing the -javaagent flag — that confirms the agent attached. 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 the ADOT Java auto-instrumentation agent into your ECS task definition.

Changes:

• Added a bind mount volume, opentelemetry-auto-instrumentation-java
• Added a non-essential init container that copies javaagent.jar into that volume
• Added JAVA_TOOL_OPTIONS (appended to any existing value) 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 and build config, the task role’s IAM policies, and the service’s sidecars — no CloudWatch Agent or collector was added.

Next steps:

1. Review the diff — confirm JAVA_TOOL_OPTIONS preserves any JVM flags the container already set.
2. Deploy and let the tasks recycle. Look for the Picked up JAVA_TOOL_OPTIONS: line in the logs.
3. Telemetry has nowhere to go yet. No OTLP endpoint was configured, so the agent is using its default (localhost:4317, gRPC — the Java agent’s default, not 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.”