{"id":1609,"library":"opentelemetry-propagator-aws-xray","title":"AWS X-Ray Propagator for OpenTelemetry","description":"The `opentelemetry-propagator-aws-xray` library provides an OpenTelemetry `TextMapPropagator` that enables propagation of trace context in AWS X-Ray compatible headers. It allows OpenTelemetry Python applications to integrate with existing AWS X-Ray traces by injecting and extracting the `X-Amzn-Trace-Id` header. The current version is 1.0.2, and it follows the release cadence of the broader `opentelemetry-python-contrib` project, which typically sees updates aligned with core OpenTelemetry Python releases.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/propagator/opentelemetry-propagator-aws-xray","tags":["observability","opentelemetry","aws","xray","tracing","propagator","distributed-tracing"],"install":[{"cmd":"pip install opentelemetry-propagator-aws-xray","lang":"bash","label":"Install package"}],"dependencies":[],"imports":[{"symbol":"AWSXRayPropagator","correct":"from opentelemetry.propagators.aws.xray import AWSXRayPropagator"},{"note":"Used to generate X-Ray compatible trace IDs for new traces.","symbol":"AwsXRayIdGenerator","correct":"from opentelemetry.sdk.trace.id_generator import AwsXRayIdGenerator"}],"quickstart":{"code":"from opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.sdk.trace.id_generator import AwsXRayIdGenerator\nfrom opentelemetry.propagators.aws.xray import AWSXRayPropagator\nfrom opentelemetry.propagate import set_global_textmap_propagator\nfrom opentelemetry.trace import get_tracer_provider, set_tracer_provider, get_tracer, get_current_span\n\n# 1. Configure TracerProvider with AwsXRayIdGenerator\n# This ensures new traces generated by this application use AWS X-Ray compatible IDs.\nprovider = TracerProvider(id_generator=AwsXRayIdGenerator())\n\n# For demonstration, we'll use a ConsoleSpanExporter.\n# In a real application, you'd use an OTLPSpanExporter or similar.\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\nset_tracer_provider(provider)\n\n# 2. Set the global propagator to AWSXRayPropagator\n# This enables automatic injection/extraction of X-Ray headers.\nset_global_textmap_propagator(AWSXRayPropagator())\n\n# 3. Obtain a tracer and create spans\ntracer = get_tracer(__name__)\n\nprint(\"\\n--- Creating an initial span and injecting context ---\")\nwith tracer.start_as_current_span(\"my-xray-root-span\") as root_span:\n    print(f\"Root Span ID: {root_span.context.span_id:x}\")\n    print(f\"Root Trace ID: {root_span.context.trace_id:x}\")\n\n    # Simulate injecting trace context into outgoing headers\n    carrier = {}\n    AWSXRayPropagator().inject(carrier)\n    print(\"Injected headers (simulating HTTP request outgoing):\", carrier)\n\nprint(\"\\n--- Simulating a new request receiving injected headers ---\")\n# Simulate receiving injected headers in a new context\n# We start a new span, but its context will be derived from the extracted headers.\n\n# Let's assume 'carrier' contains the headers from the previous step\nreceived_carrier = carrier.copy()\n\n# When a new span is started, OpenTelemetry automatically extracts context\n# from the global propagator if it's available in the current context (e.g., from a request).\n# For this example, we manually extract and then demonstrate a child span.\n\n# Manually extract context for clarity, though it's often done automatically by instrumentations.\nextracted_context = AWSXRayPropagator().extract(received_carrier)\n\nwith tracer.start_as_current_span(\"my-xray-child-span\", context=extracted_context) as child_span:\n    print(f\"Child Span ID: {child_span.context.span_id:x}\")\n    print(f\"Child Trace ID: {child_span.context.trace_id:x}\")\n    print(f\"Is child span linked to root? {root_span.context.trace_id == child_span.context.trace_id}\")\n\n    # Further nested span\n    with tracer.start_as_current_span(\"nested-operation\"):\n        print(\"  Inside nested operation.\")\n\nprint(\"\\n--- End of quickstart ---\")","lang":"python","description":"This quickstart demonstrates how to configure OpenTelemetry to use the AWS X-Ray Propagator and `AwsXRayIdGenerator`. It shows how to initialize the `TracerProvider` for X-Ray compatible trace IDs, set the global `AWSXRayPropagator`, and simulate injecting and extracting X-Ray trace context for distributed tracing."},"warnings":[{"fix":"Ensure `provider = TracerProvider(id_generator=AwsXRayIdGenerator())` is used when setting up your tracing.","message":"The `AWSXRayPropagator` primarily handles the `X-Amzn-Trace-Id` header format. For OpenTelemetry to generate trace IDs that are natively compatible with AWS X-Ray (i.e., epoch time + 24-byte unique identifier), you *must* configure your `TracerProvider` with `AwsXRayIdGenerator`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `OTEL_PROPAGATORS=\"tracecontext,baggage,awsxray\"` (or similar, including other desired propagators) in your environment to enable it without programmatic setup.","message":"If you are relying on automatic instrumentation or environment variables for configuration, ensure the `OTEL_PROPAGATORS` environment variable is set correctly. The value `awsxray` needs to be included.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `AwsXRayIdGenerator` for new traces to ensure native X-Ray IDs are generated. If traces originate outside your OTel application (e.g., from an AWS service), the propagator will extract the X-Ray ID and continue the trace correctly.","message":"AWS X-Ray trace IDs have a different format (version, timestamp, random ID) compared to W3C Trace Context trace IDs (16-byte random ID). While `AWSXRayPropagator` translates between these formats when headers are exchanged, ensure your entire tracing setup (ID generation, sampling, exporter) is compatible with X-Ray if deep integration is required.","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"}