配置 适用于 Ruby 的 X-Ray 开发工具包 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

配置 适用于 Ruby 的 X-Ray 开发工具包

适用于 Ruby 的 X-Ray 开发工具包具有提供全局记录器的、名为 XRay.recorder 的类。您可以配置全局记录器以自定义为传入 HTTP 调用创建分段的中间件。

服务插件

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

插件

  • Amazon EC2 – ec2 添加实例 ID 和可用区。

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

  • Amazon ECS – ecs 添加容器 ID。


        利用 Amazon EC2 和 Elastic Beanstalk 插件将资源数据分段。

要使用插件,请在您传递给记录器的配置对象中指定插件。

例 main.rb – 插件配置

my_plugins = %I[ec2 elastic_beanstalk] config = { plugins: my_plugins, name: 'my app', } XRay.recorder.configure(config)

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

开发工具包还使用插件设置来设置分段上的 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 服务进行管理。当您部署多台主机时,固定率将倍增,这使得记录的数据量更难控制。

要配置备份规则,请在传递给记录器的配置对象中为文档定义一个哈希。

例 main.rb – 备份规则配置

require 'aws-xray-sdk' my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config)

要单独存储采样规则,请在一个单独的文件中定义哈希,并要求该文件将哈希拉入您的应用程序中。

例 config/sampling-rules.rb

my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } }

例 main.rb – 文件中的采样规则

require 'aws-xray-sdk' require config/sampling-rules.rb config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config)

要仅使用本地规则,需要采样规则和配置 LocalSampler

例 main.rb – 本地规则采样

require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config)

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

例 main.rb – 禁用采样

require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config)

日志记录

默认情况下,记录器将信息级别事件输出到 $stdout。您可以通过在传递给记录器的配置对象中定义记录器来自定义日志记录。

例 main.rb – 日志记录

require 'aws-xray-sdk' config = { logger: my_logger, name: 'my app', } XRay.recorder.configure(config)

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

代码中的记录器配置

其他设置包含在 XRay.recorderconfigure 方法中。

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

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

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

  • naming_pattern – 设置域名模式以使用动态命名.

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

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

  • sampling_rules – 设置包含您的采样规则的哈希。

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

require 'aws-xray-sdk' config = { context_missing: 'LOG_ERROR' } XRay.recorder.configure(config)

使用 Rails 时的记录器配置

如果您使用的是 Rails 框架,则可在 app_root/initializers 下的 Ruby 文件中配置全局记录器的选项。X-Ray 开发工具包支持对 Rails 使用其他配置键。

  • active_record – 设置为 true 可记录 Active Record 数据库事务的子分段。

在名为 Rails.application.config.xray 的配置对象中配置可用设置。

例 config/initializers/aws_xray.rb

Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true }

环境变量

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

  • AWS_XRAY_TRACING_NAME – 设置开发工具包用于进行分段的服务名称。覆盖您根据 servlet 筛选器的分段命名策略设置的服务名称。

  • AWS_XRAY_DAEMON_ADDRESS – 设置 X-Ray 守护程序侦听器的主机和端口。默认情况下,SDK 会将跟踪数据发送到 127.0.0.1:2000。如果您已将守护程序配置为在不同的端口上侦听,或者它运行在其他主机上,请使用该变量。

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

    有效值

    • RUNTIME_ERROR – 引发运行时异常(默认)。

    • LOG_ERROR – 记录错误并继续。

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

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