Typing Stubs for AWS X-Ray SDK for Python

2.15.0.20260408 · active · verified Tue Apr 14

This package provides static type annotations (stubs) for the `aws-xray-sdk` Python library. It enables type checkers like MyPy, Pyright, or Pylance to perform static analysis and provide better autocompletion and error detection for code using `aws-xray-sdk`. It is part of the `typeshed` project and receives regular updates, with the current version targeting `aws-xray-sdk==2.15.*`.

Warnings

breaking The AWS X-Ray SDKs and Daemon (the runtime library this package stubs) entered maintenance mode on February 25, 2026. AWS recommends migrating to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation for new applications to ensure continued feature updates and broader community support.
Fix: For new development, consider migrating to OpenTelemetry-based instrumentation for AWS X-Ray. For existing applications, continue using `aws-xray-sdk` and `types-aws-xray-sdk` with the understanding that only critical bug fixes and security updates will be provided for the runtime library.
gotcha This package (`types-aws-xray-sdk`) contains only type stubs and provides no runtime code or functionality. It must be installed alongside the actual `aws-xray-sdk` library for any application execution. Installing only the stubs will lead to `ModuleNotFoundError` at runtime if `aws-xray-sdk` is not also present.
Fix: Always install the runtime library (`pip install aws-xray-sdk`) in your application's environment in addition to the type stubs (`pip install types-aws-xray-sdk`).
gotcha The versioning of `types-` packages from Typeshed (e.g., `2.15.0.20260408`) typically indicates compatibility with the corresponding major/minor runtime version (e.g., `aws-xray-sdk==2.15.*`). However, there's no strict guarantee of perfect alignment or that patch versions will always be in sync. A mismatch between the stub version and the runtime library version can lead to incorrect type-checking results or `mypy` errors.
Fix: Monitor your type checker's output. If issues arise, ensure your `aws-xray-sdk` and `types-aws-xray-sdk` versions are as close as possible, ideally with the `types-` package's major.minor.patch matching the runtime library. Pinning stub versions (e.g., `types-aws-xray-sdk==X.Y.Z.*`) can provide stability, but may delay benefits from stub improvements.

Install

pip install types-aws-xray-sdk Install stubs
pip install aws-xray-sdk types-aws-xray-sdk mypy Install runtime, stubs, and type checker

Imports

XRayRecorder
```
from aws_xray_sdk.core import xray_recorder
```
Stubs provide type hints for imports from the 'aws-xray-sdk' runtime library, not for imports directly from 'types-aws-xray-sdk'.
patch_all
```
from aws_xray_sdk.core import patch_all
```
The 'patch_all' function is part of the runtime SDK and is used for automatic instrumentation, type-checked by these stubs.

Quickstart

This quickstart demonstrates how to use the underlying `aws-xray-sdk` library, which `types-aws-xray-sdk` provides type hints for. It includes configuration, patching, and a basic traced function using a context manager. To verify the stubs, you would typically run a type checker like MyPy against this code. The commented-out line shows an example of a type error that `types-aws-xray-sdk` would help detect. Remember that for actual tracing, the AWS X-Ray daemon must be running and accessible.

import os
from aws_xray_sdk.core import xray_recorder, patch_all
from aws_xray_sdk.core.segments import Segment

# Install the X-Ray daemon locally or ensure it's available
# Docs: https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html

# Configure X-Ray Recorder (example values)
xray_recorder.configure(
    service='MyApplication',
    sampling=False, # For simplicity in this example
    context_missing='LOG_ERROR',
    daemon_address=os.environ.get('AWS_XRAY_DAEMON_ADDRESS', '127.0.0.1:2000')
)

# Apply patches for supported libraries (e.g., boto3, requests)
patch_all()

def my_traced_function(item_id: str) -> str:
    # Type checking will ensure 'begin_segment' returns a Segment
    with xray_recorder.in_segment('MyFunctionSegment') as segment: # type: Segment
        segment.put_annotation('item_id', item_id)
        print(f"Processing item {item_id} within segment {segment.id}")
        return f"Processed {item_id}"

if __name__ == '__main__':
    # Example usage - this code will run and potentially send traces
    # For type checking, save this as `app.py` and run `mypy app.py`
    result = my_traced_function("12345")
    print(result)

    # Demonstrate a type error (uncomment and run mypy to see it)
    # xray_recorder.configure(service=123) # Expected str, got int

view raw JSON →