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.

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(service='My app')
plugins = ('ElasticBeanstalkPlugin', 'EC2Plugin')
xray_recorder.configure(plugins=plugins)
patch_all()

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 Amazon resource that runs your application. When you use multiple plugins, the SDK uses the following resolution order to determine the origin: ElasticBeanstalk > EKS > ECS > EC2.

Sampling rules

The SDK uses the sampling rules you define in the X-Ray console to determine which requests to record. The default rule traces the first request each second, and five percent of any additional requests across all services sending traces to X-Ray. Create additional rules in the X-Ray console to customize the amount of data recorded for each of your applications.

The SDK applies custom rules in the order in which they are defined. If a request matches multiple custom rules, the SDK applies only the first rule.

You can also configure the SDK to load sampling rules from a JSON document. The SDK can use local rules as a backup for cases where X-Ray sampling is unavailable, or use local rules exclusively.

{
  "version": 2,
  "rules": [
    {
      "description": "Player moves.",
      "host": "*",
      "http_method": "*",
      "url_path": "/api/move/*",
      "fixed_target": 0,
      "rate": 0.05
    }
  ],
  "default": {
    "fixed_target": 1,
    "rate": 0.1
  }
}

This example defines one custom rule and a default rule. The custom rule applies a five-percent sampling rate with no minimum number of requests to trace for paths under /api/move/. The default rule traces the first request each second and 10 percent of additional requests.

The disadvantage of defining rules locally is that the fixed target is applied by each instance of the recorder independently, instead of being managed by the X-Ray service. As you deploy more hosts, the fixed rate is multiplied, making it harder to control the amount of data recorded.

On Amazon Lambda, you cannot modify the sampling rate. If your function is called by an instrumented service, calls that generated requests that were sampled by that service will be recorded by Lambda. If active tracing is enabled and no tracing header is present, Lambda makes the sampling decision.

To configure backup 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.

xray_recorder.configure(sampling_rules=rules)

To use only local rules, configure the recorder with a LocalSampler.

from aws_xray_sdk.core.sampling.local.sampler import LocalSampler
xray_recorder.configure(sampler=LocalSampler())

You can also configure the global recorder to disable sampling and instrument all incoming requests.

xray_recorder.configure(sampling=False)

Logging

The SDK uses Python’s built-in logging module with a default WARNING logging level. Get a reference to the logger for the aws_xray_sdk class and call setLevel on it to configure the different log level for the library and the rest of your application.

logging.basicConfig(level='WARNING')
logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

Use debug logs to identify issues, such as unclosed subsegments, when you generate subsegments manually.

Recorder configuration in code

Additional settings are available from the configure method on xray_recorder.

from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')

Recorder configuration with Django

If you use the Django framework, you can use the Django settings.py file to configure options on the global recorder.

To enable recorder configuration in settings.py, add the Django middleware to the list of installed apps.

INSTALLED_APPS = [
    ...
    'django.contrib.sessions',
    'aws_xray_sdk.ext.django',
]

Configure the available settings in a dict named XRAY_RECORDER.

XRAY_RECORDER = {
    'AUTO_INSTRUMENT': True,
    'AWS_XRAY_CONTEXT_MISSING': 'LOG_ERROR',
    'AWS_XRAY_DAEMON_ADDRESS': '127.0.0.1:5000',
    'AWS_XRAY_TRACING_NAME': 'My application',
    'PLUGINS': ('ElasticBeanstalkPlugin', 'EC2Plugin', 'ECSPlugin'),
    'SAMPLING': False,
}

Environment variables

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

Environment variables override values set in code.