AWS X-Ray SDK for Python

Warnings

• breaking The AWS X-Ray SDKs will enter maintenance mode on February 25, 2026, and reach end-of-support on February 25, 2027. AWS recommends migrating to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation for future tracing needs.
  Fix: Plan migration to AWS Distro for OpenTelemetry or OpenTelemetry Instrumentation before February 25, 2027.
• breaking Version 2.x of the SDK dropped support for Python 2.7 and Python 3.4. All versions 2.x and higher require Python >= 3.7.
  Fix: Upgrade your Python environment to 3.7 or newer. If stuck on older Python, you must use a 1.x version of the SDK, which is no longer actively maintained.
• breaking Version 2.x introduced an incompatibility with `pynamodb` and `aiobotocore` if those libraries require `botocore < 1.11.3`. Ensure these dependencies are compatible with newer `botocore` versions if upgrading to `aws-xray-sdk` 2.x.
  Fix: Ensure `pynamodb` and `aiobotocore` versions support `botocore >= 1.11.3` when using `aws-xray-sdk` 2.x, or remain on `aws-xray-sdk` 1.x.
• breaking The `Subsegment.set_user()` API was removed in version 2.x as the corresponding attribute is not supported by the X-Ray backend.
  Fix: Remove any calls to `subsegment.set_user()` from your code. Consider using `put_annotation` or `put_metadata` if you need to associate user information, although direct user association may be better handled at the segment level if applicable.
• gotcha Context propagation for traces and subsegments across threads (non-asyncio) can be tricky and may not work as expected, potentially leading to `SegmentNotFoundException` or incomplete traces. The Python SDK doesn't explicitly detail multi-threading context management as clearly as other language SDKs.
  Fix: Carefully manage segment/subsegment context in multi-threaded applications using explicit `with xray_recorder.in_segment()` blocks or custom context passing. Consider if asynchronous patterns (like `asyncio` with appropriate instrumentation) or process-based parallelism might be better suited for X-Ray tracing.

Install

• pip install aws-xray-sdk Install core SDK

Imports

• xray_recorder

  from aws_xray_sdk.core import xray_recorder

• patch_all

  from aws_xray_sdk.core import patch_all

  Automatically patches supported libraries (e.g., boto3, requests, DB API 2.0 clients).
• Segment

  from aws_xray_sdk.core.segments import Segment

  Used for manual segment creation, typically less common than using xray_recorder methods.
• Subsegment

  from aws_xray_sdk.core.segments import Subsegment

  Used for manual subsegment creation.
• SegmentNotFoundException

  from aws_xray_sdk.core.exceptions.exceptions import SegmentNotFoundException

  Common exception raised when attempting to interact with a non-existent segment/subsegment context.

Quickstart

This quickstart demonstrates how to configure the X-Ray recorder, patch supported libraries for automatic instrumentation, and use the `@xray_recorder.capture` decorator to create subsegments for function calls. It also shows manual segment creation for contexts not covered by middleware.

import os
from aws_xray_sdk.core import xray_recorder, patch_all
import boto3

# Configure the X-Ray recorder globally
# For local development without a daemon, set sampling=False to prevent errors
# In deployed AWS environments, the daemon address is often discovered automatically.
xray_recorder.configure(
    service='MyPythonApp',
    sampling=False, # Set to True or rely on daemon for actual sampling rules in production
    context_missing='LOG_ERROR', # Other options: 'RUNTIME_ERROR', 'IGNORE'
    daemon_address=os.environ.get('AWS_XRAY_DAEMON_ADDRESS', '127.0.0.1:2000')
)

# Patch supported libraries to automatically instrument calls (e.g., boto3)
patch_all()

# Example: Instrumenting an AWS SDK call with a decorator
@xray_recorder.capture('s3_list_buckets')
def list_s3_buckets():
    # Ensure AWS credentials/config are set in environment or ~/.aws/config
    s3_client = boto3.client('s3', region_name='us-east-1')
    try:
        response = s3_client.list_buckets()
        bucket_names = [bucket['Name'] for bucket in response.get('Buckets', [])]
        # Add custom metadata to the current subsegment
        xray_recorder.current_subsegment().put_metadata('bucket_count', len(bucket_names))
        return bucket_names
    except Exception as e:
        # Record exceptions to the current subsegment
        xray_recorder.current_subsegment().add_exception(e)
        raise

# Manual segment creation (if not using web framework middleware or a top-level decorator)
# This mimics an incoming request context.
with xray_recorder.in_segment(xray_recorder.begin_segment('MyApplicationRootTrace')):
    print("Starting application trace...")
    try:
        buckets = list_s3_buckets()
        print(f"Successfully listed {len(buckets)} S3 buckets.")
        # Add an annotation to the root segment
        xray_recorder.current_segment().put_annotation('result', 'success')
    except Exception as e:
        print(f"An error occurred: {e}")
        xray_recorder.current_segment().put_annotation('result', 'failure')
        xray_recorder.current_segment().add_exception(e)

print("Trace completed.")