配置适用于 Python 的 X-Ray a - Amazon X-Ray
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

配置适用于 Python 的 X-Ray a

适用于 Python 的 X-Ray 开发工具包的X-xray_recorder Ray 开发工具包的X-Ray 您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的中间件。

服务插件

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

插件
  • Amazon EC2 —EC2Plugin 添加实例 ID、可用区和 CloudWatch 日志组。

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

  • 亚马逊 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',)

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

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

SDK 还使用插件设置来设置区段上的origin字段。这表示运行您的应用程序的Amazon资源类型。当您使用多个插件时,SDK 使用以下解析顺序来确定来源: ElasticBeanstalk > EKS > ECS > EC2。

采样规则

SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录哪些请求。默认规则每秒跟踪第一个请求,以及向 X-Ray 发送跟踪的所有服务中任何额外请求的百分之五。在 X-Ray 控制台中创建其他规则,自定义每个应用程序记录的数据量。

SDK 按定义的自定义规则的应用自定义规则的应用原定设置样本规则的应用定义。如果请求匹配多个自定义规则,则 SDK 仅应用第一条规则。

注意

如果 SDK 无法访问 X-Ray 获取采样规则,它将恢复为每秒第一个请求的默认本地规则,以及每台主机任何额外请求的百分之五。如果主机没有权限调用采样 API,或者无法连接到 X-Ray 守护程序,后者充当 SDK 发出的 API 调用的 TCP 代理,就会发生这种情况。

您也可以将 SDK 配置为从 JSON 文档加载采样规则。在无法使用 X-Ray 采样的情况下,SDK 可以使用本地规则作为备份,也可以仅使用本地规则。

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

此示例定义了一个自定义规则和一个默认规则。自定义规则采用 5% 的采样率,没有最低追踪路径的请求数/api/move/。原定设置样本规则为每秒 1 个请求和 5% 的其他请求。

在本地定义规则的缺点是,固定目标由记录器的每个实例独立应用,而不是由 X-Ray 服务管理。随着部署更多主机,固定速率会成倍增加,这使得控制记录的数据量变得更加困难。

启Amazon 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)

日志记录

SDK 使用具有默认WARNING日志级别的 Python 内置logging模块。获取对 aws_xray_sdk 类的日志记录器的引用,并对其调用 setLevel 来为库以及应用程序的其余部分配置不同的日志级别。

例 app.py — 记录
logging.basicConfig(level='WARNING') logging.getLogger('aws_xray_sdk').setLevel(logging.ERROR)

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

代码中的记录器配置

其他设置包含在 xray_recorderconfigure 方法中。

  • context_missing— 设置为LOG_ERROR以避免在未打开任何区段时您的仪器化代码尝试记录数据时引发异常。

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

  • service— 设置 SDK 用于分段的服务名称。

  • plugins— 记录有关您的应用程序Amazon资源的信息。

  • 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— 设置 SDK 用于分段的服务名称。

  • PLUGINS— 记录有关您的应用程序Amazon资源的信息。

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

环境变量

您可以使用环境变量来配置适用于 Python 的 X-Ray 开发工具包。开发工具包支持以下变量:

  • AWS_XRAY_TRACING_NAME— 设置 SDK 用于分段的服务名称。覆盖您以编程方式设置的服务名称。

  • AWS_XRAY_SDK_ENABLED— 设置为时false,禁用 SDK。默认情况下,开发工具包处于启用状态,除非环境变量设置为 false。

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

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

  • AWS_XRAY_DAEMON_ADDRESS— 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下,SDK 同时使用127.0.0.1:2000跟踪数据 (UDP) 和采样 (TCP)。如果您已将守护程序配置为监听其他端口,或者它在其他主机上运行,请使用此变量。

    格式
    • 相同的端口address:port

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

  • AWS_XRAY_CONTEXT_MISSING— 设置为RUNTIME_ERROR,当您的仪器化代码在未打开任何区段时尝试记录数据时抛出异常。

    有效值
    • RUNTIME_ERROR— 抛出运行时异常。

    • LOG_ERROR— 记录错误并继续(默认)。

    当您尝试在未打开请求时运行的启动代码中或在生成新线程的代码中使用仪器化客户端时,可能会发生与缺失分段或子分段相关的错误。

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