0
# Library Patching
1

2
Automatic instrumentation for popular Python libraries and frameworks. The patching system provides seamless tracing integration without requiring code changes for supported libraries, enabling comprehensive distributed tracing across your application stack.
3

4
## Capabilities
5

6
### Patch All Libraries
7

8
Automatically patch all supported libraries with a single function call.
9

10
```python { .api }
11
def patch_all(double_patch: bool = False) -> None:
12
    """
13
    Patch all supported libraries for X-Ray tracing.
14

15
    Args:
16
        double_patch (bool): Enable patching of indirect dependencies.
17
                           When True, patches libraries that other libraries depend on.
18

19
    Supported Libraries:
20
        - aiobotocore: Async AWS SDK
21
        - botocore: AWS SDK (boto3)
22
        - pynamodb: DynamoDB ORM
23
        - requests: HTTP library
24
        - sqlite3: SQLite database
25
        - mysql: MySQL database
26
        - httplib: Standard HTTP library
27
        - pymongo: MongoDB driver
28
        - pymysql: Pure Python MySQL driver
29
        - psycopg2: PostgreSQL adapter
30
        - pg8000: Pure Python PostgreSQL driver
31
        - sqlalchemy_core: SQLAlchemy Core
32
        - httpx: Modern async HTTP client
33
    """
34
```
35

36
### Selective Library Patching
37

38
Patch specific libraries for more granular control over instrumentation.
39

40
```python { .api }
41
def patch(
42
    modules_to_patch: tuple,
43
    raise_errors: bool = True,
44
    ignore_module_patterns: list = None
45
) -> None:
46
    """
47
    Patch specific modules for X-Ray tracing.
48

49
    Args:
50
        modules_to_patch (tuple): Tuple of module names to patch
51
        raise_errors (bool): Whether to raise errors if patching fails
52
        ignore_module_patterns (list): List of regex patterns for modules to ignore
53

54
    Raises:
55
        ImportError: If module cannot be imported and raise_errors is True
56
        Exception: If patching fails and raise_errors is True
57
    """
58
```
59

60
## Supported Libraries
61

62
### AWS Services
63

64
#### botocore (boto3)
65
Traces AWS service calls made through boto3 and botocore.
66

67
```python
68
from aws_xray_sdk.core import patch
69
import boto3
70

71
# Patch botocore for AWS service tracing
72
patch(['botocore'])
73

74
# All AWS calls are now automatically traced
75
dynamodb = boto3.resource('dynamodb')
76
table = dynamodb.Table('users')
77
response = table.get_item(Key={'id': '123'})  # Automatically traced
78
```
79

80
#### aiobotocore
81
Traces async AWS service calls made through aiobotocore.
82

83
```python
84
from aws_xray_sdk.core import patch
85
import aiobotocore.session
86

87
# Patch aiobotocore for async AWS service tracing
88
patch(['aiobotocore'])
89

90
# Async AWS calls are automatically traced
91
session = aiobotocore.session.get_session()
92
async with session.create_client('s3') as client:
93
    response = await client.list_buckets()  # Automatically traced
94
```
95

96
### HTTP Clients
97

98
#### requests
99
Traces HTTP requests made through the popular requests library.
100

101
```python
102
from aws_xray_sdk.core import patch
103
import requests
104

105
# Patch requests for HTTP tracing
106
patch(['requests'])
107

108
# HTTP requests are automatically traced
109
response = requests.get('https://api.example.com/data')  # Automatically traced
110
response = requests.post('https://api.example.com/users', json={'name': 'John'})  # Automatically traced
111
```
112

113
#### httplib
114
Traces HTTP requests made through Python's standard HTTP library.
115

116
```python
117
from aws_xray_sdk.core import patch
118
import http.client
119

120
# Patch httplib for HTTP tracing
121
patch(['httplib'])
122

123
# Standard library HTTP calls are traced
124
conn = http.client.HTTPSConnection('api.example.com')
125
conn.request('GET', '/data')
126
response = conn.getresponse()  # Automatically traced
127
```
128

129
#### HTTP Request Filtering
130

131
Control which HTTP requests are traced by adding hostname, URL, or subclass filters.
132

