本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS X-Ray 适用于 Ruby 的 SDK
**注意**
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。
X-Ray SDK 是一个面向 Ruby Web 应用程序的库，该库提供用于生成跟踪数据并将其发送到 X-Ray 进程守护程序的类和方法。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 AWS 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 的 AWS SDK的、HTTP 和 SQL 客户端。每当您使用已检测的客户端调用下游 AWS 服务 或资源时，SDK 都会在子分段中记录有关该调用的信息。 AWS 服务 您在服务中访问的资源将作为下游节点显示在跟踪地图上，以帮助您识别各个连接上的错误和限制问题。
在开始使用 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 的类和方法的参考文档，请参阅 [AWS X-Ray SDK for Ruby API 参考](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference)。
## 要求
X-Ray SDK 需要 Ruby 2.3 或更高版本，并且与以下库兼容：
+ 适用于 Ruby 的 AWS SDK 3.0 或更高版本
+ Rails 版本 5.1 或更高版本