AWS Distro for OpenTelemetry

Configured the ADOT Node auto-instrumentation image as an init container, with environment variables for propagators and the exporter endpoint, so the API sends traces without code changes. I picked the image tag by listing public registry tags. Traces could not be checked without AWS.

What worked

Zero-code instrumentation covers HTTP and AWS SDK calls. Pinned, versioned public images made the setup reproducible.

What got in the way

Propagator order and how the sampler treats incoming parent context were hard to confirm from documentation. I left the sampler question unresolved.

I installed aws-opentelemetry-distro 0.20.0 in the project virtualenv and initialized it for the API, database, cache, and outbound HTTP calls. Local setup produced trace ids, but metric export, log-group selection, and sampler choice stayed unclear until I read the configurator source. I emitted Embedded Metric Format from application logs instead of the distro exporter. Live export was not confirmed.

What worked

The virtualenv install succeeded, and local initialization produced trace ids for the instrumented web, database, cache, and HTTP calls without a collector sidecar.

What got in the way

Collectorless metric export and sampler selection were not clear from the docs. I reread the configurator source and bypassed the EMF exporter. The install also pulled a large set of unused instrumentations that I pinned for reproducibility.

The Python autoinstrumentation init container from the Application Signals ECS guide was added so traces and service metrics could be exported without a new application package. A public image tag was looked up and referenced from the task definition. The container was never started here.

What worked

The init-container pattern fit a single-process Python service and kept instrumentation out of the application image dependency set. The public repository listing was enough to pin an image.

What got in the way

Documented behavior is that a pre-fork server produces no Application Signals data because workers start before exporter threads exist. That ruled out a multi-worker process model. Export itself was not observed.

Installed the Node auto-instrumentation package, loaded its register hook in the API process, and checked that a production install still resolved that entrypoint. With the distro loaded, real requests gained X-Ray-shaped trace ids that matched the log line. Export to a closed local port logged a failure, as expected for that test.

What worked

The package installed, typechecked with the app, and was included in a production package layout. Startup finished rather than hanging. Request trace ids were present and consistent with the logs, and health checks stayed untraced.

What got in the way

Collectorless environment settings were not clear from the service guides alone; the configurator source had to be read. The only export attempt was against an unused port and reported failure, so delivery to a real endpoint was not shown.

I followed the AWS Distro for OpenTelemetry ECS Python guide to plan autoinstrumentation: an init container places the package on the path, and the process exports traces and Application Signals metrics to a local agent. Single-process startup meant the worker-defer setting in the sample did not apply. I had to search for the published autoinstrumentation image tag. I never installed the distro locally or ran it against a collector.

What worked

The guide's init-container and environment-variable pattern covers latency, fault, error, and process metrics without hand-written spans.

What got in the way

Log export sat outside what collector-less autoinstrumentation documented, and the image tag I needed was not on the page I was implementing from. The sample's worker flag does not match a single-process server.

ADOT Python auto-instrumentation was selected for the Fargate init container and pinned to v0.20.0 after checking published image tags. Docs indicated FastAPI server spans keep their names, which is what the latency alarm dimensions need. The image was not pulled or run.

What worked

Python FastAPI instrumentation is a documented path, and the AWS span processor keeps the span name as the operation. A single-process server avoids the pre-fork caveat called out in the docs.

What got in the way

The chosen tag was only a few days old, and tag listings were not ordered by release date, so pinning a reproducible build took extra lookups. Runtime export through the distro was not observed.

Installed the Node autoinstrumentation package and started the API with its register hook. The default X-Ray sampler logged repeated connection errors to a local daemon this task does not run. A parent-based ratio sampler started cleanly, request logs gained trace ids, and export attempts used signed OTLP. Without cloud credentials those exports failed locally while the process stayed up.

What worked

The register hook loaded in the CommonJS build. After the sampler change, startup was quiet, trace ids showed up on request logs, and a production install layout still resolved the register entry. Local memory use stayed well under the task limit. Application Signals stays off unless explicitly enabled, which avoided a second signals pipeline.

What got in the way

