0
# AWS X-Ray SDK for Python
1

2
The AWS X-Ray SDK for Python enables Python developers to record and emit information from within their applications to the AWS X-Ray service for distributed tracing. It provides comprehensive distributed tracing capabilities for monitoring and troubleshooting complex distributed Python applications in AWS environments.
3

4
## Package Information
5

6
- **Package Name**: aws-xray-sdk
7
- **Language**: Python
8
- **Installation**: `pip install aws-xray-sdk`
9
- **Python Support**: 3.7, 3.8, 3.9, 3.10, 3.11
10
- **Dependencies**: `wrapt`, `botocore>=1.11.3`
11

12
## Core Imports
13

14
```python
15
from aws_xray_sdk.core import xray_recorder
16
from aws_xray_sdk.core import patch, patch_all
17
from typing import Union
18
```
19

20
For configuration:
21
```python
22
from aws_xray_sdk import global_sdk_config
23
```
24

25
For model classes:
26
```python
27
from aws_xray_sdk.core.models.segment import Segment
28
from aws_xray_sdk.core.models.subsegment import Subsegment
29
from aws_xray_sdk.core.models.trace_header import TraceHeader
30
```
31

32
## Basic Usage
33

34
```python
35
from aws_xray_sdk.core import xray_recorder, patch_all
36

37
# Configure X-Ray recorder
38
xray_recorder.configure(
39
    sampling=False,
40
    context_missing='LOG_ERROR',
41
    plugins=('EC2Plugin', 'ECSPlugin'),
42
    daemon_address='127.0.0.1:2000',
43
    dynamic_naming='*mysite.com*'
44
)
45

46
# Patch all supported libraries for automatic instrumentation
47
patch_all()
48

49
# Use context managers for tracing
50
with xray_recorder.in_segment('my-application') as segment:
51
    segment.put_metadata('key', {'data': 'value'})
52
    
53
    with xray_recorder.in_subsegment('database-operation') as subsegment:
54
        subsegment.put_annotation('table', 'users')
55
        # Your database operation here
56

57
# Use decorators for function tracing
58
@xray_recorder.capture('process-data')
59
def process_data(data):
60
    # Your function logic here
61
    return processed_data
62
```
63

64
## Architecture
65

66
The AWS X-Ray SDK follows a hierarchical tracing model:
67

68
- **Segments**: Top-level traces representing requests or operations in your application
69
- **Subsegments**: Nested traces for downstream calls, database queries, or function calls
70
- **Annotations**: Key-value pairs that are indexed and searchable in the X-Ray console
71
- **Metadata**: Additional context data that provides debugging information
72
- **Sampling**: Configurable rules to control trace collection volume and costs
73

74
The SDK provides both synchronous and asynchronous recorders, automatic instrumentation through patching, and extensive integration with Python web frameworks and AWS services.
75

76
## Capabilities
77

78
### Core Recording
79

80
Primary tracing functionality for creating and managing segments and subsegments. Includes synchronous and asynchronous recorders, context managers, decorators, and manual trace management.
81

82
```python { .api }
83
# Global recorder instance
84
xray_recorder: AsyncAWSXRayRecorder
85

86
# Context managers
87
def in_segment(name: str, **segment_kwargs) -> SegmentContextManager: ...
88
def in_subsegment(name: str, **subsegment_kwargs) -> SubsegmentContextManager: ...
89
def in_segment_async(name: str, **segment_kwargs) -> AsyncSegmentContextManager: ...
90
def in_subsegment_async(name: str, **subsegment_kwargs) -> AsyncSubsegmentContextManager: ...
91

92
# Decorators
93
def capture(name: str) -> Callable: ...
94
def capture_async(name: str) -> Callable: ...
95

96
# Manual management - Segments
97
def begin_segment(name: str = None, traceid: str = None, parent_id: str = None, sampling: int = None) -> Segment: ...
98
def end_segment(end_time: float = None) -> None: ...
99
def current_segment() -> Segment: ...
100

101
# Manual management - Subsegments
102
def begin_subsegment(name: str, namespace: str = 'local') -> Subsegment: ...
103
def begin_subsegment_without_sampling(name: str) -> Subsegment: ...
104
def end_subsegment(end_time: float = None) -> None: ...
105
def current_subsegment() -> Subsegment: ...
106

107
# Trace entity management
108
def get_trace_entity() -> Union[Segment, Subsegment]: ...
109
def set_trace_entity(trace_entity: Union[Segment, Subsegment]) -> None: ...
110
def clear_trace_entities() -> None: ...
111

112
# Streaming
113
def stream_subsegments() -> None: ...
114
```
115

116
[Core Recording](./core-recording.md)
117

118
### Library Patching
119

120
Automatic instrumentation for popular Python libraries and frameworks. Provides seamless tracing integration without code changes for supported libraries.
121

122
```python { .api }
123
def patch(modules_to_patch: tuple, raise_errors: bool = True, ignore_module_patterns: list = None) -> None: ...
124
def patch_all(double_patch: bool = False) -> None: ...
125
```
126

