Package: aws-xray-sdk
:mega: OpenTelemetry Python with AWS X-RayAWS 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. Seechoosing between the ADOT and X-Ray SDKsfor more help with choosing between the two.If you want additional features when tracing your Python applications, pleaseopen an issue on the OpenTelemetry Python Instrumentation repository.:mega: Python Versions End-of-Support NoticeAWS X-Ray SDK for Python versions>2.11.0has dropped support for Python 2.7, 3.4, 3.5, and 3.6.AWS X-Ray SDK for PythonInstallingThe 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-sdkTo install the SDK's testing dependencies, use the following command.pip install toxGetting HelpUse 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 theAWS X-Ray Forum.Open a support ticket withAWS Support.If you think you may have found a bug, open anissue.Opening IssuesIf you encounter a bug with the AWS X-Ray SDK for Python, we want to hear about
it. Before opening a new issue, search theexisting issuesto 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 theGetting Helpsection. Keeping the list of open issues lean helps us respond in a timely manner.DocumentationThedeveloper guideprovides in-depth
guidance about using the AWS X-Ray service.
TheAPI Referenceprovides guidance for using the SDK and module-level documentation.Quick StartConfigurationfromaws_xray_sdk.coreimportxray_recorderxray_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/subsegmentUsing context managers for implicit exceptions recording:fromaws_xray_sdk.coreimportxray_recorderwithxray_recorder.in_segment('segment_name')assegment:# Add metadata or annotation here if necessarysegment.put_metadata('key',dict,'namespace')withxray_recorder.in_subsegment('subsegment_name')assubsegment:subsegment.put_annotation('key','value')# Do something herewithxray_recorder.in_subsegment('subsegment2')assubsegment:subsegment.put_annotation('key2','value2')# Do something elseasync versions of context managers:fromaws_xray_sdk.coreimportxray_recorderasyncwithxray_recorder.in_segment_async('segment_name')assegment:# Add metadata or annotation here if necessarysegment.put_metadata('key',dict,'namespace')asyncwithxray_recorder.in_subsegment_async('subsegment_name')assubsegment:subsegment.put_annotation('key','value')# Do something hereasyncwithxray_recorder.in_subsegment_async('subsegment2')assubsegment:subsegment.put_annotation('key2','value2')# Do something elseDefault begin/end functions:fromaws_xray_sdk.coreimportxray_recorder# Start a segmentsegment=xray_recorder.begin_segment('segment_name')# Start a subsegmentsubsegment=xray_recorder.begin_subsegment('subsegment_name')# Add metadata or annotation here if necessarysegment.put_metadata('key',dict,'namespace')subsegment.put_annotation('key','value')xray_recorder.end_subsegment()# Close the segmentxray_recorder.end_segment()Oversampling MitigationTo modify the sampling decision at the subsegment level, subsegments that inherit the decision of their direct parent (segment or subsegment) can be created usingxray_recorder.begin_subsegment()and unsampled subsegments can be created usingxray_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.fromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.core.models.subsegmentimportSubsegmentfromaws_xray_sdk.core.utils.sqs_message_helperimportSqsMessageHelperdeflambda_handler(event,context):formessageinevent['Records']:ifSqsMessageHelper.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.fromaws_xray_sdk.coreimportxray_recorder,patch_allimportboto3patch_all()deflambda_handler(event,context):subsegment=xray_recorder.begin_subsegment_without_sampling('unsampled_subsegment')client=boto3.client('sqs')print(client.list_queues())xray_recorder.end_subsegment()CaptureAs a decorator:fromaws_xray_sdk.coreimportxray_recorder@xray_recorder.capture('subsegment_name')defmyfunc():# Do something heremyfunc()or as a context manager:fromaws_xray_sdk.coreimportxray_recorderwithxray_recorder.capture('subsegment_name')assubsegment:# Do something heresubsegment.put_annotation('mykey',val)# Do something moreAsync capture as decorator:fromaws_xray_sdk.coreimportxray_recorder@xray_recorder.capture_async('subsegment_name')asyncdefmyfunc():# Do something hereasyncdefmain():awaitmyfunc()or as context manager:fromaws_xray_sdk.coreimportxray_recorderasyncwithxray_recorder.capture_async('subsegment_name')assubsegment:# Do something heresubsegment.put_annotation('mykey',val)# Do something moreAdding annotations/metadata using recorderfromaws_xray_sdk.coreimportxray_recorder# Start a segment if no segment existsegment1=xray_recorder.begin_segment('segment_name')# This will add the key value pair to segment1 as it is activexray_recorder.put_annotation('key','value')# Start a subsegment so it becomes the active trace entitysubsegment1=xray_recorder.begin_subsegment('subsegment_name')# This will add the key value pair to subsegment1 as it is activexray_recorder.put_metadata('key','value')ifxray_recorder.is_sampled():# some expensitve annotations/metadata generation code hereval=compute_annotation_val()metadata=compute_metadata_body()xray_recorder.put_annotation('mykey',val)xray_recorder.put_metadata('mykey',metadata)Generate NoOp Trace and Entity IdX-Ray Python SDK will by default generate no-op trace and entity id for unsampled requests and secure random trace and entity id for sampled requests. If customer wants to enable generating secure random trace and entity id for all the (sampled/unsampled) requests (this is applicable for trace id injection into logs use case) then they should set theAWS_XRAY_NOOP_IDenvironment variable as False.Disabling X-RayOften times, it may be useful to be able to disable X-Ray for specific use cases, whether to stop X-Ray from sending traces at any moment, or to test code functionality that originally depended on X-Ray instrumented packages to begin segments prior to the code call. For example, if your application relied on an XRayMiddleware to instrument incoming web requests, and you have a method which begins subsegments based on the segment generated by that middleware, it would be useful to be able to disable X-Ray for your unit tests so thatSegmentNotFoundexceptions are not thrown when you need to test your method.There are two ways to disable X-Ray, one is through environment variables, and the other is through the SDKConfig module.Disabling through the environment variable:Prior to running your application, make sure to have the environment variableAWS_XRAY_SDK_ENABLEDset tofalse.Disabling through the SDKConfig module:from aws_xray_sdk import global_sdk_config

