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

# Amazon X-Ray 适用于 Go 的 SDK
适用于 Go 的 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)。

适用于 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)中来整理子分段并为其分组。您可以为整个函数或任何代码部分创建自定义子分段，并记录子分段的元数据和注释，而不是编写父分段的所有内容。

## 要求


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

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

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

## 参考文档


在下载开发工具包后，本地构建和托管文档以便在 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/`。

# 配置适用于 Go 的 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)。

您可以通过环境变量、使用 `Configure` 对象调用 `Config` 或采用默认值，来为适用于 Go 的 X-Ray 开发工具包指定配置。环境变量优先于 `Config` 值，后者又优先于任何默认值。

**Topics**
+ [

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

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

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

## 环境变量
](#xray-sdk-go-configuration-envvars)
+ [

## 使用 Configure 方法
](#xray-sdk-go-configuration-configure)

## 服务插件


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

**插件**
+ Amazon EC2 — `EC2Plugin` 添加实例 ID、可用区和 CloudWatch 日志组。
+ Elastic Beanstalk - `ElasticBeanstalkPlugin` 添加环境名称、版本标签和部署 ID。
+ Amazon ECS — `ECSPlugin` 添加容器 ID。

![\[Segment - Scorekeep details showing Elastic Beanstalk, EC2, and Xray configuration information.\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-go.png)


要使用插件，请导入以下程序包之一。

```
"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
"github.com/aws/aws-xray-sdk-go/awsplugins/ecs"
"github.com/aws/aws-xray-sdk-go/awsplugins/beanstalk"
```

每个插件都有一个明确的 `Init()` 函数调用来加载插件。

**Example ec2.Init()**  

```
import (
	"os"

	"github.com/aws/aws-xray-sdk-go/awsplugins/ec2"
	"github.com/aws/aws-xray-sdk-go/xray"
)

func init() {
  // conditionally load plugin
  if os.Getenv("ENVIRONMENT") == "production" {
    ec2.Init()
  }

  xray.Configure(xray.Config{
    ServiceVersion: "1.2.3",
  })
}
```

该 SDK 还使用插件设置为设置分段上的 `origin` 字段。这表示运行您的应用程序的 Amazon 资源类型。当您使用多个插件时，SDK 使用以下解析顺序来确定来源： 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 服务管理。随着您部署更多主机，固定速率会成倍增加，这使得控制记录的数据量变得更加困难。

开启后 Amazon Lambda，您无法修改采样率。如果您的函数由检测服务调用，Lambda 将记录生成由该服务采样的请求的调用。如果启用了主动跟踪且不存在任何跟踪标头，则 Lambda 会做出采样决定。

要提供备份规则，请通过使用 `NewCentralizedStrategyWithFilePath` 指向本地采样 JSON 文件。

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

```
s, _ := sampling.NewCentralizedStrategyWithFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})
```

要仅使用本地规则，请通过使用 `NewLocalizedStrategyFromFilePath` 指向本地采样 JSON 文件。

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

```
s, _ := sampling.NewLocalizedStrategyFromFilePath("sampling.json") // path to local sampling json
xray.Configure(xray.Config{SamplingStrategy: s})
```

## 日志记录


**注意**  
从版本 1.0.0-rc.10 开始，`xray.Config{}` 字段 `LogLevel` 和 `LogFormat` 已弃用。

X-Ray 使用以下接口进行日志记录。默认记录器写入 `stdout`（`LogLevelInfo` 及跟高版本）。

```
type Logger interface {
	Log(level LogLevel, msg fmt.Stringer)
}