127
**Supported Libraries**: aiobotocore, botocore, pynamodb, requests, sqlite3, mysql, httplib, pymongo, pymysql, psycopg2, pg8000, sqlalchemy_core, httpx
128

129
[Library Patching](./library-patching.md)
130

131
### Annotations and Metadata
132

133
Data attachment capabilities for enriching traces with searchable annotations and debugging metadata. Annotations are indexed for filtering and searching in the X-Ray console.
134

135
```python { .api }
136
def put_annotation(key: str, value: str) -> None: ...
137
def put_metadata(key: str, value: Any, namespace: str = 'default') -> None: ...
138
def is_sampled() -> bool: ...
139
```
140

141
[Annotations and Metadata](./annotations-metadata.md)
142

143
### Web Framework Integration
144

145
Middleware and integration components for popular Python web frameworks including Django, Flask, Bottle, and aiohttp. Provides automatic request tracing and HTTP metadata collection.
146

147
```python { .api }
148
# Flask integration
149
class XRayMiddleware:
150
    def __init__(self, app: Flask, recorder: AWSXRayRecorder): ...
151

152
# Django integration
153
MIDDLEWARE = ['aws_xray_sdk.ext.django.middleware.XRayMiddleware']
154

155
# aiohttp integration
156
def middleware(request: web.Request, handler: Callable) -> web.Response: ...
157
```
158

159
[Web Framework Integration](./web-frameworks.md)
160

161
### AWS Service Integration
162

163
Specialized integration for AWS services through boto3/botocore patching. Automatically traces AWS API calls with service-specific metadata and error handling.
164

165
```python { .api }
166
# Automatic AWS service call tracing via patching
167
import boto3
168
from aws_xray_sdk.core import patch
169

170
patch(['botocore'])
171
client = boto3.client('dynamodb')  # Automatically traced
172
```
173

174
[AWS Service Integration](./aws-services.md)
175

176
### Database Integration
177

178
Database-specific tracing for SQL and NoSQL databases. Captures query information, connection details, and performance metrics while respecting security best practices.
179

180
```python { .api }
181
# SQLAlchemy integration
182
from aws_xray_sdk.ext.sqlalchemy.query import XRaySessionMaker
183
Session = XRaySessionMaker(bind=engine)
184

185
# Flask-SQLAlchemy integration  
186
from aws_xray_sdk.ext.flask_sqlalchemy.query import XRayFlaskSqlAlchemy
187
db = XRayFlaskSqlAlchemy(app)
188
```
189

190
[Database Integration](./database-integration.md)
191

192
### Configuration and Plugins
193

194
Recorder configuration options, plugin system for AWS metadata collection, and global SDK settings. Includes sampling configuration, context management, and environment-specific plugins.
195

196
```python { .api }
197
def configure(
198
    sampling: bool = None,
199
    plugins: tuple = None,
200
    context_missing: str = None,
201
    sampling_rules: str = None,
202
    daemon_address: str = None,
203
    service: str = None,
204
    context: object = None,
205
    emitter: object = None,
206
    streaming: bool = None,
207
    dynamic_naming: str = None,
208
    streaming_threshold: int = None,
209
    max_trace_back: int = None,
210
    sampler: object = None,
211
    stream_sql: bool = True
212
) -> None: ...
213

214
# Plugin classes
215
class EC2Plugin: ...
216
class ECSPlugin: ...
217
class ElasticBeanstalkPlugin: ...
218
```
219

220
[Configuration and Plugins](./configuration-plugins.md)
221

222
### Context Management
223

224
Trace entity context management for controlling the active segment or subsegment in multi-threaded environments and manual trace control scenarios.
225

226
```python { .api }
227
def get_trace_entity() -> Union[Segment, Subsegment]: ...
228
def set_trace_entity(trace_entity: Union[Segment, Subsegment]) -> None: ...
229
def clear_trace_entities() -> None: ...
230
```
231

232
*Detailed in [Core Recording](./core-recording.md) under Trace Entity Management section*
233

234
### Exception Handling
235

236
Exception and error tracking capabilities for adding fault, error, and throttle information to traces, along with detailed exception metadata.
237

238
```python { .api }
239
# Segment/Subsegment methods for error tracking
240
def add_exception(self, exception: Exception, stack: list = None, remote: bool = False) -> None: ...
241
def add_fault_flag(self) -> None: ...
242
def add_error_flag(self) -> None: ...
243
def add_throttle_flag(self) -> None: ...
244
def apply_status_code(self, status_code: int) -> None: ...
245
```
246

247
### HTTP Metadata
248

249
HTTP-specific metadata collection for web requests, including status codes, request/response headers, and URL information.
250

251
```python { .api }
252
# Segment/Subsegment methods for HTTP metadata
253
def put_http_meta(self, key: str, value: Any) -> None: ...
254
def set_user(self, user: str) -> None: ...
255
def apply_status_code(self, status_code: int) -> None: ...
256
```
257

258
[HTTP Utilities](./http-utilities.md)
259

260
### Sampling Control
261

262
Advanced sampling control and decision inspection for optimizing trace collection and performance.
263

