0
# X-Ray ID Generation
1

2
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.
3

4
## Capabilities
5

6
### AwsXRayIdGenerator
7

8
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.
9

10
```python { .api }
11
class AwsXRayIdGenerator(IdGenerator):
12
    """
13
    Generates tracing IDs compatible with the AWS X-Ray tracing service.
14
    
15
    Attributes:
16
        random_id_generator: RandomIdGenerator instance for generating span IDs
17
    """
18
    
19
    random_id_generator: RandomIdGenerator
20
    
21
    def generate_span_id(self) -> int:
22
        """
23
        Generate a random span ID.
24
        
25
        Returns:
26
            int: Random 64-bit span ID
27
        """
28
    
29
    def generate_trace_id(self) -> int:
30
        """
31
        Generate X-Ray compatible trace ID with embedded timestamp.
32
        
33
        The trace ID format embeds the current Unix timestamp in the first
34
        32 bits followed by 96 bits of random data.
35
        
36
        Returns:
37
            int: 128-bit trace ID compatible with X-Ray format
38
        """
39
```
40

41
### Usage Examples
42

43
#### Basic Integration
44

45
```python
46
import opentelemetry.trace as trace
47
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
48
from opentelemetry.sdk.trace import TracerProvider
49

50
# Configure TracerProvider with X-Ray ID generator
51
trace.set_tracer_provider(
52
    TracerProvider(id_generator=AwsXRayIdGenerator())
53
)
54

55
# Use tracing normally - all trace IDs will be X-Ray compatible
56
tracer = trace.get_tracer(__name__)
57
with tracer.start_as_current_span("my-operation") as span:
58
    span.set_attribute("operation.type", "data-processing")
59
    # Your application code here
60
```
61

62
#### Combined with Resource Detection
63

64
```python
65
import opentelemetry.trace as trace
66
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
67
from opentelemetry.sdk.extension.aws.resource.ec2 import AwsEc2ResourceDetector
68
from opentelemetry.sdk.trace import TracerProvider
69
from opentelemetry.sdk.resources import get_aggregated_resources
70

71
# Configure TracerProvider with both X-Ray IDs and resource detection
72
trace.set_tracer_provider(
73
    TracerProvider(
74
        id_generator=AwsXRayIdGenerator(),
75
        resource=get_aggregated_resources([
76
            AwsEc2ResourceDetector(),
77
        ])
78
    )
79
)
80
```
81

82
## Technical Details
83

84
### X-Ray Trace ID Format
85

86
The X-Ray trace ID format is a 128-bit identifier structured as:
87
- **First 32 bits**: Unix timestamp in seconds
88
- **Remaining 96 bits**: Random identifier
89

90
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.
91

92
### Entry Point Configuration
93

94
The package provides an entry point for automatic discovery:
95

96
```
97
[project.entry-points.opentelemetry_id_generator]
98
xray = "opentelemetry.sdk.extension.aws.trace.aws_xray_id_generator:AwsXRayIdGenerator"
99
```
100

101
This allows the ID generator to be configured via environment variables or configuration files without direct code references.
102

103
## Types
104

105
```python { .api }
106
from opentelemetry.sdk.trace.id_generator import IdGenerator, RandomIdGenerator
107

108
class IdGenerator:
109
    """Base class for ID generators."""
110
    def generate_span_id(self) -> int: ...
111
    def generate_trace_id(self) -> int: ...
112

113
class RandomIdGenerator(IdGenerator):
114
    """Default random ID generator."""
115
    def generate_span_id(self) -> int: ...
116
    def generate_trace_id(self) -> int: ...
117
```