133
```python
134
from aws_xray_sdk.ext.httplib import add_ignored, reset_ignored
135

136
# Ignore requests to specific hostnames
137
add_ignored(hostname='test.myapp.com')
138

139
# Ignore requests with glob patterns
140
add_ignored(hostname='*.internal.com')
141

142
# Ignore specific URL paths
143
add_ignored(urls=['/health', '/metrics'])
144

145
# Ignore requests from specific HTTP client classes
146
add_ignored(subclass='botocore.awsrequest.AWSHTTPConnection')
147

148
# Combine multiple filters
149
add_ignored(hostname='api.example.com', urls=['/internal/*'])
150

151
# Reset all ignore patterns to defaults
152
reset_ignored()
153
```
154

155
#### httpx
156
Traces HTTP requests made through the modern httpx library.
157

158
```python
159
from aws_xray_sdk.core import patch
160
import httpx
161

162
# Patch httpx for HTTP tracing
163
patch(['httpx'])
164

165
# Both sync and async httpx calls are traced
166
response = httpx.get('https://api.example.com/data')  # Automatically traced
167

168
async with httpx.AsyncClient() as client:
169
    response = await client.get('https://api.example.com/data')  # Automatically traced
170
```
171

172
### Database Libraries
173

174
#### SQLite3
175
Traces SQLite database operations.
176

177
```python
178
from aws_xray_sdk.core import patch
179
import sqlite3
180

181
# Patch sqlite3 for database tracing
182
patch(['sqlite3'])
183

184
# SQLite operations are automatically traced
185
conn = sqlite3.connect('database.db')
186
cursor = conn.cursor()
187
cursor.execute('SELECT * FROM users')  # Automatically traced
188
```
189

190
#### MySQL Drivers
191
Traces MySQL database operations through various Python drivers.
192

193
```python
194
from aws_xray_sdk.core import patch
195

196
# Patch MySQL drivers
197
patch(['mysql'])  # MySQLdb
198
patch(['pymysql'])  # PyMySQL
199

200
import MySQLdb
201
# or
202
import pymysql
203

204
# Database operations are automatically traced
205
```
206

207
#### PostgreSQL Drivers
208
Traces PostgreSQL database operations.
209

210
```python
211
from aws_xray_sdk.core import patch
212

213
# Patch PostgreSQL drivers
214
patch(['psycopg2'])  # psycopg2
215
patch(['pg8000'])    # pg8000
216

217
import psycopg2
218
# or
219
import pg8000
220

221
# Database operations are automatically traced
222
```
223

224
#### MongoDB
225
Traces MongoDB operations through pymongo.
226

227
```python
228
from aws_xray_sdk.core import patch
229
import pymongo
230

231
# Patch pymongo for MongoDB tracing
232
patch(['pymongo'])
233

234
# MongoDB operations are automatically traced
235
client = pymongo.MongoClient()
236
db = client.mydb
237
collection = db.users
238
result = collection.find_one({'name': 'John'})  # Automatically traced
239
```
240

241
#### SQLAlchemy
242
Traces SQLAlchemy Core operations.
243

244
```python
245
from aws_xray_sdk.core import patch
246
from sqlalchemy import create_engine
247

248
# Patch SQLAlchemy Core
249
patch(['sqlalchemy_core'])
250

251
# SQLAlchemy operations are automatically traced
252
engine = create_engine('postgresql://user:pass@localhost/db')
253
result = engine.execute('SELECT * FROM users')  # Automatically traced
254
```
255

256
#### PynamoDB
257
Traces DynamoDB operations through PynamoDB ORM.
258

259
```python
260
from aws_xray_sdk.core import patch
261
from pynamodb.models import Model
262

263
# Patch PynamoDB
264
patch(['pynamodb'])
265

266
# PynamoDB operations are automatically traced
267
class User(Model):
268
    class Meta:
269
        table_name = 'users'
270
    
271
    id = UnicodeAttribute(hash_key=True)
272
    name = UnicodeAttribute()
273

274
user = User.get('123')  # Automatically traced
275
```
276

277
## Patching Patterns
278

279
### Basic Patching
280

