Developer Guide

Configuring the X-Ray SDK for Python

The X-Ray SDK for Python has a class named xray_recorder that provides the global recorder. You can configure the global recorder to customize the middleware that creates segments for incoming HTTP calls.

Service Plugins

Use plugins to record information about the service hosting your application.


  • Amazon EC2 – EC2Plugin adds the instance ID and Availability Zone.

  • Elastic Beanstalk – ElasticBeanstalkPlugin adds the environment name, version label, and deployment ID.

  • Amazon ECS – ECSPlugin adds the container ID.

        Segment resource data with Amazon EC2 and Elastic Beanstalk

To use a plugin, call configure on the xray_recorder.

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

xray_recorder.configure(aws_xray_tracing_name='My app'
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
# Or:
# plugins = ('elasticbeanstalk_plugin', 'ec2_plugin', 'ecs_plugin')

You can also use environment variables, which take precedence over values set in code, to configure the recorder.

Configure plugins before patching libraries to record downstream calls.

The SDK also uses plugin settings to set the origin field on the segment. This indicates the type of AWS resource that runs your application. The resource type appears under your application's name in the service map. For example, AWS::ElasticBeanstalk::Environment.

Service node with resource type.

When you use multiple plugins, the SDK uses the plugin that was loaded last.

Sampling Rules

The X-Ray SDK for Python applies sampling to incoming requests by default when you use the SDK middleware to instrument your application. You can configure the global recorder to disable sampling and instrument all incoming requests.

Example – disable sampling

from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all xray_recorder.configure(aws_xray_tracing_name='My app' plugins = ('EC2Plugin') xray_recorder.configure(plugins=plugins) xray_recorder.configure(sampling=False) patch_all()

To configure sampling rules, call xray_recorder.configure, as shown in the following example, where rules is either a dictionary of rules or the absolute path to a JSON file containing sampling rules.


Environment Variables

You can use environment variables to configure the X-Ray SDK for Python. The SDK supports the following variables:

  • AWS_XRAY_TRACING_NAME – Set a service name that the SDK uses for segments.

  • AWS_XRAY_DAEMON_ADDRESS – Set the host and port of the X-Ray daemon listener. By default, the SDK sends trace data to Use this variable if you have configured the daemon to listen on a different port or if it is running on a different host.

  • AWS_XRAY_CONTEXT_MISSING – Set to LOG_ERROR to avoid throwing exceptions when your instrumented code attempts to record data when no segment is open.

    Valid Values

    • RUNTIME_ERROR – Throw a runtime exception (default).

    • LOG_ERROR – Log an error and continue.

    Errors related to missing segments or subsegments can occur when you attempt to use an instrumented client in startup code that runs when no request is open, or in code that spawns a new thread.

Environment variables override values set in code.