OpenTelemetry Python - AWS SDK Extension

Installation

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.

Usage

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 opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
from opentelemetry.sdk.trace import TracerProvider

trace.set_tracer_provider(
    TracerProvider(id_generator=AwsXRayIdGenerator())
)

API

class opentelemetry.sdk.extension.aws.trace.aws_xray_id_generator.AwsXRayIdGenerator[source]

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.

See: https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids

random_id_generator = <opentelemetry.sdk.trace.id_generator.RandomIdGenerator object>
generate_span_id()[source]

Get a new span ID.

Return type

int

Returns

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

int

Returns

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.

Usage

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 opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format import AwsXRayFormat

set_global_textmap(AwsXRayFormat())

API

exception opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format.AwsParseTraceHeaderError(message)[source]

Bases: Exception

class opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format.AwsXRayFormat[source]

Bases: opentelemetry.propagators.textmap.TextMapPropagator

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

See: https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader

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.

Parameters
  • 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

Context

Returns

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.

Parameters
  • 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

None

property fields

Returns a set with the fields set in inject.