Amazon X-Ray SDK for Python - Amazon X-Ray
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon X-Ray SDK for Python

The X-Ray SDK for Python is a library for Python web applications that provides classes and methods for generating and sending trace data to the X-Ray daemon. Trace data includes information about incoming HTTP requests served by the application, and calls that the application makes to downstream services using the Amazon SDK, HTTP clients, or an SQL database connector. You can also create segments manually and add debug information in annotations and metadata.

You can download the SDK with pip.

$ pip install aws-xray-sdk

The X-Ray SDK for Python is an open source project. You can follow the project and submit issues and pull requests on GitHub:

If you use Django or Flask, start by adding the SDK middleware to your application to trace incoming requests. The middleware creates a segment for each traced request, and completes the segment when the response is sent. While the segment is open, you can use the SDK client's methods to add information to the segment and create subsegments to trace downstream calls. The SDK also automatically records exceptions that your application throws while the segment is open. For other applications, you can create segments manually.

For Lambda functions called by an instrumented application or service, Lambda reads the tracing header and traces sampled requests automatically. For other functions, you can configure Lambda to sample and trace incoming requests. In either case, Lambda creates the segment and provides it to the X-Ray SDK.


On Lambda, the X-Ray SDK is optional. If you don't use it in your function, your service map will still include a node for the Lambda service, and one for each Lambda function. By adding the SDK, you can instrument your function code to add subsegments to the function segment recorded by Lambda. See Amazon Lambda and Amazon X-Ray for more information.

See Worker for a example Python function instrumented in Lambda.

Next, use the X-Ray SDK for Python to instrument downstream calls by patching your application's libraries. The SDK supports the following libraries.

Supported Libraries
  • botocore, boto3 – Instrument Amazon SDK for Python (Boto) clients.

  • pynamodb – Instrument PynamoDB's version of the Amazon DynamoDB client.

  • aiobotocore, aioboto3 – Instrument asyncio-integrated versions of SDK for Python clients.

  • requests, aiohttp – Instrument high-level HTTP clients.

  • httplib, http.client – Instrument low-level HTTP clients and the higher level libraries that use them.

  • sqlite3 – Instrument SQLite clients.

  • mysql-connector-python – Instrument MySQL clients.

  • pg8000 – Instrument Pure-Python PostgreSQL interface.

  • psycopg2 – Instrument PostgreSQL database adapter.

  • pymongo – Instrument MongoDB clients.

  • pymysql – Instrument PyMySQL based clients for MySQL and MariaDB.

Whenever your application makes calls to Amazon, an SQL database, or other HTTP services, the SDK records information about the call in a subsegment. Amazon Web Services and the resources that you access within the services appear as downstream nodes on the trace map to help you identify errors and throttling issues on individual connections.

After you start using the SDK, customize its behavior by configuring the recorder and middleware. You can add plugins to record data about the compute resources running your application, customize sampling behavior by defining sampling rules, and set the log level to see more or less information from the SDK in your application logs.

Record additional information about requests and the work that your application does in annotations and metadata. Annotations are simple key-value pairs that are indexed for use with filter expressions, so that you can search for traces that contain specific data. Metadata entries are less restrictive and can record entire objects and arrays — anything that can be serialized into JSON.

Annotations and Metadata

Annotations and metadata are arbitrary text that you add to segments with the X-Ray SDK. Annotations are indexed for use with filter expressions. Metadata are not indexed, but can be viewed in the raw segment with the X-Ray console or API. Anyone that you grant read access to X-Ray can view this data.

When you have a lot of instrumented clients in your code, a single request segment can contain a large number of subsegments, one for each call made with an instrumented client. You can organize and group subsegments by wrapping client calls in custom subsegments. You can create a custom subsegment for an entire function or any section of code. You can then you can record metadata and annotations on the subsegment instead of writing everything on the parent segment.

For reference documentation for the SDK's classes and methods, see the Amazon X-Ray SDK for Python API Reference.


The X-Ray SDK for Python supports the following language and library versions.

  • Python – 2.7, 3.4, and newer

  • Django – 1.10 and newer

  • Flask – 0.10 and newer

  • aiohttp – 2.3.0 and newer

  • Amazon SDK for Python (Boto) – 1.4.0 and newer

  • botocore – 1.5.0 and newer

  • enum – 0.4.7 and newer, for Python versions 3.4.0 and older

  • jsonpickle – 1.0.0 and newer

  • setuptools – 40.6.3 and newer

  • wrapt – 1.11.0 and newer

Dependency management

The X-Ray SDK for Python is available from pip.

  • Packageaws-xray-sdk

Add the SDK as a dependency in your requirements.txt file.

Example requirements.txt
aws-xray-sdk==2.4.2 boto3==1.4.4 botocore==1.5.55 Django==1.11.3

If you use Elastic Beanstalk to deploy your application, Elastic Beanstalk installs all of the packages in requirements.txt automatically.