aws-xray-sdk
The AWS X-Ray SDK for Python (the SDK) enables Python developers to record and emit information from within their applications to the AWS X-Ray service.
Description
AWS X-Ray SDK for Python
:mega: Upcoming Maintenance Mode on February 25, 2026
The AWS X-Ray SDKs will enter maintenance mode on February 25, 2026. During maintenance mode, the X-Ray SDKs and Daemon will only receive critical bug fixes and security updates, and will not be updated to support new features.
We recommend that you migrate to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation to generate traces (through manual or zero-code instrumentation) from your application and send them to AWS X-Ray. OpenTelemetry is the industry-wide standard for tracing instrumentation and observability. It has a large open-source community for support and provides more instrumentations and updates. By adopting an OpenTelemetry solution, developers can leverage the latest services and innovations from AWS CloudWatch.
:mega: End-of-Support on February 25, 2027
The AWS X-Ray SDKs will reach end-of-support on February 25, 2027. After end-of-support, the X-Ray SDKs will no longer receive updates or releases. Previously published releases will continue to be available via public package managers and the source code will remain on GitHub.
OpenTelemetry Python with AWS X-Ray
AWS X-Ray supports using OpenTelemetry Python and the AWS Distro for OpenTelemetry (ADOT) Collector to instrument your application and send trace data to X-Ray. The OpenTelemetry SDKs are an industry-wide standard for tracing instrumentation. They provide more instrumentations and have a larger community for support, but may not have complete feature parity with the X-Ray SDKs. See choosing between the ADOT and X-Ray SDKs for more help with choosing between the two.
If you want additional features when tracing your Python applications, please open an issue on the OpenTelemetry Python Instrumentation repository.
Python Versions End-of-Support Notice
AWS X-Ray SDK for Python versions >2.11.0 has dropped support for Python 2.7, 3.4, 3.5, and 3.6.
Installing
The AWS X-Ray SDK for Python is compatible with Python 3.7, 3.8, 3.9, 3.10, and 3.11.
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.
- Open a support ticket with AWS Support.
- If you think you may have found a bug, open an issue.
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 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.
Documentation
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.
Quick Start
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
Using context managers for implicit exceptions recording:
from aws_xray_sdk.core import xray_recorder
with xray_recorder.in_segment('segment_name') as segment:
# Add metadata or annotation here if necessary
segment.put_metadata('key', dict, 'namespace')
with xray_recorder.in_subsegment('subsegment_name') as subsegment:
subsegment.put_annotation('key', 'value')
# Do something here
with xray_recorder.in_subsegment('subsegment2') as subsegment:
subsegment.put_annotation('key2', 'value2')
# Do something else
async versions of context managers:
from aws_xray_sdk.core import xray_recorder
async with xray_recorder.in_segment_async('segment_name') as segment:
# Add metadata or annotation here if necessary
segment.put_metadata('key', dict, 'namespace')
async with xray_recorder.in_subsegment_async('subsegment_name') as subsegment:
subsegment.put_annotation('key', 'value')
# Do something here
async with xray_recorder.in_subsegment_async('subsegment2') as subsegment:
subsegment.put_annotation('key2', 'value2')
# Do something else
Default begin/end functions:
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()
Oversampling Mitigation
To modify the sampling decision at the subsegment level, subsegments that inherit the decision of their direct parent (segment or subsegment) can be created using xray_recorder.begin_subsegment() and unsampled subsegments can be created using
xray_recorder.begin_subsegment_without_sampling().
The code snippet below demonstrates creating a sampled or unsampled subsegment based on the sampling decision of each SQS message processed by Lambda.
from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core.models.subsegment import Subsegment
from aws_xray_sdk.core.utils.sqs_message_helper import SqsMessageHelper
def lambda_handler(event, context):
for message in event['Records']:
if SqsMessageHelper.isSampled(message):
subsegment = xray_recorder.begin_subsegment('sampled_subsegment')
print('sampled - processing SQS message')
else:
subsegment = xray_recorder.begin_subsegment_without_sampling('unsampled_subsegment')
print('unsampled - processing SQS message')
xray_recorder.end_subsegment()
The code snippet below demonstrates wrapping a downstream AWS SDK request with an unsampled subsegment.
from aws_xray_sdk.core import xray_recorder, patch_all
import boto3
patch_all()
def lambda_handler(event, context):
subsegment = xray_recorder.begin_subsegment_without_sampling('unsampled_subsegment')
client = boto3.client('sqs')
print(client.list_queues())
xray_recorder.end_subsegment()
Capture
As a decorator:
from aws_xray_sdk.core import xray_recorder
@xray_recorder.capture('subsegment_name')
def myfunc():
# Do something here
myfunc()
or as a context manager:
from aws_xray_sdk.core import xray_recorder
with xray_recorder.capture('subsegment_name') as subsegment:
# Do something here
subsegment.put_annotation('mykey', val)
# Do something more
Async capture as decorator:
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()
or as context manager:
from aws_xray_sdk.core import xray_recorder
async with xray_recorder.capture_async('subsegment_name') as subsegment:
# Do something here
subsegment.put_annotation('mykey', val)
# Do something more
Adding annotations/metadata using recorder
from aws_xray_sdk.core import xray_recorder
# Start a segment if no segment exist
segment1 = xray_recorder.begin_segment('segment_name')
# This will add the key value pair to segment1 as it is active
xray_recorder.put_annotation('key', 'value')
# Start a subsegment so it becomes the active trace entity
subsegment1 = xray_recorder.begin_subsegment('subsegment_name')
# This will add the key value pair to subsegment1 as it is active
xray_recorder.put_metadata('key', 'value')
if xray_recorder.is_sampled():
# some expensitve annotations/metadata generation code here
val = compute_annotation_val()
metadata = compute_metadata_body()
xray_recorder.put_annotati