264
```python { .api }
265
def is_sampled() -> bool: ...
266
def begin_subsegment_without_sampling(name: str) -> Subsegment: ...
267
# Sampling configuration via configure() method
268
```
269

270
[Sampling Control](./sampling.md)
271

272
## Types
273

274
```python { .api }
275
class AWSXRayRecorder:
276
    """Synchronous X-Ray recorder for managing traces."""
277
    
278
class AsyncAWSXRayRecorder(AWSXRayRecorder):
279
    """Asynchronous X-Ray recorder extending synchronous functionality."""
280

281
class Segment:
282
    """Represents a segment - compute resources running application logic."""
283
    def __init__(self, name: str, entityid: str = None, traceid: str = None, parent_id: str = None, sampled: bool = True): ...
284
    
285
    # Subsegment management
286
    def add_subsegment(self, subsegment: 'Subsegment') -> None: ...
287
    def remove_subsegment(self, subsegment: 'Subsegment') -> None: ...
288
    def increment(self) -> None: ...
289
    def decrement_ref_counter(self) -> None: ...
290
    def ready_to_send(self) -> bool: ...
291
    
292
    # Annotations and metadata
293
    def put_annotation(self, key: str, value: Any) -> None: ...
294
    def put_metadata(self, key: str, value: Any, namespace: str = 'default') -> None: ...
295
    def put_http_meta(self, key: str, value: Any) -> None: ...
296
    
297
    # Error handling
298
    def add_exception(self, exception: Exception, stack: list = None, remote: bool = False) -> None: ...
299
    def add_fault_flag(self) -> None: ...
300
    def add_error_flag(self) -> None: ...
301
    def add_throttle_flag(self) -> None: ...
302
    def apply_status_code(self, status_code: int) -> None: ...
303
    
304
    # AWS and service metadata
305
    def set_aws(self, aws_meta: dict) -> None: ...
306
    def set_service(self, service_info: dict) -> None: ...
307
    def set_user(self, user: str) -> None: ...
308
    
309
    # Serialization
310
    def serialize(self) -> str: ...
311
    def to_dict(self) -> dict: ...
312
    def close(self, end_time: float = None) -> None: ...
313

314
class Subsegment:
315
    """Represents a subsegment - granular timing and details about downstream calls."""
316
    def __init__(self, name: str, namespace: str = 'local', segment: Segment = None): ...
317
    
318
    # Subsegment management
319
    def add_subsegment(self, subsegment: 'Subsegment') -> None: ...
320
    def remove_subsegment(self, subsegment: 'Subsegment') -> None: ...
321
    
322
    # Annotations and metadata
323
    def put_annotation(self, key: str, value: Any) -> None: ...
324
    def put_metadata(self, key: str, value: Any, namespace: str = 'default') -> None: ...
325
    def put_http_meta(self, key: str, value: Any) -> None: ...
326
    def set_sql(self, sql: dict) -> None: ...
327
    
328
    # Error handling
329
    def add_exception(self, exception: Exception, stack: list = None, remote: bool = False) -> None: ...
330
    def add_fault_flag(self) -> None: ...
331
    def add_error_flag(self) -> None: ...
332
    def add_throttle_flag(self) -> None: ...
333
    def apply_status_code(self, status_code: int) -> None: ...
334
    
335
    # AWS metadata
336
    def set_aws(self, aws_meta: dict) -> None: ...
337
    
338
    # Serialization
339
    def serialize(self) -> str: ...
340
    def to_dict(self) -> dict: ...
341
    def close(self, end_time: float = None) -> None: ...
342

343
class TraceHeader:
344
    """Represents X-Ray trace header for HTTP request propagation."""
345
    def __init__(self, root: str = None, parent: str = None, sampled: int = None, data: str = None): ...
346
    @classmethod
347
    def from_header_str(cls, header: str) -> 'TraceHeader': ...
348
    def to_header_str(self) -> str: ...
349

350
class SDKConfig:
351
    """Global SDK configuration management."""
352
    @classmethod
353
    def sdk_enabled(cls) -> bool: ...
354
    @classmethod  
355
    def set_sdk_enabled(cls, value: bool) -> None: ...
356

357
# Context manager classes
358
class SegmentContextManager:
359
    """Context manager for segment lifecycle management."""
360
    def __enter__(self) -> Segment: ...
361
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
362

363
class SubsegmentContextManager:
364
    """Context manager for subsegment lifecycle management."""
365
    def __enter__(self) -> Subsegment: ...
366
    def __exit__(self, exc_type, exc_val, exc_tb) -> None: ...
367

368
class AsyncSegmentContextManager:
369
    """Async context manager for segment lifecycle management."""
370
    async def __aenter__(self) -> Segment: ...
371
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: ...
372

373
class AsyncSubsegmentContextManager:
374
    """Async context manager for subsegment lifecycle management."""
375
    async def __aenter__(self) -> Subsegment: ...
376
    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None: ...
377

378
# Dummy entities for unsampled traces
379
class DummySegment(Segment):
380
    """Dummy segment used when traces are not sampled."""
381
    pass
382

383
class DummySubsegment(Subsegment):
384
    """Dummy subsegment used when traces are not sampled."""
385
    pass
386
```