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

# AWS X-Ray 適用於 Go 的 SDK
<a name="xray-sdk-go"></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)。

適用於 Go 的 X-Ray 開發套件是一組適用於 Go 應用程式的程式庫，提供產生追蹤資料並將其傳送至 X-Ray 協助程式的類別和方法。追蹤資料包含應用程式所服務傳入 HTTP 請求的相關資訊，以及應用程式使用 AWS SDK、HTTP 用戶端或 SQL 資料庫連接器對下游服務進行的呼叫。您也可以手動建立區段，並將除錯資訊新增至註釋和中繼資料中。

使用 `go get` 以從軟體開發套件的 [GitHub 儲存庫](https://github.com/aws/aws-xray-sdk-go)下載軟體開發套件：

```
$ 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 函數的節點。透過新增 SDK，您可以檢測函數程式碼，將子區段新增至 Lambda 記錄的函數區段。如需詳細資訊，請參閱[AWS Lambda 而且 AWS X-Ray](xray-services-lambda.md)。

接著，[請呼叫 `AWS` 函數以包裝您的用戶端](xray-sdk-go-awssdkclients.md)。此步驟可確保 X-Ray 檢測到對任何用戶端方法的呼叫。您也可以[檢測對 SQL 資料庫的呼叫](xray-sdk-go-sqlclients.md)。

開始使用 SDK 之後，請透過[設定記錄器和中介軟體來](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 或更新版本。

軟體開發套件在編譯和執行時間需仰賴下列程式庫：
+ AWS 適用於 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/` 網址。