const (
	LogLevelDebug LogLevel = iota + 1
	LogLevelInfo
	LogLevelWarn
	LogLevelError
)
```

**Example 写入 `io.Writer`**  

```
xray.SetLogger(xraylog.NewDefaultLogger(os.Stderr, xraylog.LogLevelError))
```

## 环境变量


您可以使用环境变量来配置适用于 Go 的 X-Ray 开发工具包。SDK 支持以下变量。
+ `AWS_XRAY_CONTEXT_MISSING` - 设置为 `RUNTIME_ERROR` 在您的已检测代码尝试在分段未打开的情况下记录数据时引发异常。

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

  对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。
+ `AWS_XRAY_TRACING_NAME` - 设置开发工具包用于分段的服务名称。
+ `AWS_XRAY_DAEMON_ADDRESS` - 设置 X-Ray 进程守护程序侦听器的主机和端口。默认情况下，开发工具包会将跟踪数据发送到 `127.0.0.1:2000`。如果您已将进程守护程序配置为[侦听不同端口](xray-daemon-configuration.md)或者进程守护程序在另一台主机上运行，则使用此变量。
+ `AWS_XRAY_CONTEXT_MISSING` - 设置该值来确定开发工具包如何处理缺少上下文错误。对于在未打开任何请求时运行的启动代码或者会生成新线程的代码，如果您尝试在其中使用检测过的客户端，则可能发生与缺失分段或子分段相关的错误。
  + `RUNTIME_ERROR` - 默认情况下，开发工具包设置为抛出运行时异常。
  + `LOG_ERROR` - 记录错误并继续。

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

## 使用 Configure 方法


您还可以使用 `Configure` 方法配置适用于 Go 的 X-Ray 开发工具包。`Configure` 采用一个参数、一个 `Config` 对象以及以下可选字段。

DaemonAddr  
此字符串指定 X-Ray 进程守护程序侦听器的主机和端口。如果未指定，X-Ray 将使用 `AWS_XRAY_DAEMON_ADDRESS` 环境变量的值。如果未设置该值，则将使用“127.0.0.1:2000”。

ServiceVersion  
此字符串指定服务的版本。如果未指定，X-Ray 使用空字符串 ("")。

SamplingStrategy  
此 `SamplingStrategy` 对象指定跟踪哪些应用程序调用。如果未指定，X-Ray 将使用 `LocalizedSamplingStrategy`，这将采用在 `xray/resources/DefaultSamplingRules.json` 中定义的策略。

StreamingStrategy  
此`StreamingStrategy`对象指定在**RequiresStreaming**返回 **true** 时是否流式传输片段。如果未指定，X-Ray 将使用 `DefaultStreamingStrategy`，这将在子分段数超过 20 个时流式传输采样分段。

ExceptionFormattingStrategy  
此 `ExceptionFormattingStrategy` 对象指定您希望如何处理各种异常。如果未指定，X-Ray 将使用带有 `DefaultExceptionFormattingStrategy` 类型的 `XrayError`、错误消息和堆栈跟踪的 `error`。

# 使用适用于 Go 的 X-Ray 开发工具包检测传入 HTTP 请求
传入请求

**注意**  
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 来跟踪您的应用程序在亚马逊 EC2 或 Amazon ECS 的 EC2 实例上提供的 Amazon Elastic Beanstalk传入 HTTP 请求。

使用 `xray.Handler` 检测传入 HTTP 请求。适用于 Go 的 X-Ray 开发工具包在 `http.Handler` 类中实现标准的 Go 库 `xray.Handler` 接口以截取 Web 请求。`xray.Handler` 类通过 `http.Handler` 包装提供的 `xray.Capture`（使用请求的上下文，解析传入的标头，根据需要添加响应标头），并设置特定于 HTTP 的跟踪字段。

当您使用此类来处理 HTTP 请求和响应时，适用于 Go 的 X-Ray 开发工具包将为每个采样请求创建一个分段。此分段包括 HTTP 请求的计时、方法和处置。其他检测会在此分段上创建子分段。

**注意**  
对于 Amazon Lambda 函数，Lambda 会为每个采样请求创建一个分段。请参阅[Amazon Lambda 和 Amazon X-Ray](xray-services-lambda.md)了解更多信息。

以下示例在端口 8000 上截取请求并返回“Hello\$1” 作为响应。它通过任何应用程序创建分段 `myApp` 并检测调用。

**Example main.go**  

```
func main() {
  http.Handle("/", xray.Handler(xray.NewFixedSegmentNamer("MyApp"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello!"))
  })))

  http.ListenAndServe(":8000", nil)
}
```

每个分段都有一个名称，用于在服务映射中标识您的应用程序。可以静态命名分段，也可以将 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`。

## 配置分段命名策略


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 的请求，您将会在服务地图上看到第四个节点，以及您指定的回退名称。

要对所有请求分段使用相同名称，请在创建处理程序时指定应用程序的名称，如前面的部分中所示。

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

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

**Example main.go**  
如果请求中的主机名与模式 `*.example.com` 匹配，请使用主机名。否则，请使用 `MyApp`。  

```
func main() {
  http.Handle("/", xray.Handler(xray.NewDynamicSegmentNamer("MyApp", "*.example.com"), http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte("Hello!"))
  })))

  http.ListenAndServe(":8000", nil)
}
```

# 使用 X-Ray Amazon SDK for Go 追踪 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 服务 以存储数据、写入队列或发送通知时，X-Ray SDK for Go 会按[子分段](xray-sdk-go-subsegments.md)跟踪下游的调用。在这些服务（例如，Amazon S3 存储桶或 Amazon SQS 队列）中追踪的资源 Amazon Web Services 服务 和访问的资源在 X-Ray 控制台的跟踪地图上显示为下游节点。

