Ecs Python

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 Python 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 the application’s .py files

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

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

PYTHONPATH must be prepended, not replaced

If the container already sets PYTHONPATH, keep its existing value in the middle so the instrumentation paths are prepended rather than overwriting it:

If the container does not set PYTHONPATH today, use the two-segment form shown above. Check the existing container environment before writing this value — silently dropping an existing PYTHONPATH will break the application’s imports.

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 PYTHONPATH will point at directories 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 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:

Note on pre-fork servers

Gunicorn with its default sync workers and no --preload needs no special handling — instrumentation loads and produces both server spans and nested client spans normally.

The configurations that more often need attention are --preload and async worker classes (gevent, eventlet). If the workload uses one of those and no telemetry appears, the usual remedy is a Gunicorn post_fork hook that re-initializes the SDK — flag that to the user rather than changing the server configuration silently.

Verify

After the user deploys and tasks recycle:

Then check the application container’s CloudWatch Logs. ADOT Python prints no line containing “opentelemetry” — the real startup signal is Configuration of aws_configurator not loaded, configurator already loaded. 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 Python auto-instrumentation into your ECS task definition.

Changes:

• Added a bind mount volume, opentelemetry-auto-instrumentation-python
• Added a non-essential init container that copies the ADOT Python SDK into that volume
• Added PYTHONPATH (prepended 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, 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 the PYTHONPATH value preserves any path the container already relied on.
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.”