Registry / aws / aws-opentelemetry-distro

aws-opentelemetry-distro

JSON →
library0.19.0pypypi✓ verified 23d ago

The AWS OpenTelemetry Python Distro (`aws-opentelemetry-distro`) is a distribution of the OpenTelemetry Python SDK, pre-configured for AWS environments. It includes AWS-specific resource detectors, X-Ray compatible trace ID generation, and automatic instrumentation for AWS SDK (boto3/botocore) and popular frameworks. It aims to simplify the adoption of OpenTelemetry for applications running on AWS, providing a streamlined path to send traces, metrics, and logs to services like AWS X-Ray and Amazon CloudWatch. The current version is `0.17.0`, with releases typically aligning with upstream OpenTelemetry component updates and AWS-specific feature additions.

pip install aws-opentelemetry-distro
INSTALL
IMPORT
SIG · AWS-OPENTELEMETRY-
A
aws-opentelemetry-distro
awspythonv0.19.0
Install
9.5s avg
Import
Disk
64MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 65.3MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 9.5s · import 0.000s · 64MB
64MB installed
● package 64MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

start_tracing
from amazon.opentelemetry.distro import start_tracing
from amazon.opentelemetry.distro import start_tracing

This quickstart demonstrates the most basic usage: initializing the distro and creating a simple trace span. For traces to be actually collected and visible, you need to configure an OTLP exporter, typically via environment variables like `OTEL_EXPORTER_OTLP_ENDPOINT` pointing to an OpenTelemetry Collector or AWS X-Ray daemon.

import os from aws_opentelemetry_distro import start_tracing from opentelemetry import trace # 1. Initialize the AWS OpenTelemetry Distro. # This sets up the global trace provider, resource detectors, and default exporters # based primarily on environment variables (e.g., OTEL_EXPORTER_OTLP_ENDPOINT). # In AWS Lambda or ECS/EC2 with the ADOT Collector, these environment variables are often pre-configured. start_tracing() # 2. Get a tracer and create a span. tracer = trace.get_tracer("my-application-tracer") with tracer.start_as_current_span("my-aws-operation") as span: span.set_attribute("service.name", "my-app") span.set_attribute("aws.region", os.environ.get("AWS_REGION", "us-east-1")) print("Performing some instrumented work with AWS OpenTelemetry Distro...") # Simulate some work import time time.sleep(0.1) print("Application finished. Spans were sent to the configured OTLP endpoint.") print("To see output, ensure OTEL_EXPORTER_OTLP_ENDPOINT is set (e.g., to a local ADOT Collector or X-Ray daemon).")
Debug
Known issues
breakingVersion `0.13.0` was explicitly deprecated due to a critical issue and should not be used. All users on this version should revert to an older stable release or upgrade to `0.14.0` or newer.
fix
Upgrade to `aws-opentelemetry-distro>=0.14.0` or revert to a stable older version.
affects: 0.13.0
gotchaThe distro heavily relies on environment variables for configuration (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_PYTHON_CONFIGURATOR`, `AWS_LAMBDA_EXEC_WRAPPER`). For full observability, ensure these are correctly set for your deployment environment (e.g., pointing to an ADOT Collector or X-Ray daemon). Without a configured exporter, traces will be generated but not sent anywhere.
fix
Set appropriate OpenTelemetry environment variables according to your deployment target (e.g., `export OTEL_EXPORTER_OTLP_ENDPOINT='http://localhost:4317'`). Consult the official documentation for specific deployment scenarios (Lambda, EC2, ECS).
affects: All
gotchaWhen using Django instrumentation, the `DJANGO_SETTINGS_MODULE` environment variable must be correctly set, otherwise Django auto-instrumentation will be disabled. This prevents issues when running Django-based applications where the settings module is not immediately available.
fix
Ensure `DJANGO_SETTINGS_MODULE` is correctly defined in your environment when instrumenting Django applications.
affects: >=0.14.1
gotchaUpdating `aws-opentelemetry-distro` bundles updates to upstream OpenTelemetry Python components (SDK, API, instrumentations). While this simplifies dependency management, new versions of these upstream components might introduce breaking changes or behavioral shifts that you should be aware of, even if the `aws-opentelemetry-distro` itself has no direct breaking changes.
fix
Review the release notes for both `aws-opentelemetry-distro` and the bundled OpenTelemetry Python components when upgrading major or minor versions.
affects: All
Upgrade
Version history
0.19.0latest on PyPI · released Jul 23, 2026
Audit
Dependencies
opentelemetry-apirequiredCore OpenTelemetry API, bundled and managed by the distro.
opentelemetry-sdkrequiredCore OpenTelemetry SDK, bundled and managed by the distro.
opentelemetry-instrumentation-botocorerequiredProvides automatic instrumentation for AWS SDK (boto3).
opentelemetry-exporter-otlp-proto-grpcrequiredEnables exporting telemetry data via OTLP/gRPC.
Agent activity
33 hits · last 30 days
node
28
OpenAI (training)
1
Resources
aws-opentelemetry-distro — pip install aws-opentelemetry-distro · libregistry