281
```python
282
from aws_xray_sdk.core import patch_all, patch, xray_recorder
283

284
# Configure recorder first
285
xray_recorder.configure(
286
    sampling=False,
287
    context_missing='LOG_ERROR'
288
)
289

290
# Option 1: Patch all supported libraries
291
patch_all()
292

293
# Option 2: Patch specific libraries
294
patch(['requests', 'botocore', 'sqlite3'])
295

296
# Your application code - all patched libraries are now traced
297
import requests
298
import boto3
299

300
with xray_recorder.in_segment('my-application'):
301
    # These calls are automatically traced
302
    response = requests.get('https://api.example.com')
303
    s3 = boto3.client('s3')
304
    buckets = s3.list_buckets()
305
```
306

307
### Selective Patching with Error Handling
308

309
```python
310
from aws_xray_sdk.core import patch
311

312
# Patch with error handling
313
try:
314
    patch(['requests', 'botocore', 'nonexistent_library'], raise_errors=False)
315
    print("Patching completed - some modules may have been skipped")
316
except Exception as e:
317
    print(f"Patching failed: {e}")
318

319
# Patch with module filtering
320
patch(
321
    ['requests', 'botocore'],
322
    ignore_module_patterns=[r'.*test.*', r'.*mock.*']
323
)
324
```
325

326
### Framework-Specific Patching
327

328
Some libraries require special handling or have dedicated extensions:
329

330
```python
331
# For Django applications
332
from aws_xray_sdk.core import patch
333
patch(['requests', 'botocore'])
334

335
# Django middleware handles segment creation
336
# Add to settings.py:
337
# MIDDLEWARE = ['aws_xray_sdk.ext.django.middleware.XRayMiddleware', ...]
338

339
# For Flask applications  
340
from aws_xray_sdk.core import patch, xray_recorder
341
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
342

343
patch(['requests', 'botocore'])
344
app = Flask(__name__)
345
XRayMiddleware(app, xray_recorder)
346
```
347

348
### Advanced Patching Options
349

350
#### Module Pattern Ignoring
351

352
```python
353
from aws_xray_sdk.core import patch
354

355
# Ignore test and development modules
356
patch(
357
    ['requests', 'botocore'],
358
    ignore_module_patterns=[
359
        r'.*test.*',      # Ignore any module with 'test' in the name
360
        r'.*mock.*',      # Ignore mock modules
361
        r'dev\..*',       # Ignore dev.* modules
362
        r'.*\.test_.*'    # Ignore test_ modules
363
    ]
364
)
365
```
366

367
#### Double Patching
368

369
```python
370
from aws_xray_sdk.core import patch_all
371

372
# Enable double patching for indirect dependencies
373
patch_all(double_patch=True)
374
```
375

376
This enables patching of libraries that other libraries depend on, providing more comprehensive tracing coverage.
377

378
### Custom Module Patching
379

380
For libraries not in the standard supported list, you can patch entire modules recursively:
381

382
```python
383
from aws_xray_sdk.core import patch
384

385
# Patch entire local modules recursively
386
patch(['myapp.services', 'myapp.utils'])
387

388
# This applies @xray_recorder.capture() decorator to all functions
389
# and class methods in the specified modules and their submodules
390
```
391

392
## Error Handling and Troubleshooting
393

394
### Common Patching Issues
395

396
1. **Import Order**: Patch libraries before importing them
397
2. **Module Not Found**: Use `raise_errors=False` for optional libraries
398
3. **Conflicting Patches**: Avoid patching the same library multiple times
399
4. **Framework Integration**: Some frameworks require specific middleware setup
400

401
### Best Practices
402

403
```python
404
from aws_xray_sdk.core import patch_all, xray_recorder
405

406
# 1. Configure recorder first
407
xray_recorder.configure(
408
    sampling=False,
409
    context_missing='LOG_ERROR',
410
    daemon_address='127.0.0.1:2000'
411
)
412

413
# 2. Patch libraries early in application startup
414
patch_all()
415

416
# 3. Import libraries after patching
417
import requests
418
import boto3
419
import sqlite3
420

421
# 4. Use with proper segment management
422
with xray_recorder.in_segment('application-startup'):
423
    # Initialize your application
424
    pass
425
```
426

427
### Verification
428

429
```python
430
from aws_xray_sdk.core import xray_recorder
431

432
# Check if a library is properly patched
433
if hasattr(requests.get, '__wrapped__'):
434
    print("Requests is properly patched")
435

436
# Test tracing is working
437
with xray_recorder.in_segment('test-segment'):
438
    response = requests.get('https://httpbin.org/get')
439
    print(f"Request traced: {response.status_code}")
440
```