本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS X-Ray 適用於 Ruby 的 SDK
**注意**
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 是 Ruby Web 應用程式的程式庫，提供產生追蹤資料並將其傳送至 X-Ray 協助程式的類別和方法。追蹤資料包含應用程式提供的傳入 HTTP 請求，以及應用程式使用 AWS SDK、HTTP 用戶端或作用中記錄用戶端對下游服務發出的呼叫的相關資訊。您也可以手動建立區段，並將除錯資訊新增至註釋和中繼資料中。
您可以透過將它新增至您的 gemfile 並執行 `bundle install`，來下載軟體開發套件。
**Example Gemfile**
```
gem 'aws-sdk'
```
如果您使用 Rails，請先[新增 X-Ray SDK 中介軟體](xray-sdk-ruby-middleware.md)來追蹤傳入的請求。請求篩選條件會建立[區段](xray-concepts.md#xray-concepts-segments)。當區段開啟時，您可以使用軟體開發套件用戶端的方法，將資訊新增到區段，並建立子區段以追蹤下游呼叫。軟體開發套件也會在區段為開啟時自動記錄應用程式擲回的例外狀況。針對非 Rails 應用程式，您可以[手動建立區段](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual)。
接著，使用 X-Ray 開發套件來檢測您的 適用於 Ruby 的 AWS SDK、HTTP 和 SQL 用戶端，方法是[設定記錄器](xray-sdk-ruby-patching.md)來修補相關聯的程式庫。每當您使用經檢測的用戶端呼叫下游 AWS 服務 或資源時，開發套件會在子區段中記錄有關呼叫的資訊。 AWS 服務 而您在服務中存取的資源會在追蹤地圖上顯示為下游節點，以協助您識別錯誤並調節個別連線的問題。
開始使用軟體開發套件之後，請[設定記錄器](xray-sdk-ruby-configuration.md)以自訂其行為。您可以新增外掛程式，以記錄執行應用程式所需的運算資源相關資料、定義抽樣規則以自訂抽樣行為，並提供記錄器以在應用程式日誌中查看更多或更少的軟體開發套件資訊。
使用[註釋與中繼資料](xray-sdk-ruby-segment.md)，記錄應用程式所做的請求和工作等其他資訊。註釋是簡單的鍵/值對，系統會為其建立索引以用於[篩選條件表達式](xray-console-filters.md)，因此您可以搜尋包含特定資料的追蹤。中繼資料項目的限制性較低，可以記錄整個物件和陣列，任何可以序列化為 JSON 的項目。
**標註與中繼資料**
註釋和中繼資料是您使用 X-Ray SDK 新增至客群的任意文字。註釋會編製索引，以便與篩選條件表達式搭配使用。中繼資料不會編製索引，但可以使用 X-Ray 主控台或 API 在原始區段中檢視。您授予 X-Ray 讀取存取權的任何人都可以檢視此資料。
當程式碼中有很多經過檢測的用戶端時，單一請求區段可能包含大量子區段，每個使用經檢測用戶端進行的呼叫都有一個子區段。您可以將用戶端呼叫包裝在[自訂子區段](xray-sdk-ruby-subsegments.md)中，以組織和群組子區段。您可以為整個函數或任何部分的程式碼建立自訂子區段，並記錄子區段上的中繼資料和註釋，而不必寫入父區段上的所有項目。
如需開發套件類別和方法的參考文件，請參閱[AWS X-Ray 適用於 Ruby 的開發套件 API 參考](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference)。
## 要求
X-Ray SDK 需要 Ruby 2.3 或更新版本，並與下列程式庫相容：
+ 適用於 Ruby 的 AWS SDK 3.0 版或更新版本
+ Rails 版本 5.1 或更新版本