{"id":3410,"library":"aws-opentelemetry-distro","title":"AWS OpenTelemetry Python Distro","description":"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.","status":"active","version":"0.17.0","language":"en","source_language":"en","source_url":"https://github.com/aws-observability/aws-otel-python-instrumentation/tree/main/aws-opentelemetry-distro","tags":["aws","opentelemetry","observability","tracing","metrics","logs","x-ray","cloudwatch"],"install":[{"cmd":"pip install aws-opentelemetry-distro","lang":"bash","label":"Install core distro"},{"cmd":"pip install aws-opentelemetry-distro[all]","lang":"bash","label":"Install with all common instrumentations (e.g., boto3, flask, django)"}],"dependencies":[{"reason":"Core OpenTelemetry API, bundled and managed by the distro.","package":"opentelemetry-api"},{"reason":"Core OpenTelemetry SDK, bundled and managed by the distro.","package":"opentelemetry-sdk"},{"reason":"Provides automatic instrumentation for AWS SDK (boto3).","package":"opentelemetry-instrumentation-botocore"},{"reason":"Enables exporting telemetry data via OTLP/gRPC.","package":"opentelemetry-exporter-otlp-proto-grpc"}],"imports":[{"note":"This function initializes the OpenTelemetry environment with AWS-specific configurations.","symbol":"start_tracing","correct":"from aws_opentelemetry_distro import start_tracing"},{"note":"Used for advanced manual resource detection beyond what `start_tracing` provides by default.","symbol":"AwsResourceDetector","correct":"from aws_opentelemetry_distro.aws_resource_detector import AwsResourceDetector"}],"quickstart":{"code":"import os\nfrom aws_opentelemetry_distro import start_tracing\nfrom opentelemetry import trace\n\n# 1. Initialize the AWS OpenTelemetry Distro.\n# This sets up the global trace provider, resource detectors, and default exporters\n# based primarily on environment variables (e.g., OTEL_EXPORTER_OTLP_ENDPOINT).\n# In AWS Lambda or ECS/EC2 with the ADOT Collector, these environment variables are often pre-configured.\nstart_tracing()\n\n# 2. Get a tracer and create a span.\ntracer = trace.get_tracer(\"my-application-tracer\")\n\nwith tracer.start_as_current_span(\"my-aws-operation\") as span:\n    span.set_attribute(\"service.name\", \"my-app\")\n    span.set_attribute(\"aws.region\", os.environ.get(\"AWS_REGION\", \"us-east-1\"))\n    print(\"Performing some instrumented work with AWS OpenTelemetry Distro...\")\n    # Simulate some work\n    import time\n    time.sleep(0.1)\n\nprint(\"Application finished. Spans were sent to the configured OTLP endpoint.\")\nprint(\"To see output, ensure OTEL_EXPORTER_OTLP_ENDPOINT is set (e.g., to a local ADOT Collector or X-Ray daemon).\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to `aws-opentelemetry-distro>=0.14.0` or revert to a stable older version.","message":"Version `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.","severity":"breaking","affected_versions":"0.13.0"},{"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).","message":"The 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `DJANGO_SETTINGS_MODULE` is correctly defined in your environment when instrumenting Django applications.","message":"When 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.","severity":"gotcha","affected_versions":">=0.14.1"},{"fix":"Review the release notes for both `aws-opentelemetry-distro` and the bundled OpenTelemetry Python components when upgrading major or minor versions.","message":"Updating `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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}