{"id":2170,"library":"opentelemetry-sdk-extension-aws","title":"AWS SDK Extension for OpenTelemetry","description":"The opentelemetry-sdk-extension-aws library, currently at version 2.1.0, provides components to configure the OpenTelemetry SDK for Python, primarily enabling compatibility with AWS X-Ray tracing. It offers custom ID generators for X-Ray compatible trace IDs and AWS resource detectors to automatically enrich telemetry data with AWS-specific metadata. The project is actively maintained as part of the wider opentelemetry-python-contrib monorepo and follows its release cadence.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","aws","sdk","x-ray","observability","tracing","cloud"],"install":[{"cmd":"pip install opentelemetry-sdk-extension-aws opentelemetry-sdk opentelemetry-propagator-aws-xray","lang":"bash","label":"Install with core SDK and X-Ray propagator"}],"dependencies":[{"reason":"Provides the core OpenTelemetry SDK functionalities and interfaces.","package":"opentelemetry-sdk","optional":false},{"reason":"Strongly recommended for correct trace context propagation across AWS services like SQS and SNS.","package":"opentelemetry-propagator-aws-xray","optional":false}],"imports":[{"symbol":"AwsXRayIdGenerator","correct":"from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator"},{"note":"The Ec2ResourceDetector is located in a submodule specific to resource detectors.","wrong":"from opentelemetry.sdk.extension.aws.resource import Ec2ResourceDetector","symbol":"Ec2ResourceDetector","correct":"from opentelemetry.sdk.extension.aws.resource.ec2 import Ec2ResourceDetector"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator\nfrom opentelemetry.sdk.extension.aws.resource.ec2 import Ec2ResourceDetector\n\n# 1. Configure the TracerProvider with the X-Ray ID Generator for trace ID compatibility\n# This is crucial for traces to be accepted and correlated correctly by AWS X-Ray.\ntracer_provider = TracerProvider(id_generator=AwsXRayIdGenerator())\ntrace.set_tracer_provider(tracer_provider)\n\n# 2. Detect AWS specific resource attributes (e.g., EC2 instance metadata)\n# For a local runnable example, we use a basic resource and merge with detected EC2 attributes.\n# In an actual EC2 environment, Ec2ResourceDetector.detect() would populate real metadata.\nresource = Resource.create({\"service.name\": os.environ.get(\"OTEL_SERVICE_NAME\", \"my-aws-app\")})\n# Attempt to detect EC2 resources; if not on EC2, this will yield an empty resource.\n# The merge operation combines the service name with any detected AWS resource attributes.\ntracer_provider.resource = resource.merge(Ec2ResourceDetector().detect())\n\n# 3. Configure a simple span processor and console exporter for demonstration\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\ntracer_provider.add_span_processor(span_processor)\n\n# 4. Get a tracer and create some spans\ntracer = trace.get_tracer(__name__)\n\nwith tracer.start_as_current_span(\"my-aws-operation\"):\n    print(\"Performing an operation traced with OpenTelemetry and AWS X-Ray compatible IDs.\")\n    with tracer.start_as_current_span(\"sub-operation\"):\n        print(\"This is a sub-operation within the main task.\")\n\nprint(\"OpenTelemetry with AWS X-Ray compatibility and resource detection configured.\")\nprint(\"Check console output for example spans.\")\n","lang":"python","description":"This quickstart demonstrates how to configure the OpenTelemetry Python SDK using `opentelemetry-sdk-extension-aws`. It initializes a `TracerProvider` with `AwsXRayIdGenerator` to ensure trace ID compatibility with AWS X-Ray and includes an `Ec2ResourceDetector` to automatically add AWS EC2 metadata to your traces. Spans are then exported to the console."},"warnings":[{"fix":"Initialize your TracerProvider with `id_generator=AwsXRayIdGenerator()`.","message":"OpenTelemetry's default trace ID generation is not compatible with AWS X-Ray. To ensure traces can be ingested and properly correlated in X-Ray, you MUST configure the `AwsXRayIdGenerator` from this package when initializing your `TracerProvider`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `opentelemetry-propagator-aws-xray` and configure it as a global propagator: `from opentelemetry.propagate import set_global_textmap;\nfrom opentelemetry.propagators.aws.xray import AwsXRayPropagator;\nset_global_textmap(AwsXRayPropagator())`.","message":"For correct trace context propagation across AWS services (e.g., SQS, SNS, Lambda), the `opentelemetry-propagator-aws-xray` package is strongly recommended. Without it, trace context may not propagate correctly, leading to broken traces across service boundaries.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Adopt `opentelemetry-sdk-extension-aws` and other OpenTelemetry components for new tracing implementations in AWS environments.","message":"AWS is transitioning its native X-Ray SDKs and Daemon to maintenance mode, focusing new feature development on OpenTelemetry-based solutions. While existing X-Ray SDKs will continue to function, new development or migrations should leverage OpenTelemetry and this extension for better future compatibility and access to new features.","severity":"deprecated","affected_versions":"All versions"},{"fix":"Review the documentation for each specific resource detector to understand its requirements and ensure your AWS environment is configured accordingly (e.g., IAM roles, environment variables).","message":"AWS resource detectors (e.g., `Ec2ResourceDetector`, `EcsResourceDetector`) included in this package rely on specific environment variables, IAM permissions, or runtime metadata services to automatically detect and populate resource attributes. Ensure your application's deployment environment provides the necessary access for accurate resource attribution.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}