配置 X-Ray SDK for Python - AWS X-Ray
服务插件采样规则Logging代码中的记录器配置使用 Django 时的记录器配置环境变量
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 AWS 服务入门。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

配置 X-Ray SDK for Python

X-Ray SDK for Python具有提供全局记录器的、名为 xray_recorder 的类。您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的中间件。

服务插件

使用 plugins 可记录有关托管您应用程序的服务的信息。

Plugins

  • Amazon EC2 – EC2Plugin 会添加实例 ID、可用区和 CloudWatch Logs 组。

  • Elastic Beanstalk – ElasticBeanstalkPlugin 添加环境名称、版本标签和部署 ID。

  • Amazon ECS – ECSPlugin 添加容器 ID。

使用 Amazon EC2 和 Elastic Beanstalk 插件为资源数据分段。

要使用插件，请在 xray_recorder 上调用 configure。 

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()
注意

由于 plugins 作为元组传入，因此，请确保在指定单个插件时包含尾部 ,。例如，plugins = ('EC2Plugin',)

您还可以使用环境变量来配置记录器，它优先于在代码中设置的值。

配置插件，然后再修补库，从而记录下游调用。

开发工具包还使用插件设置来设置分段上的 origin 字段。这指示运行您的应用程序的 AWS 资源的类型。资源类型显示在运行应用程序中您应用程序名称的下方。例如：AWS::ElasticBeanstalk::Environment。

具有资源类型的服务节点。

在使用多个插件时，开发工具包将使用以下解析顺序确定来源：ElasticBeanstalk > EKS > ECS > EC2。

采样规则

开发工具包使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跨将跟踪发送至 X-Ray 的所有服务跟踪每秒的第一个请求，以及任何额外请求中的 5%。在 X-Ray 控制台中创建其他规则以自定义为每个应用程序记录的数据量。

SDK 将按定义自定义规则的顺序应用它们。如果一个请求与多个自定义规则匹配，SDK 将只应用第一个规则。

注意

如果开发工具包无法访问 X-Ray 来获取示例规则，则它将恢复为使用每台主机的默认本地规则每秒的第一个请求，以及任何额外请求中的 5%。如果主机无权调用采样 API，或者无法连接到 X-Ray 守护程序（充当开发工具包所发出 API 调用的 TCP 代理），则可能出现此情况。

您还可将开发工具包配置为加载 JSON 文档中的采样规则。开发工具包可以在 X-Ray 采样不可用的情况下使用本地规则作为备份，或仅使用本地规则。

例 sampling-rules.json

{
  "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
  }
}

本示例定义了一个自定义规则和一个默认规则。自定义规则应用了百分之五的取样率，并且对 /api/move/ 下的路径的请求未设置最低追踪请求数量。默认规则将跟踪每秒的第一个请求，以及任何额外请求中的 10%。

在本地定义规则的缺点是，每个记录器实例将独立应用固定目标，而不是由 X-Ray 服务进行管理。当您部署多台主机时，固定率将倍增，这使得记录的数据量更难控制。

在 AWS Lambda 上，您无法修改采样率。如果您的函数由已分析服务调用，则由该服务采样的调用生成请求将由 Lambda 记录。如果启用了活动跟踪，并且没有跟踪标头，则 Lambda 进行采样决策。

要配置备份采样规则，请调用 xray_recorder.configure，如以下示例所示，其中 rules 是规则词典或包含采样规则的 JSON 文件的绝对路径。 

xray_recorder.configure(sampling_rules=rules)

要仅使用本地规则，请使用 LocalSampler 配置记录器。 

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

您还可以配置全局记录器以禁止对所有传入请求进行采样和分析。

例 main.py – 禁用采样

xray_recorder.configure(sampling=False)

Logging

开发工具包使用 Python 的内置 logging 模块。获取对 aws_xray_sdk 类的日志记录器的引用，并对其调用 setLevel 来为库以及应用程序的其余部分配置不同的日志级别。

例 app.py – 日志记录

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

当您手动生成子分段时，使用调试日志来识别诸如未结束子分段之类的问题。

代码中的记录器配置

其他设置包含在 xray_recorder 的 configure 方法中。

  • context_missing – 设置为 LOG_ERROR 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

  • daemon_address – 设置 X-Ray 守护程序侦听器的主机和端口。

  • service – 设置开发工具包用于进行分段的服务名称。

  • plugins – 记录有关应用程序的 AWS 资源的信息。

  • sampling – 设置为 False 可禁用采样。

  • sampling_rules – 设置包含您的采样规则的 JSON 文件的路径。

例 main.py – 禁用缺少上下文异常

from aws_xray_sdk.core import xray_recorder

xray_recorder.configure(context_missing='LOG_ERROR')

使用 Django 时的记录器配置

如果您使用 Django 框架，您可以使用 Django settings.py 文件来配置全局记录器的选项。

  • AUTO_INSTRUMENT（仅限 Django）– 记录内置数据库和模板渲染操作的子分段。

  • AWS_XRAY_CONTEXT_MISSING – 设置为 LOG_ERROR 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

  • AWS_XRAY_DAEMON_ADDRESS – 设置 X-Ray 守护程序侦听器的主机和端口。

  • AWS_XRAY_TRACING_NAME – 设置开发工具包用于进行分段的服务名称。

  • PLUGINS – 记录有关应用程序的 AWS 资源的信息。

  • SAMPLING – 设置为 False 可禁用采样。

  • SAMPLING_RULES – 设置包含您的采样规则的 JSON 文件的路径。

要启用 settings.py 中的记录器配置，请将 Django 中间件添加到已安装应用程序列表中。

例 settings.py – 已安装的应用程序

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

在名为 XRAY_RECORDER 的 dict 中配置可用设置。

例 settings.py – 已安装的应用程序

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,
}

环境变量

您可以使用环境变量配置X-Ray SDK for Python。开发工具包支持以下变量：

  • AWS_XRAY_TRACING_NAME – 设置开发工具包用于进行分段的服务名称。覆盖您以编程方式设置的服务名称。

  • AWS_XRAY_SDK_ENABLED – 如果设置为 false，则会禁用开发工具包。默认情况下，开发工具包处于启用状态，除非环境变量设置为 false。

    • 禁用时，全局记录器会自动生成不发送到守护程序的虚拟分段和子分段，并禁用自动修补。中间件是作为全局记录器的包装器编写的。通过中间件生成的所有分段和子分段也成为虚拟分段和虚拟子分段。

    • 通过环境变量设置 AWS_XRAY_SDK_ENABLED 值，或者通过与 aws_xray_sdk 库中 global_sdk_config 对象的直接交互来设置。环境变量的设置会覆盖这些交互。

  • AWS_XRAY_DAEMON_ADDRESS – 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下，开发工具包对跟踪数据 (UDP) 和采样 (TCP) 使用 127.0.0.1:2000。如果您已将守护程序配置为在不同的端口上侦听，或者它运行在其他主机上，请使用该变量。

    格式

    • 相同端口 – address:port

    • 不同端口 – tcp:address:port udp:address:port

  • AWS_XRAY_CONTEXT_MISSING – 设置为 LOG_ERROR 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

    有效值

    • RUNTIME_ERROR – 引发运行时异常（默认）。

    • LOG_ERROR – 记录错误并继续。

    对于在未打开任何请求时运行的启动代码或生成新线程的代码，如果您尝试在其中使用分析的客户端，则可能发生与缺失分段或子分段相关的错误。

环境变量覆盖在代码中设置的值。