1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
# AWS X-Ray SDK for Python <sup><sup><sup>(beta)</sup></sup></sup>
## Installing
The AWS X-Ray SDK for Python is compatible with Python 2.7, 3.4, 3.5, and 3.6.
Install the SDK using the following command (the SDK's non-testing dependencies will be installed).
```
pip install aws-xray-sdk
```
To install the SDK's testing dependencies, use the following command.
```
pip install tox
```
## Getting Help
Use the following community resources for getting help with the SDK. We use the GitHub
issues for tracking bugs and feature requests.
* Ask a question in the [AWS X-Ray Forum](https://forums.aws.amazon.com/forum.jspa?forumID=241&start=0).
* Open a support ticket with [AWS Support](http://docs.aws.amazon.com/awssupport/latest/user/getting-started.html).
* If you think you may have found a bug, open an [issue](https://github.com/aws/aws-xray-sdk-python/issues/new).
## Opening Issues
If you encounter a bug with the AWS X-Ray SDK for Python, we want to hear about
it. Before opening a new issue, search the [existing issues](https://github.com/aws/aws-xray-sdk-python/issues)
to see if others are also experiencing the issue. Include the version of the AWS X-Ray
SDK for Python, Python language, and botocore/boto3 if applicable. In addition,
include the repro case when appropriate.
The GitHub issues are intended for bug reports and feature requests. For help and
questions about using the AWS SDK for Python, use the resources listed
in the [Getting Help](https://github.com/aws/aws-xray-sdk-python#getting-help) section. Keeping the list of open issues lean helps us respond in a timely manner.
## Documentation
The [developer guide](https://docs.aws.amazon.com/xray/latest/devguide) provides in-depth
guidance about using the AWS X-Ray service.
The [API Reference](http://docs.aws.amazon.com/xray-sdk-for-python/latest/reference/)
provides guidance for using the SDK and module-level documentation.
## Quick Start
**Configuration**
```python
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(
sampling=False,
context_missing='LOG_ERROR',
plugins=('EC2Plugin', 'ECSPlugin', 'ElasticBeanstalkPlugin'),
daemon_address='127.0.0.1:3000',
dynamic_naming='*mysite.com*'
)
```
**Start a custom segment/subsegment**
```python
from aws_xray_sdk.core import xray_recorder
# Start a segment
segment = xray_recorder.begin_segment('segment_name')
# Start a subsegment
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Add metadata or annotation here if necessary
segment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
xray_recorder.end_subsegment()
# Close the segment
xray_recorder.end_segment()
```
**Capture**
```python
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('subsegment_name')
def myfunc():
# Do something here
myfunc()
```
```python
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture_async('subsegment_name')
async def myfunc():
# Do something here
async def main():
await myfunc()
```
**Trace AWS Lambda functions**
```python
from aws_xray_sdk.core import xray_recorder
def lambda_handler(event, context):
# ... some code
subsegment = xray_recorder.begin_subsegment('subsegment_name')
# Code to record
# Add metadata or annotation here, if necessary
subsegment.put_metadata('key', dict, 'namespace')
subsegment.put_annotation('key', 'value')
xray_recorder.end_subsegment()
# ... some other code
```
**Patch third-party libraries**
```python
from aws_xray_sdk.core import patch
libs_to_patch = ('boto3', 'mysql', 'requests')
patch(libs_to_patch)
```
**Add Django middleware**
In django settings.py, use the following.
```python
INSTALLED_APPS = [
# ... other apps
'aws_xray_sdk.ext.django',
]
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
# ... other middlewares
]
```
**Add Flask middleware**
```python
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.ext.flask.middleware import XRayMiddleware
app = Flask(__name__)
xray_recorder.configure(service='fallback_name', dynamic_naming='*mysite.com*')
XRayMiddleware(app, xray_recorder)
```
**Add aiohttp middleware**
```python
from aiohttp import web
from aws_xray_sdk.ext.aiohttp.middleware import middleware
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core.async_context import AsyncContext
xray_recorder.configure(service='fallback_name', context=AsyncContext())
app = web.Application(middlewares=[middleware])
app.router.add_get("/", handler)
web.run_app(app)
```
## License
The AWS X-Ray SDK for Python is licensed under the Apache 2.0 License. See LICENSE and NOTICE.txt for more information.
|
