Ecs .NET

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 .NET application
• The task definition available to edit — as CDK, Terraform, CloudFormation, or raw JSON
• Whether the task runs Linux or Windows Server containers (the paths and the copy command differ)

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 the application’s .cs files or its .csproj

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

Linux containers

Windows Server containers

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

.NET needs the most environment variables of any language, because the CoreCLR profiler is loaded by the runtime at process start and reads its configuration entirely from the environment.

Four of them are what actually attach the profiler — omit any one and the app starts normally with no instrumentation and no error: CORECLR_ENABLE_PROFILING, CORECLR_PROFILER, CORECLR_PROFILER_PATH, DOTNET_STARTUP_HOOKS. OTEL_DOTNET_AUTO_HOME and OTEL_DOTNET_AUTO_PLUGINS select the ADOT distro’s behaviour.

DOTNET_ADDITIONAL_DEPS and DOTNET_SHARED_STORE are set for parity with the distro’s own instrument.sh, but the AdditionalDeps/ and store/ directories do not exist in the container image (they ship only in the tarball). Instrumentation works with both paths dangling, so do not treat them as evidence of a broken install when auditing paths.

Linux containers

CORECLR_PROFILER_PATH depends on two things, and none of this guide’s other checks catch getting it wrong — a bad path means the profiler silently does not attach:

• Architecture, from the task: linux-x64 for X86_64, linux-arm64 for ARM64 (Graviton). Check runtimePlatform.cpuArchitecture; Fargate defaults to X86_64 when it is unset.
• libc, from the application’s base image — not the task. linux-<arch> for glibc bases (mcr.microsoft.com/dotnet/aspnet:*, Debian, Ubuntu); linux-musl-<arch> for Alpine bases.

The amd64 image ships linux-x64 and linux-musl-x64, and no linux-arm64 — so on X86_64 the choice is entirely about the image’s libc. If you are unsure, list what the image actually shipped rather than inferring it.

Windows Server containers

Same variables, with Windows paths and the native DLL instead of the shared object:

Mount the volume at C:\otel-auto-instrumentation on the application container as well.

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 the profiler paths will point at files that do 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, Linux shown, 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:

Do not check the application container’s log for OpenTelemetry startup lines — ADOT .NET writes none there at the default level: a fully working task logs nothing matching opentelemetry|otlp|exporter, and the init container’s log stream is empty because cp -a is silent. Judge init by exitCode: 0, not content.

The check that matters for .NET is that every CoreCLR variable reached the running process and each path it names exists — if one is missing or wrong, the profiler does not attach and the application starts normally with no instrumentation and no error. On Fargate that needs ECS Exec (enableExecuteCommand plus ssmmessages:*Channel on the task role), which is a verification-only addition — say so if you add it:

The SDK also writes its own log at the default level — /tmp/otel-dotnet-auto-<pid>-<App>-Managed-<date>.log, carrying The profiler has been initialized with NN direct definitions — but that file lives in the task’s filesystem and is never sent to the awslogs stream, so on Fargate it needs ECS Exec too. It is not a fallback for not having Exec.

Without ECS Exec, the honest position is that there is no local verification on Fargate: rely on init exit code 0, the task definition diff, and — once a destination exists — spans arriving.

Note DOTNET_ADDITIONAL_DEPS and DOTNET_SHARED_STORE name directories that are not shipped in the container image; both dangle on a working deployment and are not the fault.

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 .NET auto-instrumentation into your ECS task definition.

Changes:

• Added a bind mount volume, opentelemetry-auto-instrumentation-dotnet
• Added a non-essential init container that copies the ADOT .NET SDK into that volume
• Added the CoreCLR profiler variables, the SDK location variables, 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 .csproj, 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 CORECLR_PROFILER_PATH matches your task’s OS and CPU architecture.
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.”