本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
为 Ruby 配置 X-R SDK ay
Ruby SDK 的 X-Ray 有一个名为的类XRay.recorder，它提供了全局记录器。您可以配置全局记录器以自定义为来HTTP电创建分段的中间件。
服务插件
plugins 用于记录有关托管应用程序的服务的信息。
插件
-
Amazon EC2 —
ec2添加实例 ID 和可用区域。 -
Elastic Beanstalk -
elastic_beanstalk添加环境名称、版本标签和部署 ID。 -
亚马逊 ECS-
ecs添加集装箱编号。
要使用插件，请在您传递给记录器的配置对象中指定插件。
例 main.rb - 插件配置
my_plugins = %I[ec2 elastic_beanstalk]
config = {
plugins: my_plugins,
name: 'my app',
}
XRay.recorder.configure(config)您还可以使用环境变量来配置记录器，它优先于在代码中设置的值。
SDK还使用插件设置来设置区段上的origin字段。这表示运行应用程序的 AWS 资源类型。当您使用多个插件时，SDK使用以下解析顺序来确定来源： ElasticBeanstalk > EKS > ECS > EC2。
采样规则
SDK使用您在 X-Ray 控制台中定义的采样规则来确定要记录哪些请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。在 X-Ray 控制台中创建其他规则以自定义为每个应用程序记录的数据量。
按定义的顺序SDK应用自定义规则。如果请求与多个自定义规则匹配，则仅SDK应用第一条规则。
注意
如果SDK无法访问 X-Ray 获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有额外请求的百分之五。如果主机无权调用采样APIs，或者无法连接到 X-Ray 守护程序（该守护程序充当API调用的TCP代理），则可能会发生这种情况。SDK
您也可以将配置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
}
}此示例定义了一个自定义规则和一个默认规则。自定义规则采用百分之五的采样率，对于 /api/move/ 之下的路径要跟踪的请求数量不设下限。默认规则中每秒的第一个请求以及其他请求的百分之十。
在本地定义规则的缺点是，固定目标由记录器的每个实例独立应用而不是由 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.recorder 的 configure 方法中。
例 main.py - 禁用缺少上下文异常
require 'aws-xray-sdk'
config = {
context_missing: 'LOG_ERROR'
}
XRay.recorder.configure(config)使用 Rails 时的记录器配置
如果您使用的是 Rails 框架，则可在 app_root/initializers 下的 Ruby 文件中配置全局记录器的选项。X-Rails 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-R SDK ay。SDK支持以下变量：
-
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— 记录错误并继续（默认）。 -
IGNORE_ERROR— 忽略错误并继续。
对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。
-
环境变量覆盖在代码中设置的值。