要跟踪 AWS SDK 客户端，请将客户端对象与 `xray.AWS()` 调用一起包装，如以下示例所示。

**Example main.go**  

```
var dynamo *dynamodb.DynamoDB
func main() {
  dynamo = dynamodb.New(session.Must(session.NewSession()))
  xray.AWS(dynamo.Client)
}
```

然后，当您使用 AWS SDK 客户端时，使用调用方法的 `withContext` 版本，在 `context` 中将其从 `http.Request` 对象传递到[处理程序](xray-sdk-go-handler.md)。

**Example main.go — Amazon SDK 调用**  

```
func listTablesWithContext(ctx context.Context) {
  output := dynamo.ListTablesWithContext(ctx, &dynamodb.ListTablesInput{})
  doSomething(output)
}
```

对于所有服务，都可以在 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** - 队列名称

# 使用适用于 Go 的 X-Ray 开发工具包跟踪对下游 HTTP Web 服务的调用
传出 HTTP 调用

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

当您的应用程序调用微服务或公共 HTTP 时 APIs，您可以使用`xray.Client`将这些调用视为 Go 应用程序的子段，如以下示例所示，其中 *http-client 是一个 HTTP 客户端*。

客户端创建所提供的 HTTP 客户端的阴影副本，默认为 `http.DefaultClient`，并带有使用 `xray.RoundTripper` 包装的往返处理器。

**Example**  

```
myClient := xray.Client(http-client)
```
以下示例借助使用 `xray.Client` 的 ctxhttp 库来检测传出 HTTP 调用。可以传递来自上游调用的 `ctx`。这样可以确保使用现有的区段上下文。例如，X-Ray 不允许在 Lambda 函数中创建新的分段，因此应使用现有的 Lambda 分段上下文。  

```
resp, err := ctxhttp.Get(ctx, xray.Client(nil), url)
```

# 使用适用于 Go 的 X-Ray 开发工具包跟踪 SQL 查询
SQL 查询

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

要跟踪对 PostgreSQL 或 MySQL 的 SQL 调用，请将 `sql.Open` 调用替换为 `xray.SQLContext`，如以下示例所示。如果可能，请使用 URLs 而不是配置字符串。

**Example main.go**  

```
func main() {
  db, err := xray.SQLContext("postgres", "postgres://user:password@host:port/db")
  row, err := db.QueryRowContext(ctx, "SELECT 1") // Use as normal
}
```

# 使用适用于 Go 的 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 在子分段中记录生成的信息。您可以创建其他子分段来分组其他子分段，来度量某个代码段的性能如何，或是来记录注释和元数据。

使用 `Capture` 方法创建有关函数的子分段。

**Example main.go - 自定义子分段**  

```
func criticalSection(ctx context.Context) {
  //this is an example of a subsegment
  xray.Capture(ctx, "GameModel.saveGame", func(ctx1 context.Context) error {
    var err error

    section.Lock()
    result := someLockedResource.Go()
    section.Unlock()

    xray.AddMetadata(ctx1, "ResourceResult", result)
  })
```

以下屏幕截图中显示的示例说明了 `saveGame` 子分段如何显示在应用程序 `Scorekeep` 的跟踪中。

![\[Trace timeline showing Scorekeep application segments, including DynamoDB operations and GameModel saveGame subsegment.\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-PUTrules-timeline-subsegments.png)


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

**注意**  
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-go-segment-userid)。用户 IDs 被记录在区段的单独字段中，并编制索引以供搜索使用。

**Topics**
+ [

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

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

## IDs 使用 X-Ray SDK for Go 录制用户
](#xray-sdk-go-segment-userid)

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


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

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

要记录注释，请使用一个包含您要与分段关联的元数据的字符串来调用 `AddAnnotation`。

```
xray.AddAnnotation(key string, value interface{})
```

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

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

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


使用元数据记录有关您无需为其编制索引以进行搜索的分段的信息。

要记录元数据，请使用一个包含您要与分段关联的元数据的字符串来调用 `AddMetadata`。

```
xray.AddMetadata(key string, value interface{})
```

## IDs 使用 X-Ray SDK for Go 录制用户


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

**要记录用户 IDs**

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

   ```
   import (
     "context"
     "github.com/aws/aws-xray-sdk-go/xray"
   )
   
   mySegment := xray.GetSegment(context)
   ```

1. 使用发送请求的用户的字符串 ID 调用 `setUser`。

   ```
   mySegment.User = "U12345"
   ```

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