Patching libraries to instrument downstream calls - AWS X-Ray
Tracing context for asynchronous work

Patching libraries to instrument downstream calls

To instrument downstream calls, use the X-Ray SDK for Python to patch the libraries that your application uses. The X-Ray SDK for Python can patch the following libraries.

Supported Libraries

  • botocore, boto3 – Instrument AWS 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.

When you use a patched library, the X-Ray SDK for Python creates a subsegment for the call and records information from the request and response. A segment must be available for the SDK to create the subsegment, either from the SDK middleware or from AWS Lambda.

Note

If you use SQLAlchemy ORM, you can instrument your SQL queries by importing the SDK's version of SQLAlchemy's session and query classes. See Use SQLAlchemy ORM for instructions.

To patch all available libraries, use the patch_all function in aws_xray_sdk.core. Some libraries, such as httplib and urllib, may need to enable double patching by calling patch_all(double_patch=True).

Example main.py – Patch all supported libraries
import boto3
import botocore
import requests
import sqlite3

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch_all

patch_all()

To patch a single library, call patch with a tuple of the library name. In order to achieve this, you will need to provide a single element list.

Example main.py – Patch specific libraries
import boto3
import botocore
import requests
import mysql-connector-python

from aws_xray_sdk.core import xray_recorder
from aws_xray_sdk.core import patch

libraries = (['botocore'])
patch(libraries)
Note

In some cases, the key that you use to patch a library does not match the library name. Some keys serve as aliases for one or more libraries.

Libraries Aliases

Tracing context for asynchronous work

For asyncio integrated libraries, or to create subsegments for asynchronous functions, you must also configure the X-Ray SDK for Python with an async context. Import the AsyncContext class and pass an instance of it to the X-Ray recorder.

Note

Web framework support libraries, such as AIOHTTP, are not handled through the aws_xray_sdk.core.patcher module. They will not appear in the patcher catalog of supported libraries.

Example main.py – Patch aioboto3
import asyncio
import aioboto3
import requests

from aws_xray_sdk.core.async_context import AsyncContext
from aws_xray_sdk.core import xray_recorder
xray_recorder.configure(service='my_service', context=AsyncContext())
from aws_xray_sdk.core import patch

libraries = (['aioboto3'])
patch(libraries)