0
# OpenTelemetry SDK Extension for AWS
1

2
A comprehensive OpenTelemetry SDK extension providing AWS X-Ray tracing compatibility and automatic resource attribute detection for AWS services. This package bridges OpenTelemetry distributed tracing with AWS X-Ray by generating compatible trace IDs and automatically populating resource attributes when running on AWS infrastructure.
3

4
## Package Information
5

6
- **Package Name**: opentelemetry-sdk-extension-aws
7
- **Language**: Python
8
- **Installation**: `pip install opentelemetry-sdk-extension-aws`
9

10
## Core Imports
11

12
For X-Ray ID generation:
13

14
```python
15
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
16
```
17

18
For AWS resource detection:
19

20
```python
21
from opentelemetry.sdk.extension.aws.resource.ec2 import AwsEc2ResourceDetector
22
from opentelemetry.sdk.extension.aws.resource.ecs import AwsEcsResourceDetector
23
from opentelemetry.sdk.extension.aws.resource.eks import AwsEksResourceDetector  
24
from opentelemetry.sdk.extension.aws.resource.beanstalk import AwsBeanstalkResourceDetector
25
from opentelemetry.sdk.extension.aws.resource._lambda import AwsLambdaResourceDetector
26
```
27

28
## Basic Usage
29

30
### X-Ray Compatible Tracing
31

32
```python
33
import opentelemetry.trace as trace
34
from opentelemetry.sdk.extension.aws.trace import AwsXRayIdGenerator
35
from opentelemetry.sdk.trace import TracerProvider
36

37
# Configure TracerProvider with X-Ray compatible ID generator
38
trace.set_tracer_provider(
39
    TracerProvider(id_generator=AwsXRayIdGenerator())
40
)
41

42
# Use tracing as normal - IDs will be X-Ray compatible
43
tracer = trace.get_tracer(__name__)
44
with tracer.start_as_current_span("operation"):
45
    # Your application code here
46
    pass
47
```
48

49
### Automatic Resource Detection
50

51
```python
52
import opentelemetry.trace as trace
53
from opentelemetry.sdk.trace import TracerProvider
54
from opentelemetry.sdk.extension.aws.resource.ec2 import AwsEc2ResourceDetector
55
from opentelemetry.sdk.resources import get_aggregated_resources
56

57
# Configure TracerProvider with automatic AWS resource detection
58
trace.set_tracer_provider(
59
    TracerProvider(
60
        resource=get_aggregated_resources([
61
            AwsEc2ResourceDetector(),
62
        ])
63
    )
64
)
65
```
66

67
## Architecture
68

69
The extension consists of two main components:
70

71
- **X-Ray ID Generator**: Produces trace and span IDs compatible with AWS X-Ray's format requirements, embedding Unix timestamps in trace IDs to ensure acceptance by X-Ray backend services
72
- **Resource Detectors**: Automatically detect and populate OpenTelemetry resource attributes when running on various AWS services (EC2, ECS, EKS, Lambda, Beanstalk)
73

74
Both components integrate seamlessly with OpenTelemetry's standard TracerProvider configuration, enabling applications to benefit from X-Ray compatibility and automatic resource detection without code changes beyond initial setup.
75

76
## Capabilities
77

78
### X-Ray ID Generation
79

80
Generates OpenTelemetry trace and span IDs 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.
81

82
```python { .api }
83
class AwsXRayIdGenerator:
84
    def generate_span_id(self) -> int: ...
85
    def generate_trace_id(self) -> int: ...
86
```
87

88
[X-Ray ID Generation](./xray-id-generator.md)
89

90
### AWS Resource Detection
91

92
Automatically detects and populates resource attributes when running on AWS services. Each detector focuses on a specific AWS service and extracts relevant metadata to enhance observability.
93

94
```python { .api }
95
class AwsEc2ResourceDetector:
96
    def detect(self) -> Resource: ...
97

98
class AwsEcsResourceDetector:
99
    def detect(self) -> Resource: ...
100

101
class AwsEksResourceDetector:
102
    def detect(self) -> Resource: ...
103

104
class AwsBeanstalkResourceDetector:
105
    def detect(self) -> Resource: ...
106

107
class AwsLambdaResourceDetector:
108
    def detect(self) -> Resource: ...
109
```
110

111
[AWS Resource Detection](./resource-detectors.md)
112

113
## Types
114

115
```python { .api }
116
from opentelemetry.sdk.resources import Resource
117
from opentelemetry.sdk.trace.id_generator import IdGenerator
118

119
# All resource detectors extend this base class
120
class ResourceDetector:
121
    raise_on_error: bool
122
    def detect(self) -> Resource: ...
123

124
# ID generator base class
125
class IdGenerator:
126
    def generate_span_id(self) -> int: ...
127
    def generate_trace_id(self) -> int: ...
128
```