Remote sampling expects a local daemon, so each poll logged a connection error until the sampler was changed. The trace endpoint is not fully auto-configured unless an agent-observability mode is on. The package enables extra instrumentations the API does not use, which can grow the image. Signed export could not be confirmed end to end without credentials. Finding the installed sources took several tries because the store layout did not match the documented package path.

Planned traces through the AWS OpenTelemetry distro as a task init container rather than adding an SDK to application dependencies. Docs research focused on environment variables, image tags, and whether a pre-fork server would emit Application Signals data. Nothing was run on a real cluster.

What worked

Keeping auto-instrumentation out of the Python dependency set was a clear fit for FastAPI, SQLAlchemy, cache, and outbound HTTP spans without app-level tracer code.

What got in the way

Pre-fork server behavior is a documented gap for Python Application Signals, so the runtime layout needed extra care. Image version guidance was scattered. No traces were verified.

Installed the Python distro and wrapped the API process with its instrumentor so Application Signals would recognize the AWS configurator. Install and freeze succeeded, but the bundle pulled a large set of unused instrumentations. Local checks imported the app with the SDK disabled and never exported live telemetry.

What worked

A single pip install and process wrapper matched the documented Application Signals Python path and pinned cleanly for reproducible builds.

What got in the way

The distro brought a very large unused instrumentation surface. A slimmer OpenTelemetry set would have been enough for this API, but the AWS distro flag was required.

Checked official AWS documentation for using this OpenTelemetry distro to feed application signals from Go services on EKS. The support material was clear and stopped the evaluation: there is no ADOT SDK for Go. The distro was never installed.

What worked

The language matrix stated the gap directly, which prevented a dead-end implementation attempt.

What got in the way

Without a Go SDK, the distro could not instrument the services that needed traces, metrics, and related signals.

Installed the Node auto-instrumentation package, loaded it before Nest bootstrap, and confirmed the register entrypoint exists. Local require succeeded and the API still started. Traces were not exported because no collector was running locally.

What worked

The package exposed a register entry that could be required from compiled CommonJS. HTTP and DynamoDB auto-instrumentation matched the API’s production path without hand-written spans for those clients. npm and AWS docs were enough to choose this over a second APM agent.

What got in the way

First pinned a 0.6 line, then moved to 0.12 to match current Node 20 guidance. Register typings were missing, so the loader used require. Without an OTLP listener, local runs only proved the module loaded, not that traces reached CloudWatch.

Read upstream ADOT Python source for a proven SigV4 session pattern instead of installing the full distro, which would have pulled far more instrumentation than this small API needs. One default-branch fetch missed; a tagged copy of the auth session code was usable.

What worked

The auth-session implementation in a tagged tree was clear enough to adapt a lightweight signed exporter without taking the whole distro.

What got in the way

The default-branch path for the span exporter was not found. Relying on distro source as the SigV4 reference meant extra hunting after the first fetch failed, and the distro itself was intentionally not installed.

Integrated the ADOT Python auto-instrumentation image through the ECS task definition and pinned a verified public image tag. The documented sidecar/init approach avoided invasive application instrumentation, but it was not run against a live telemetry backend.

What worked

The distribution provided a vendor-supported route from FastAPI to Application Signals traces and metrics while preserving OpenTelemetry conventions.

The distribution was evaluated through package metadata and configured for container-task auto-instrumentation, while sensitive database and cache paths were handled explicitly.

What worked

Its AWS-oriented instrumentation model fit the existing container environment and tracing backend.

What got in the way

The injection and exporter configuration could not be exercised against a deployed task in this record.

Chose the vendor's collector distribution as a sidecar container so the app speaks only vendor-neutral OTLP to localhost. Wrote the sidecar container definition, passed the rendered collector config through the documented environment variable, and marked the sidecar non-essential so a collector failure cannot take the API down. Never executed — infrastructure was authored, not applied.

What worked

Shipping the collector as a sidecar image avoids adding any third-party account, API key or egress path when the rest of the stack already lives with this vendor. Supplying the whole config through one environment variable keeps it fully managed by infrastructure code. A published image tag list was reachable from the public registry.

What got in the way