global_sdk_config.set_sdk_enabled(False)Important Notes:Environment Variables always take precedence over the SDKConfig module when disabling/enabling. If your environment variable is set tofalsewhile your code callsglobal_sdk_config.set_sdk_enabled(True), X-Ray will still be disabled.If you need to re-enable X-Ray again during runtime and acknowledge disabling/enabling through the SDKConfig module, you may run the following in your application:import os
from aws_xray_sdk import global_sdk_config

del os.environ['AWS_XRAY_SDK_ENABLED']
global_sdk_config.set_sdk_enabled(True)Trace AWS Lambda functionsfromaws_xray_sdk.coreimportxray_recorderdeflambda_handler(event,context):# ... some codesubsegment=xray_recorder.begin_subsegment('subsegment_name')# Code to record# Add metadata or annotation here, if necessarysubsegment.put_metadata('key',dict,'namespace')subsegment.put_annotation('key','value')xray_recorder.end_subsegment()# ... some other codeTrace ThreadPoolExecutorimportconcurrent.futuresimportrequestsfromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.coreimportpatchpatch(('requests',))URLS=['http://www.amazon.com/','http://aws.amazon.com/','http://example.com/','http://www.bilibili.com/','http://invalid-domain.com/']defload_url(url,trace_entity):# Set the parent X-Ray entity for the worker thread.xray_recorder.set_trace_entity(trace_entity)# Subsegment captured from the following HTTP GET will be# a child of parent entity passed from the main thread.resp=requests.get(url)# prevent thread pollutionxray_recorder.clear_trace_entities()returnresp# Get the current active segment or subsegment from the main thread.current_entity=xray_recorder.get_trace_entity()withconcurrent.futures.ThreadPoolExecutor(max_workers=5)asexecutor:# Pass the active entity from main thread to worker threads.future_to_url={executor.submit(load_url,url,current_entity):urlforurlinURLS}forfutureinconcurrent.futures.as_completed(future_to_url):url=future_to_url[future]try:data=future.result()exceptException:passTrace SQL queriesBy default, if no other value is provided to.configure(), SQL trace streaming is enabled
for all the supported DB engines. Those currently are:Any engine attached to the Django ORM.Any engine attached to SQLAlchemy.The behaviour can be toggled by sending the appropriatestream_sqlvalue, for example:fromaws_xray_sdk.coreimportxray_recorderxray_recorder.configure(service='fallback_name',stream_sql=True)Patch third-party librariesfromaws_xray_sdk.coreimportpatchlibs_to_patch=('boto3','mysql','requests')patch(libs_to_patch)Automatic module patchingFull modules in the local codebase can be recursively patched by providing the module references
to the patch function.fromaws_xray_sdk.coreimportpatchlibs_to_patch=('boto3','requests','local.module.ref','other_module')patch(libs_to_patch)Anxray_recorder.capture()decorator will be applied to all functions and class methods in the
given module and all the modules inside them recursively. Some files/modules can be excluded by
providing to thepatchfunction a regex that matches them.fromaws_xray_sdk.coreimportpatchlibs_to_patch=('boto3','requests','local.module.ref','other_module')ignore=('local.module.ref.some_file','other_module.some_module\.*')patch(libs_to_patch,ignore_module_patterns=ignore)DjangoAdd Django middlewareIn django settings.py, use the following.INSTALLED_APPS=[# ... other apps'aws_xray_sdk.ext.django',]MIDDLEWARE=['aws_xray_sdk.ext.django.middleware.XRayMiddleware',# ... other middlewares]You can configure the X-Ray recorder in a Django app under the ‘XRAY_RECORDER’ namespace. For a minimal configuration, the 'AWS_XRAY_TRACING_NAME' is required unless it is specified in an environment variable.XRAY_RECORDER = {
    'AWS_XRAY_TRACING_NAME': 'My application', # Required - the segment name for segments generated from incoming requests
}For more information about configuring Django with X-Ray read more about it in theAPI referenceSQL tracingIf Django's ORM is patched - either using theAUTO_INSTRUMENT = Truein your settings file
or explicitly callingpatch_db()- the SQL query trace streaming can then be enabled or
disabled updating theSTREAM_SQLvariable in your settings file. It is enabled by default.Automatic patchingThe automatic module patching can also be configured through Django settings.XRAY_RECORDER={'PATCH_MODULES':['boto3','requests','local.module.ref','other_module',],'IGNORE_MODULE_PATTERNS':['local.module.ref.some_file','other_module.some_module\.*',],...}IfAUTO_PATCH_PARENT_SEGMENT_NAMEis also specified, then a segment parent will be created
with the supplied name, wrapping the automatic patching so that it captures any dangling
subsegments created on the import patching.Django in LambdaX-Ray can't search on http annotations in subsegments.   To enable searching the middleware adds the http values as annotations
This allows searching in the X-Ray console like soThis is configurable in settings withURLS_AS_ANNOTATIONthat has 3 valid valuesLAMBDA- the default, which uses URLs as annotations by default if running in a lambda contextALL- do this for every request (useful if running in a mixed lambda/other deployment)NONE- don't do this for any (avoiding hitting the 50 annotation limit)annotation.url BEGINSWITH "https://your.url.com/here"Add Flask middlewarefromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.ext.flask.middlewareimportXRayMiddlewareapp=Flask(__name__)xray_recorder.configure(service='fallback_name',dynamic_naming='*mysite.com*')XRayMiddleware(app,xray_recorder)Add Bottle middleware(plugin)fromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.ext.bottle.middlewareimportXRayMiddlewareapp=Bottle()xray_recorder.configure(service='fallback_name',dynamic_naming='*mysite.com*')app.install(XRayMiddleware(xray_recorder))Serverless Support for Flask & Django & Bottle Using X-RayServerless is an application model that enables you to shift more of your operational responsibilities to AWS. As a result, you can focus only on your applications and services, instead of the infrastructure management tasks such as server provisioning, patching, operating system maintenance, and capacity provisioning. With serverless, you can deploy your web application toAWS Lambdaand have customers interact with it through a Lambda-invoking endpoint, such asAmazon API Gateway.X-Ray supports the Serverless model out of the box and requires no extra configuration. The middlewares in Lambda generateSubsegmentsinstead ofSegmentswhen an endpoint is reached. This is becauseSegmentscannot be generated inside the Lambda function, but it is generated automatically by the Lambda container. Therefore, when using the middlewares with this model, it is important to make sure that your methods only generateSubsegments.The following guide shows an example of setting up a Serverless application that utilizes API Gateway and Lambda:Instrumenting Web Frameworks in a Serverless EnvironmentWorking with aiohttpAdding aiohttp middleware. Support aiohttp >= 2.3.fromaiohttpimportwebfromaws_xray_sdk.ext.aiohttp.middlewareimportmiddlewarefromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.core.async_contextimportAsyncContextxray_recorder.configure(service='fallback_name',context=AsyncContext())app=web.Application(middlewares=[middleware])app.router.add_get("/",handler)web.run_app(app)Tracing aiohttp client. Support aiohttp >=3.fromaws_xray_sdk.ext.aiohttp.clientimportaws_xray_trace_configasyncdeffoo():trace_config=aws_xray_trace_config()asyncwithClientSession(loop=loop,trace_configs=[trace_config])assession:asyncwithsession.get(url)asrespawaitresp.read()Use SQLAlchemy ORMThe SQLAlchemy integration requires you to override the Session and Query Classes for SQL AlchemySQLAlchemy integration uses subsegments so you need to have a segment started before you make a query.fromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.ext.sqlalchemy.queryimportXRaySessionMakerxray_recorder.begin_segment('SQLAlchemyTest')Session=XRaySessionMaker(bind=engine)session=Session()xray_recorder.end_segment()app=Flask(__name__)xray_recorder.configure(service='fallback_name',dynamic_naming='*mysite.com*')XRayMiddleware(app,xray_recorder)Add Flask-SQLAlchemyfromaws_xray_sdk.coreimportxray_recorderfromaws_xray_sdk.ext.flask.middlewareimportXRayMiddlewarefromaws_xray_sdk.ext.flask_sqlalchemy.queryimportXRayFlaskSqlAlchemyapp=Flask(__name__)app.config["SQLALCHEMY_DATABASE_URI"]="sqlite:///:memory:"XRayMiddleware(app,xray_recorder)db=XRayFlaskSqlAlchemy(app)Ignoring httplib requestsIf you want to ignore certain httplib requests you can do so based on the hostname or URL that is being requsted. The hostname is matched using the Pythonfnmatch librarywhich does Unix glob style matching.fromaws_xray_sdk.ext.httplibimportadd_ignoredasxray_add_ignored# ignore requests to test.myapp.comxray_add_ignored(hostname='test.myapp.com')# ignore requests to a subdomain of myapp.com with a glob patternxray_add_ignored(hostname='*.myapp.com')# ignore requests to /test-url and /other-test-urlxray_add_ignored(urls=['/test-path','/other-test-path'])# ignore requests to myapp.com for /test-urlxray_add_ignored(hostname='myapp.com',urls=['/test-url'])If you use a subclass of httplib to make your requests, you can also filter on the class name that initiates the request. This must use the complete package name to do the match.fromaws_xray_sdk.ext.httplibimportadd_ignoredasxray_add_ignored# ignore all requests made by botocorexray_add_ignored(subclass='botocore.awsrequest.AWSHTTPConnection')LicenseThe AWS X-Ray SDK for Python is licensed under the Apache 2.0 License. See LICENSE and NOTICE.txt for more information.