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

# 配置适用于 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`。