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

# Amazon X-Ray 适用于 Ruby 的 SDK
X-Ray SDK for Ruby

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

X-Ray SDK 是一个面向 Ruby Web 应用程序的库，该库提供用于生成跟踪数据并将其发送到 X-Ray 进程守护程序的类和方法。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 Amazon SDK、HTTP 客户端或活动记录客户端对下游服务进行的调用的信息。您还可以手动创建分段并在注释和元数据中添加调试信息。

您可以通过将 SDK 添加到 gemfile 并运行 `bundle install` 来下载 SDK。

**Example Gemfile**  

```
gem 'aws-sdk'
```

如果您使用了 Rails，[请首先添加 X-Ray SDK 中间件](xray-sdk-ruby-middleware.md)来跟踪传入请求。请求筛选器将创建一个[分段](xray-concepts.md#xray-concepts-segments)。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。对于非 Rails 应用程序，您可以[手动创建分段](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual)。

接下来，使用 X-Ray SDK 通过[配置记录](xray-sdk-ruby-patching.md)器来修补关联的库，从而检测您 适用于 Ruby 的 Amazon SDK的、HTTP 和 SQL 客户端。每当您使用已检测的客户端调用下游 Amazon Web Services 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 Amazon Web Services 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。

在开始使用 SDK 后，通过[配置记录器](xray-sdk-ruby-configuration.md)来自定义其行为。您可以添加插件来记录有关运行应用程序的计算资源的数据，通过定义采样规则来自定义采样行为，提供记录器以在应用程序日志中查看来自 SDK 的更多或更少的信息。

记录有关请求以及应用程序在[注释和元数据](xray-sdk-ruby-segment.md)中所做的工作的其他信息。注释是简单的键值对，已为这些键值对编制索引以用于[筛选条件表达式](xray-console-filters.md)，以便您能够搜索包含特定数据的跟踪。元数据条目的限制性较低，并且可以记录整个对象和数组 - 可序列化为 JSON 的任何项目。

**注释和元数据**  
注释和元数据是您使用 X-Ray 开发工具包添加到分段的任意文本。系统会对注释编制索引，以便与筛选表达式一起使用。元数据未编制索引，但可以使用 X-Ray 控制台或 API 在原始分段中查看。您授予 X-Ray 读取权限的任何人都可以查看这些数据。

当代码中具有大量检测的客户端时，一个请求分段可包含大量子分段，检测的客户端发起的每个调用均对应一个子分段。您可以通过将客户端调用包含在[自定义子分段](xray-sdk-ruby-subsegments.md)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段，并记录子分段的元数据和注释，而不是编写父分段的所有内容。

有关 SDK 的类和方法的参考文档，请参阅 [Amazon X-Ray SDK for Ruby API 参考](https://docs.amazonaws.cn/xray-sdk-for-ruby/latest/reference)。

## 要求


X-Ray SDK 需要 Ruby 2.3 或更高版本，并且与以下库兼容：
+ 适用于 Ruby 的 Amazon SDK 3.0 或更高版本
+ Rails 版本 5.1 或更高版本

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

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

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

**Topics**
+ [

## 服务插件
](#xray-sdk-ruby-configuration-plugins)
+ [

## 采样规则
](#xray-sdk-ruby-configuration-sampling)
+ [

## 日志记录
](#xray-sdk-ruby-configuration-logging)
+ [

## 代码中的记录器配置
](#xray-sdk-ruby-configuration-code)
+ [

## 使用 Rails 时的记录器配置
](#xray-sdk-ruby-middleware-configuration-rails)
+ [

## 环境变量
](#xray-sdk-ruby-configuration-envvars)

## 服务插件


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

**插件**
+ Amazon EC2 - `ec2` 添加实例 ID 和可用区。
+ Elastic Beanstalk - `elastic_beanstalk` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ecs` 添加容器 ID。

![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png)


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

**Example main.rb - 插件配置**  

```
my_plugins = %I[ec2 elastic_beanstalk]

config = {
  plugins: my_plugins,
  name: 'my app',
}

XRay.recorder.configure(config)
```

您还可以使用[环境变量](#xray-sdk-ruby-configuration-envvars)来配置记录器，它优先于在代码中设置的值。

开发工具包还使用插件设置为设置分段上的 `origin` 字段。这表示运行您的应用程序的 Amazon 资源类型。当您使用多个插件时，软件开发工具包使用以下解析顺序来确定来源： ElasticBeanstalk > EKS > ECS > EC2。

## 采样规则


该 SDK 使用您在 X-Ray 控制台中定义的采样规则来确定要记录的请求。默认规则跟踪每秒的第一个请求，以及所有将跟踪发送到 X-Ray 的服务的任何其他请求的百分之五。[在 X-Ray 控制台中创建其他规则](xray-console-sampling.md)以自定义为每个应用程序记录的数据量。

该 SDK 按照定义的顺序应用自定义规则。如果请求与多个自定义规则匹配，则 SDK 仅应用第一条规则。

**注意**  
如果 SDK 无法访问 X-Ray 来获取采样规则，它将恢复为默认的本地规则，即每秒第一个请求以及每个主机所有其他请求的百分之五。如果主机无权调用采样，或者无法连接到 X-Ray 守护程序 APIs，后者充当 SDK 发出的 API 调用的 TCP 代理，则可能会发生这种情况。

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

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

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

**Example 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)
```

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

**Example config/sampling-rules.rb**  

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

**Example 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`。

**Example main.rb - 本地规则采样**  

```
require 'aws-xray-sdk'
require 'aws-xray-sdk/sampling/local/sampler'

config = {
  sampler: LocalSampler.new,
  name: 'my app',
}
XRay.recorder.configure(config)
```

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

**Example main.rb - 禁用采样**  

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

## 日志记录


默认情况下，记录器将信息级别事件输出到 `$stdout`。您可以通过在传递给记录器的配置对象中定义[记录器](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html)来自定义日志记录。

**Example main.rb - 日志记录**  

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

当您手动[生成子分段](xray-sdk-ruby-subsegments.md)时，使用调试日志来识别诸如未结束子分段之类的问题。

## 代码中的记录器配置


其他设置包含在 `XRay.recorder` 的 `configure` 方法中。
+ `context_missing` - 设置为 `LOG_ERROR` 可避免在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。
+ `daemon_address` - 设置 X-Ray 进程守护程序侦听器的主机和端口。
+ `name` - 设置开发工具包用于进行分段的服务名称。
+ `naming_pattern` - 设置域名模式以使用[动态命名](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)。
+ `plugins` - 使用[插件](#xray-sdk-ruby-configuration-plugins)记录有关应用程序的 Amazon 资源的信息。
+ `sampling` 设置为 `false` 可禁用采样。
+ `sampling_rules` - 设置包含您的[采样规则](#xray-sdk-ruby-configuration-sampling)的哈希。

**Example 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` 的配置对象中配置可用设置。

**Example config/initializers/aws\$1xray.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 筛选器的[分段命名策略](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)设置的服务名称。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，开发工具包会将跟踪数据发送到 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 会在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

**有效值**
  + `RUNTIME_ERROR`— 引发运行时异常。
  + `LOG_ERROR`— 记录错误并继续（默认）。
  + `IGNORE_ERROR`— 忽略错误并继续。

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

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

# 使用 X-Ray SDK for Ruby 中间件跟踪传入请求
传入请求

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

您可以使用 X-Ray SDK 来跟踪您的应用程序在 Amazon EC2 或 Amazon ECS 的 EC2 实例上提供的 Amazon Elastic Beanstalk传入 HTTP 请求。

如果您使用的是 Rails，请使用 Rails 中间件检测传入 HTTP 请求。在您将中间件添加到应用程序并配置分段名称时，X-Ray SDK for Ruby 会为每个采样请求创建一个分段。由其他检测创建的任何分段成为请求级别分段的子分段，请求级别的分段提供有关 HTTP 请求和响应的信息。此信息包括请求的计时、方法和处置。

每个分段都有一个名称，用于在服务映射中标识您的应用程序。可以静态命名分段，也可以将 SDK 配置为根据传入请求中的主机标头对其进行动态命名。动态命名允许根据请求中的域名对跟踪进行分组，并且在名称不匹配预期模式时（例如，如果主机标头是伪造的）应用默认名称。

**转发的请求**  
如果负载均衡器或其他中间将请求转发到您的应用程序，X-Ray 会提取请求 `X-Forwarded-For` 标头中的客户端 IP 而非 IP 数据包中的源 IP。由于转发的请求记录的客户端 IP 可以伪造，因此不应信任。

在转发请求时，SDK 在分段中设置附加字段来指示此行为。如果分段包含设置为 `x_forwarded_for` 的字段 `true`，则从 HTTP 请求的 `X-Forwarded-For` 标头获取客户端 IP。

中间件使用包含以下信息的 `http` 块为每个传入请求创建一个分段：
+ **HTTP 方法** - GET、POST、PUT、DELETE 等。
+ **客户端地址** - 发送请求的客户端的 IP 地址。
+ **响应代码** - 已完成请求的 HTTP 响应代码。
+ **时间** - 开始时间（收到请求时）和结束时间（发送响应时）。
+ **用户代理** - 请求中的 `user-agent`。
+ **内容长度** - 响应中的 `content-length`。

## 使用 Rails 中间件


要使用中间件，请将 gemfile 更新为包含所需的 [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html)。

**Example Gemfile - rails**  

```
gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie']
```

要使用中间件，您还必须使用在跟踪地图中表示应用程序的名称来[配置记录器](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails)。

**Example config/initializers/aws\$1xray.rb**  

```
Rails.application.config.xray = {
  name: 'my app'
}
```

## 手动检测代码


如果您未使用 Rails，请手动创建分段。您可以为每个传入的请求创建区段，也可以围绕已修补的 HTTP 或 Amazon SDK 客户端创建区段，为录制器添加子分段提供上下文。

```
# Start a segment
segment = XRay.recorder.begin_segment 'my_service'
# Start a subsegment
subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote'

# Add metadata or annotation here if necessary
my_annotations = {
  k1: 'v1',
  k2: 1024
}
segment.annotations.update my_annotations

# Add metadata to default namespace
subsegment.metadata[:k1] = 'v1'

# Set user for the segment (subsegment is not supported)
segment.user = 'my_name'

# End segment/subsegment
XRay.recorder.end_subsegment
XRay.recorder.end_segment
```

## 配置分段命名策略


Amazon X-Ray 使用*服务名称*来标识您的应用程序，并将其与您的应用程序使用的其他应用程序、数据库 APIs、外部数据库和 Amazon 资源区分开来。当 X-Ray SDK 为传入请求生成分段时，会将应用程序的服务名称记录在分段的[名称字段](xray-api-segmentdocuments.md#api-segmentdocuments-fields)中。

X-Ray SDK 可以用在 HTTP 请求标头中的 hostname 来命名分段。不过，此标头可以伪造，会导致服务地图中出现意料之外的节点。为防止 SDK 由于包含伪造的主机标头的请求而错误地命名分段，必须为传入请求指定一个默认名称。

如果应用程序为多个域的请求提供服务，则可以将 SDK 配置为使用动态命名策略以在分段名称中反映出这一点。动态命名策略允许 SDK 将主机名用于符合预期模式的请求，并将默认名称应用于不符合预期模式的请求。

例如，可能有一款应用程序为发送到三个子域的请求提供服务，分别为 `www.example.com`、`api.example.com` 和 `static.example.com`。可以使用格式 `*.example.com` 的动态命名策略以识别包含不同名称的子域的分段，服务地图上因此会显示三个服务节点。如果应用程序收到包含与该格式不匹配的 hostname 的请求，您将会在服务地图上看到第四个节点，以及您指定的回退名称。

要对所有请求分段使用相同名称，请在配置记录器时指定应用程序的名称，如[前几节](#xray-sdk-ruby-middleware-rails)所示。

动态命名策略定义一个主机名应匹配的模式和一个在 HTTP 请求中的主机名与该模式不匹配时要使用的默认名称。要动态命名分段，请在 config 哈希中指定命名模式。

**Example main.rb - 动态命名**  

```
config = {
  naming_pattern: '*mydomain*',
  name: 'my app',
}

XRay.recorder.configure(config)
```

您可以在模式中使用“\$1”来匹配任何字符串，或使用“?”来匹配任意单个字符。

**注意**  
您可以使用 `AWS_XRAY_TRACING_NAME` [环境变量](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars)覆盖您在代码中定义的默认服务名称。

# 修补库以检测下游调用
修补库

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

要检测下游调用，请使用适用于 Ruby 的 X-Ray 开发工具包修补您的应用程序使用的库。适用于 Ruby 的 X-Ray 开发工具包可以修补以下库。

**支持的库**
+ `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)` - 检测 HTTP 客户端。
+ `[aws-sdk](https://www.amazonaws.cn/sdk-for-ruby)`— 仪器 适用于 Ruby 的 Amazon SDK 客户。

如果您使用已修补的库，适用于 Ruby 的 X-Ray 开发工具包会为调用创建子分段，并记录请求和响应中的信息。必须通过开发工具包中间件或对 `XRay.recorder.begin_segment` 的调用提供分段，以供开发工具包创建子分段。

要修补库，请在您传递给 X-Ray 记录器的配置对象中指定这些库。

**Example main.rb - 修补库**  

```
require 'aws-xray-sdk'

config = {
  name: 'my app',
  patch: %I[net_http aws_sdk]
}

XRay.recorder.configure(config)
```

# 使用适用于 Ruby 的 X-Ray SD Amazon K 追踪 SDK 调用
Amazon SDK 客户端

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

当您的应用程序调用 Amazon Web Services 服务 以存储数据、写入队列或发送通知时，适用于 Ruby 的 X-Ruby 的 X-Ruby SDK 会按[子分段](xray-sdk-ruby-subsegments.md)跟踪下游的调用。在这些服务（例如，Amazon S3 存储桶或 Amazon SQS 队列）中追踪的资源 Amazon Web Services 服务 和访问的资源在 X-Ray 控制台的跟踪地图上显示为下游节点。

当你[修补`aws-sdk`库](xray-sdk-ruby-patching.md)时，适用于 Ruby 的 X-Ruby Amazon SDK 会自动检测所有 SDK 客户端。您无法检测单个客户端。

对于所有服务，都可以在 X-Ray 控制台中看到调用的 API 的名称。X-Ray 开发工具包会为一部分服务将信息添加到分段，从而在服务地图中提供更高的粒度。

例如，当使用经过检测的 DynamoDB 客户端发出调用时，对于针对表的调用，开发工具包会将表名称添加到分段中。在控制台中，每个表在服务地图中显示为一个独立的节点，以及没有表作为目标的调用的一般 DynamoDB 节点。

**Example 对 DynamoDB 进行调用以保存项目的子分段**  

```
{
  "id": "24756640c0d0978a",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "DynamoDB",
  "namespace": "aws",
  "http": {
    "response": {
      "content_length": 60,
      "status": 200
    }
  },
  "aws": {
    "table_name": "scorekeep-user",
    "operation": "UpdateItem",
    "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
  }
}
```

在您访问指定的资源时，对以下服务的调用会在服务地图中创建额外的节点。没有定向到特定资源的调用，为服务创建了通用节点。
+ **Amazon DynamoDB** - 表名称
+ **Amazon Simple Storage Service** - 存储桶和键名称
+ **Amazon Simple Queue Service** - 队列名称

# 使用 X-Ray 开发工具包生成自定义子分段
自定义子分段

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

子分段可为跟踪的[分段](xray-concepts.md#xray-concepts-segments)扩展为了给请求提供服务而已完成的工作的详细信息。每次使用已检测的客户端进行调用时，X-Ray SDK 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。

要管理子分段，请使用 `begin_subsegment` 和 `end_subsegment` 方法。

```
subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote'
my_annotations = { id: 12345 }
subsegment.annotations.update my_annotations
XRay.recorder.end_subsegment
```

要为函数创建子分段，可将其包装在对 `XRay.recorder.capture` 的调用中。

```
XRay.recorder.capture('name_for_subsegment') do |subsegment|
  resp = myfunc() # myfunc is your function
  subsegment.annotations.update k1: 'v1'
  resp
end
```

当您在分段或者其他子分段中创建子分段时，X-Ray 开发工具包将为其生成 ID 并记录开始时间和结束时间。

**Example 包含元数据的子分段**  

```
"subsegments": [{
  "id": "6f1605cd8a07cb70",
  "start_time": 1.480305974194E9,
  "end_time": 1.4803059742E9,
  "name": "Custom subsegment for UserModel.saveUser function",
  "metadata": {
    "debug": {
      "test": "Metadata string from UserModel.saveUser"
    }
  },
```

# 使用 X-Ray SDK for Ruby，将注释和元数据添加到分段
注释和元数据

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html)。

可以利用注释和元数据记录与请求、环境或应用程序相关的其他信息。可以将注释和元数据添加到 X-Ray 开发工具包创建的分段或您创建的自定义子分段。

**注释**是带字符串、数字或布尔值的键值对。系统会对注释编制索引，以便与[筛选表达式](xray-console-filters.md)一起使用。使用注释记录要用于对控制台中的跟踪进行分组的数据或在调用 [https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html](https://docs.amazonaws.cn/xray/latest/api/API_GetTraceSummaries.html) API 时使用的数据。

**元数据**是可以具有任何类型值的键-值对，包括对象和列表，但没有编制索引，无法与筛选条件表达式一起使用。使用元数据记录要存储在跟踪中但不需要用于搜索跟踪的其他数据。

除了注释和元数据之外，您还可以在分段上[记录用户 ID 字符串](#xray-sdk-ruby-segment-userid)。用户 IDs 被记录在区段的单独字段中，并编制索引以供搜索使用。

**Topics**
+ [

## 使用 X-Ray SDK for Ruby 记录注释
](#xray-sdk-ruby-segment-annotations)
+ [

## 使用 X-Ray SDK for Ruby 记录元数据
](#xray-sdk-ruby-segment-metadata)
+ [

## 使用适用于 Ruby IDs 的 X-Ray SDK 录制用户
](#xray-sdk-ruby-segment-userid)

## 使用 X-Ray SDK for Ruby 记录注释


使用注释记录有关要为其编制索引以进行搜索的分段和子分段的信息。

**注释要求**
+ **键** - X-Ray 注释的键最多可以包含 500 个字母数字字符。除了点或句点（.）之外，不能使用空格或符号
+ **值** - X-Ray 注释的值最多可以包含 1,000 个 Unicode 字符。
+ **注释**的数量 - 每个跟踪最多可使用 50 条注释。

**记录注释**

1. 从 `xray_recorder` 获取对当前分段或子分段的引用。

   ```
   require 'aws-xray-sdk'
   ...
   document = XRay.recorder.current_segment
   ```

   或者

   ```
   require 'aws-xray-sdk'
   ...
   document = XRay.recorder.current_subsegment
   ```

1. 调用带哈希值的 `update`。

   ```
   my_annotations = { id: 12345 }
   document.annotations.update my_annotations
   ```

   以下示例演示如何使用包含点的注释调用 `update`。

   ```
   my_annotations = { testkey.test: 12345 }
   document.annotations.update my_annotations
   ```

开发工具包将注释以键-值对的形式记录在分段文档的 `annotations` 对象中。使用相同键调用两次 `add_annotations` 将覆盖同一分段或子分段上之前记录的值。

要查找具有带特定值的注释的跟踪，请在`annotation[key]`筛选表达式[中使用 ](xray-console-filters.md) 关键字。

## 使用 X-Ray SDK for Ruby 记录元数据


使用元数据记录有关您无需为其编制索引以进行搜索的分段或子分段的信息。元数据值可以是字符串、数字、布尔值或可序列化为 JSON 对象或数组的任何对象。

**记录元数据**

1. 从 `xray_recorder` 获取对当前分段或子分段的引用。

   ```
   require 'aws-xray-sdk'
   ...
   document = XRay.recorder.current_segment
   ```

   或者

   ```
   require 'aws-xray-sdk'
   ...
   document = XRay.recorder.current_subsegment
   ```

1. 使用字符串键、布尔值、数字、字符串或对象值以及字符串命名空间调用 `metadata`。

   ```
   my_metadata = {
     my_namespace: {
       key: 'value'
     }
   }
   subsegment.metadata my_metadata
   ```

使用相同键调用两次 `metadata` 将覆盖同一分段或子分段上之前记录的值。

## 使用适用于 Ruby IDs 的 X-Ray SDK 录制用户


记录请求细分中的用户，以识别发送请求的用户。 IDs 

**记录用户 IDs**

1. 从 `xray_recorder` 获取对当前分段的引用。

   ```
   require 'aws-xray-sdk'
   ...
   document = XRay.recorder.current_segment
   ```

1. 将分段上的用户字段设置为发送请求的用户的字符串 ID。

   ```
   segment.user = 'U12345'
   ```

您可以在控制器中设置用户以便在应用程序开始处理请求后立即记录用户 ID。

要查找用户 ID 的跟踪，请在`user`筛选表达式[中使用 ](xray-console-filters.md) 关键字。