配置 Ruby 的 X-Ray 开发工具包 - Amazon X-Ray
服务插件采样规则日志记录代码中的记录器配置使用 Rails 时的记录器配置环境变量
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

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

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

服务插件

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

插件

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

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

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

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

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 服务管理。随着部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

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

例 main.rb — Backup 规则配置
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.recorder 的 configure 方法中。

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

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

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

  • naming_pattern— 设置域名模式以使用动态命名。

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

  • sampling— 设置为禁false用采样。

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

例 main.rb — 禁用上下文缺失异常
require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)

使用 Rails 时的记录器配置

如果您使用的是 Rails 框架，则可在 app_root/initializers 下的 Ruby 文件中配置全局记录器的选项。X-Ray ails SDK 支持额外的配置密钥，可用于 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— 设置 SDK 用于分段的服务名称。覆盖您根据 servlet 筛选器的分段命名策略设置的服务名称。

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

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

    有效值

    • RUNTIME_ERROR— 抛出运行时异常。

    • LOG_ERROR— 记录错误并继续（默认）。

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

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