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

# Amazon X-Ray 适用于 Go 的 SDK
<a name="xray-sdk-go"></a>

**注意**  
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)。

适用于 Go 的 X-Ray 开发工具包是一组面向 Go 应用程序的库，可提供类和方法来生成跟踪数据并将跟踪数据发送给 X-Ray 进程守护程序。跟踪数据包括有关应用程序处理的传入 HTTP 请求的信息，以及应用程序使用 Amazon SDK、HTTP 客户端或 SQL 数据库连接器对下游服务进行的调用的信息。您还可以手动创建分段并在注释和元数据中添加调试信息。

使用以下命令从其[GitHub存储库](https://github.com/aws/aws-xray-sdk-go)中下载 SDK`go get`：

```
$ go get -u github.com/aws/aws-xray-sdk-go/... 
```

对于 Web 应用程序，首先[使用 `xray.Handler` 功能](xray-sdk-go-handler.md)跟踪传入请求。消息处理程序为每个被跟踪的请求创建一个[分段](xray-concepts.md#xray-concepts-segments)并在发送响应时完成该分段。当分段打开时，您可以使用开发工具包客户端的方法将信息添加到分段，并创建子分段以跟踪下游调用。开发工具包还会自动记录在分段打开时应用程序引发的异常。

对于由经过检测的应用程序或服务调用的 Lambda 函数，Lambda 会读取[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)并自动跟踪采样的请求。对于其他函数，您可以[将 Lambda 配置](xray-services-lambda.md)为采样和跟踪传入请求。无论哪种情况，Lambda 都会创建分段并将其提供给 X-Ray 开发工具包。

**注意**  
在 Lambda 上，X-Ray 开发工具包是可选的。如果您不在函数中使用它，您的服务映射仍将包含一个用于 Lambda 服务的节点，以及每个 Lambda 函数的节点。可通过添加该开发工具包检测函数代码，将子分段添加到 Lambda 记录的函数分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

接下来，[使用对 `AWS` 函数的调用包装您的客户端](xray-sdk-go-awssdkclients.md)。此步骤可确保 X-Ray 检测对任何客户端方法的调用。您还可以[检测对 SQL 数据库的调用](xray-sdk-go-sqlclients.md)。

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

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

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

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

## 要求
<a name="xray-sdk-go-requirements"></a>

适用于 Go 的 X-Ray 开发工具包需要 Go 1.9 或更高版本。

该 SDK 在编译和运行时依赖于以下库：
+ Amazon 适用于 Go 的 SDK 版本 1.10.0 或更高版本

这些依赖项在开发工具包的 `README.md` 文件中声明。

## 参考文档
<a name="xray-sdk-go-reference"></a>

在下载开发工具包后，本地构建和托管文档以便在 Web 浏览器中查看文档。

**查看参考文档**

1. 导航到 `$GOPATH/src/github.com/aws/aws-xray-sdk-go`（Linux 或 Mac）目录或 `%GOPATH%\src\github.com\aws\aws-xray-sdk-go` (Windows) 文件夹

1. 运行 `godoc` 命令。

   ```
   $ godoc -http=:6060
   ```

1. 打开浏览器，定位到 `http://localhost:6060/pkg/github.com/aws/aws-xray-sdk-go/`。