OpenTelemetry Python - AWS SDK Extension


pip install opentelemetry-sdk-extension-aws

AWS X-Ray IDs Generator

The AWS X-Ray IDs Generator provides a custom IDs Generator to make traces generated using the OpenTelemetry SDKs TracerProvider compatible with the AWS X-Ray backend service trace ID format.


Configure the OTel SDK TracerProvider with the provided custom IDs Generator to make spans compatible with the AWS X-Ray backend tracing service.

Install the OpenTelemetry SDK package.

pip install opentelemetry-sdk

Next, use the provided AwsXRayIdGenerator to initialize the TracerProvider.

import opentelemetry.trace as trace
from import AwsXRayIdGenerator
from opentelemetry.sdk.trace import TracerProvider




Bases: opentelemetry.sdk.trace.id_generator.IdGenerator

Generates tracing IDs compatible with the AWS X-Ray tracing service. In the X-Ray system, the first 32 bits of the TraceId are the Unix epoch time in seconds. Since spans (AWS calls them segments) with an embedded timestamp more than 30 days ago are rejected, a purely random TraceId risks being rejected by the service.


random_id_generator = <opentelemetry.sdk.trace.id_generator.RandomIdGenerator object>

Get a new span ID.

Return type



A 64-bit int for use as a span ID

static generate_trace_id()[source]

Get a new trace ID.

Implementations should at least make the 64 least significant bits uniformly random. Samplers like the TraceIdRatioBased sampler rely on this randomness to make sampling decisions.

See the specification on TraceIdRatioBased.

Return type



A 128-bit int for use as a trace ID

AWS X-Ray Propagator

The AWS X-Ray Propagator provides a propagator that when used, adds a trace header to outgoing traces that is compatible with the AWS X-Ray backend service. This allows the trace context to be propagated when a trace spans multiple AWS services.

The same propagator setup is used to extract a context sent by external systems so that child span have the correct parent context.

NOTE: Because the parent context parsed from the X-Amzn-Trace-Id header assumes the context is _not_ sampled by default, users should make sure to add Sampled=1 to their X-Amzn-Trace-Id headers so that the child spans are sampled.


Use the provided AWS X-Ray Propagator to inject the necessary context into traces sent to external systems.

This can be done by either setting this environment variable:

export OTEL_PROPAGATORS = xray

Or by setting this propagator in your instrumented application:

from opentelemetry.propagate import set_global_textmap
from import AwsXRayFormat




Bases: Exception


Bases: opentelemetry.propagators.textmap.TextMapPropagator

Propagator for the AWS X-Ray Trace Header propagation protocol.


extract(carrier, context=None, getter=<opentelemetry.propagators.textmap.DefaultGetter object>)[source]

Create a Context from values in the carrier.

The extract function should retrieve values from the carrier object using getter, and use values to populate a Context value and return it.

  • getter (Getter) – a function that can retrieve zero or more values from the carrier. In the case that the value does not exist, return an empty list.

  • carrier (~CarrierT) – and object which contains values that are used to construct a Context. This object must be paired with an appropriate getter which understands how to extract a value from it.

  • context (Optional[Context]) – an optional Context to use. Defaults to root context if not set.

Return type



A Context with configuration found in the carrier.

inject(carrier, context=None, setter=<opentelemetry.propagators.textmap.DefaultSetter object>)[source]

Inject values from a Context into a carrier.

inject enables the propagation of values into HTTP clients or other objects which perform an HTTP request. Implementations should use the Setter ‘s set method to set values on the carrier.

  • carrier (~CarrierT) – An object that a place to define HTTP headers. Should be paired with setter, which should know how to set header values on the carrier.

  • context (Optional[Context]) – an optional Context to use. Defaults to current context if not set.

  • setter (Setter) – An optional Setter object that can set values on the carrier.

Return type


property fields

Returns a set with the fields set in inject.