tessl/pypi-opentelemetry-sdk-extension-aws
AWS SDK extension for OpenTelemetry providing X-Ray ID generation and AWS resource detection
—
xray-id-generator.mddocs/
X-Ray ID Generation
Provides custom ID generation for OpenTelemetry traces that are compatible with AWS X-Ray's format requirements. X-Ray requires trace IDs to embed Unix timestamps in the first 32 bits to ensure spans are not rejected by the service.
Capabilities
AwsXRayIdGenerator
Generates tracing IDs compatible with the AWS X-Ray tracing service. The X-Ray system requires the first 32 bits of the trace ID to be the Unix epoch time in seconds. Since spans with an embedded timestamp more than 30 days ago are rejected, a purely random trace ID risks being rejected by the service.
class AwsXRayIdGenerator(IdGenerator):
"""
Generates tracing IDs compatible with the AWS X-Ray tracing service.
Attributes:
random_id_generator: RandomIdGenerator instance for generating span IDs
"""
random_id_generator: RandomIdGenerator
def generate_span_id(self) -> int:
"""
Generate a random span ID.
Returns:
int: Random 64-bit span ID
"""
def generate_trace_id(self) -> int:
"""
Generate X-Ray compatible trace ID with embedded timestamp.
The trace ID format embeds the current Unix timestamp in the first
32 bits followed by 96 bits of random data.
Returns:
int: 128-bit trace ID compatible with X-Ray format
"""Usage Examples
Basic Integration
import opentelemetry.trace as trace
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
from opentelemetry.sdk.trace import TracerProvider
# Configure TracerProvider with X-Ray ID generator
trace.set_tracer_provider(
TracerProvider(id_generator=AwsXRayIdGenerator())
)
# Use tracing normally - all trace IDs will be X-Ray compatible
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("my-operation") as span:
span.set_attribute("operation.type", "data-processing")
# Your application code hereCombined with Resource Detection
import opentelemetry.trace as trace
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
from opentelemetry.sdk.extension.aws.resource.ec2 import AwsEc2ResourceDetector
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.resources import get_aggregated_resources
# Configure TracerProvider with both X-Ray IDs and resource detection
trace.set_tracer_provider(
TracerProvider(
id_generator=AwsXRayIdGenerator(),
resource=get_aggregated_resources([
AwsEc2ResourceDetector(),
])
)
)Technical Details
X-Ray Trace ID Format
The X-Ray trace ID format is a 128-bit identifier structured as:
- First 32 bits: Unix timestamp in seconds
- Remaining 96 bits: Random identifier
This format ensures that traces are not rejected by X-Ray for being too old (older than 30 days) while maintaining compatibility with OpenTelemetry's trace ID requirements.
Entry Point Configuration
The package provides an entry point for automatic discovery:
[project.entry-points.opentelemetry_id_generator]
xray = "opentelemetry.sdk.extension.aws.trace.aws_xray_id_generator:AwsXRayIdGenerator"This allows the ID generator to be configured via environment variables or configuration files without direct code references.
Types
from opentelemetry.sdk.trace.id_generator import IdGenerator, RandomIdGenerator
class IdGenerator:
"""Base class for ID generators."""
def generate_span_id(self) -> int: ...
def generate_trace_id(self) -> int: ...
class RandomIdGenerator(IdGenerator):
"""Default random ID generator."""
def generate_span_id(self) -> int: ...
def generate_trace_id(self) -> int: ...Install with Tessl CLI
npx tessl i tessl/pypi-opentelemetry-sdk-extension-aws