本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 設定適用於 Go 的 X-Ray 的開發套件
<a name="xray-sdk-go-configuration"></a>

**注意**  
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](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 for Go through environment 變數的組態、`Configure`使用 `Config` 物件呼叫 ，或假設預設值。環境變數優先於 `Config` 值，而後者則優先於任何預設值。

**Topics**
+ [服務外掛程式](#xray-sdk-go-configuration-plugins)
+ [抽樣規則](#xray-sdk-go-configuration-sampling)
+ [日誌](#xray-sdk-go-configuration-logging)
+ [環境變數](#xray-sdk-go-configuration-envvars)
+ [使用設定](#xray-sdk-go-configuration-configure)

## 服務外掛程式
<a name="xray-sdk-go-configuration-plugins"></a>

使用 `plugins` 記錄託管您應用程式之服務的相關資訊。

**外掛程式**
+ Amazon EC2 – `EC2Plugin` 新增執行個體 ID、可用區域和 CloudWatch Logs 群組。
+ Elastic Beanstalk – `ElasticBeanstalkPlugin` 新增環境名稱、版本標籤和部署 ID。
+ Amazon ECS – `ECSPlugin` 新增容器 ID。

![\[Segment - Scorekeep details showing Elastic Beanstalk, EC2, and Xray configuration information.\]](http://docs.aws.amazon.com/zh_tw/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` 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時，軟體開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。

## 抽樣規則
<a name="xray-sdk-go-configuration-sampling"></a>

SDK 會使用您在 X-Ray 主控台中定義的抽樣規則來決定要記錄哪些請求。預設規則每秒追蹤第一個請求，以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。[在 X-Ray 主控台中建立其他規則](xray-console-sampling.md)，以自訂為每個應用程式記錄的資料量。

軟體開發套件會依定義自訂規則的順序套用自訂規則。如果請求符合多個自訂規則，軟體開發套件只會套用第一個規則。

**注意**  
如果開發套件無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs許可，或無法連線至 X-Ray 協助程式，該常駐程式可作為 SDK 進行 API 呼叫的 TCP 代理，就會發生這種情況。

您也可以設定 SDK 從 JSON 文件載入抽樣規則。對於無法使用 X-Ray 取樣的情況，軟體開發套件可以使用本機規則作為備份，或僅使用本機規則。

**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
  }
}
```

此範例定義了一個自訂規則和預設規則。自訂規則會套用 5% 的取樣率，沒有追蹤 下路徑的最低請求數`/api/move/`。預設規則會追蹤每秒的第一個請求和 10% 的額外請求。

在本機定義規則的缺點是，固定目標是由記錄器的每個執行個體獨立套用，而不是由 X-Ray 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。

開啟時 AWS 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})
```

## 日誌
<a name="xray-sdk-go-configuration-logging"></a>

**注意**  
從版本 1.0.0-rc.10 開始已取代 `xray.Config{}` 欄位 `LogLevel` 和 `LogFormat`。

X-Ray 使用以下界面進行記錄。在 `LogLevelInfo` 和以上時，預設記錄器會寫入 `stdout`。

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

## 環境變數
<a name="xray-sdk-go-configuration-envvars"></a>

您可以使用環境變數來設定適用於 Go 的 X-Ray 開發套件。軟體開發套件支援以下變數。
+ `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。

**有效值**
  + `RUNTIME_ERROR` – 擲回執行時間例外狀況。
  + `LOG_ERROR` – 記錄錯誤並繼續 （預設）。
  + `IGNORE_ERROR` – 忽略錯誤並繼續。

  當您嘗試在未開啟請求時執行的啟動程式碼中使用經檢測的用戶端，或在產生新執行緒的程式碼中，可能會發生與缺少區段或子區段相關的錯誤。
+ `AWS_XRAY_TRACING_NAME` – 設定 SDK 用於區段的服務名稱。
+ `AWS_XRAY_DAEMON_ADDRESS` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會將追蹤資料傳送至 `127.0.0.1:2000`。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。
+ `AWS_XRAY_CONTEXT_MISSING` – 設定 值，以判斷 SDK 如何處理遺漏的內容錯誤。若您嘗試在未開啟請求時於啟動程式碼中使用受檢測用戶端，或是在會產生新執行緒的程式碼中使用受檢測用戶端，就可能會發生與遺漏區段或子區段相關的錯誤。
  + `RUNTIME_ERROR` – 根據預設，軟體開發套件會設定為擲回執行時間例外狀況。
  + `LOG_ERROR` – 設定 以記錄錯誤並繼續。

環境變數會覆寫程式碼中所設的同等值。

## 使用設定
<a name="xray-sdk-go-configuration-configure"></a>

您也可以使用 `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`、錯誤訊息和堆疊追蹤。