AWS OpenTelemetry Python Distro

Warnings

• breaking 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.
  Fix: Upgrade to `aws-opentelemetry-distro>=0.14.0` or revert to a stable older version.
• gotcha 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.
  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).
• gotcha 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.
  Fix: Ensure `DJANGO_SETTINGS_MODULE` is correctly defined in your environment when instrumenting Django applications.
• gotcha 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.
  Fix: Review the release notes for both `aws-opentelemetry-distro` and the bundled OpenTelemetry Python components when upgrading major or minor versions.

Install

• pip install aws-opentelemetry-distro Install core distro
• pip install aws-opentelemetry-distro[all] Install with all common instrumentations (e.g., boto3, flask, django)

Imports

• start_tracing

  from aws_opentelemetry_distro import start_tracing

  This function initializes the OpenTelemetry environment with AWS-specific configurations.
• AwsResourceDetector

  from aws_opentelemetry_distro.aws_resource_detector import AwsResourceDetector

  Used for advanced manual resource detection beyond what `start_tracing` provides by default.

Quickstart

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).")