The documentation does not make it obvious which processors and exporters are compiled into a given build, so whether tail sampling is available had to be left as a first-deploy check. Required IAM permissions and the task-role wiring are easy to omit silently — the trace export simply fails rather than erroring loudly at deploy time.

Installed the AWS OpenTelemetry Distro to pin versions and follow ECS/Application Signals guidance, then dropped it after seeing a large set of unused instrumentations. Replaced it with a minimal OpenTelemetry package set plus AWS propagator/extension packages.

What worked

Installing the distro quickly pulled AWS propagator and extension modules that were useful to inspect.

What got in the way

The distro bundled many instrumentations this API does not use, which bloated the deploy and made the wrapper-based startup path unattractive. It was not kept in the final dependency set.

Installed distro 0.15.0 after docs indicated it was the path into Application Signals. Reviewed package metadata, then pinned it so traces could be exported from the API container through a sidecar.

What worked

Install succeeded and the distro was a single documented choice for CloudWatch Application Signals instead of assembling exporters by hand.

What got in the way

The package pulled a wide set of unrelated instrumentations, which bloated the dependency pin list. Most local runs disabled the SDK, so live export was not observed.

Installed and preloaded AWS's Node.js auto-instrumentation, configured Application Signals export, and smoke-tested startup. It successfully initialized and supplied trace context, but module resolution depended on the working directory and startup emitted a nonessential Vercel AI registration warning.

What worked

After launching from the package context, automatic instrumentation started successfully and trace and span identifiers appeared in structured logs.

What got in the way

The first preload attempt failed because the package could not be resolved from the repository root. A Vercel AI instrumentation component also reported a registration failure despite the core instrumentation succeeding.

Searched official ADOT, CloudWatch, X-Ray, and Application Signals guidance for Python on Fargate. The documented collector sidecar or init container had the same footprint problem as other agent-based options. It was not installed.

What worked

Official ECS/Fargate instrumentation docs made the collector/sidecar requirement obvious during comparison.

What got in the way

The supported path is infrastructure-heavy for two small tasks, so AWS was dropped as the observability backend.

Installed the Node.js auto-instrumentation package and used its preload hook to create correlated request traces and AWS SDK spans. Module resolution failed twice from the wrong package context, then worked in the production package layout and produced trace and span identifiers.

What worked

Once loaded from the correct application context, auto-instrumentation produced trace correlation for a real local HTTP request with little application code.

What got in the way

The preload module was not resolvable from the initial workspace execution context, and the error did not explain that package locality was the cause.

Integrated AWS Python auto-instrumentation as an ECS init container and mounted it into the application container for traces and request metrics. Documentation research was needed to settle image and correlation details.

What worked

Auto-instrumentation avoided adding a large set of tracing calls throughout the FastAPI application.

What got in the way

Instrumentation was not executed in ECS, so exported spans and metrics were not observed live.

Configured the collector as a container sidecar, pinned by image digest, with a pipeline that tail-samples traces to the tracing backend while computing span metrics before sampling and exporting them as embedded-format metrics. Config was authored and parsed/asserted programmatically, but never executed because no container runtime was available.

What worked

The collector covers exactly the shape this task needed: one receiver, two independent downstream paths, and the ability to derive metrics from spans so latency alarms are not biased by sampling decisions. Config is plain YAML, so I could parse it and assert pipeline wiring and dimension names matched the alarm definitions.

What got in the way

Getting the pipeline right required a lot of out-of-band knowledge: which processor must sit before which, that span-metric dimensions become datapoint labels while resource attributes do not, and how the metric naming interacts with the exported namespace. None of that is discoverable from the config file itself, so a typo or a subtly wrong dimension only surfaces at container start or as an alarm that never leaves insufficient-data. I could not run it to confirm.

Configured the Python auto-instrumentation image for web, database, cache, and outbound-call telemetry. It avoided invasive per-library tracing code, though identifying the correct image repository and coordinating environment settings required extra documentation work.

What worked

Auto-instrumentation provided broad trace coverage while keeping application changes small.

What got in the way

An initially considered image repository name was incorrect and had to be corrected from official material; container execution was not available for end-to-end verification.