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
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.
- Open a support ticket with AWS Support.
- If you think you may have found a bug, open an issue.
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 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 section. Keeping the list of open issues lean helps us respond in a timely manner.
The developer guide provides in-depth guidance about using the AWS X-Ray service. The API Reference provides guidance for using the SDK and module-level documentation.
Configuration
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
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
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('subsegment_name')
def myfunc():
# Do something here
myfunc()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
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 codePatch third-party libraries
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.
INSTALLED_APPS = [
# ... other apps
'aws_xray_sdk.ext.django',
]
MIDDLEWARE = [
'aws_xray_sdk.ext.django.middleware.XRayMiddleware',
# ... other middlewares
]Add Flask middleware
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
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)The AWS X-Ray SDK for Python is licensed under the Apache 2.0 License. See LICENSE and NOTICE.txt for more information.