本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 Ruby **注意** 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)。 有兩種方式可以檢測您的 Ruby 應用程式，以將追蹤傳送至 X-Ray： + [AWS Distro for OpenTelemetry Ruby](xray-ruby-opentel-sdk.md) – 透過 [AWS Distro for OpenTelemetry Collector](https://aws-otel.github.io/docs/getting-started/collector) AWS X-Ray， AWS 提供一組開放原始碼程式庫，用於將相關指標和追蹤傳送至多個 AWS 監控解決方案，包括 Amazon CloudWatch 和 Amazon OpenSearch Service。 + [AWS X-Ray 適用於 Ruby 的 SDK](xray-sdk-ruby.md) – 一組程式庫，用於透過 X-Ray [協助程式產生和傳送追蹤至 X-Ray](xray-daemon.md)。 如需詳細資訊，請參閱[選擇 AWS Distro for OpenTelemetry 和 X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing)。 # AWS Distro for OpenTelemetry Ruby 使用 AWS Distro for OpenTelemetry (ADOT) Ruby，您可以檢測您的應用程式一次，並將相關指標和追蹤傳送至多個 AWS 監控解決方案 AWS X-Ray，包括 Amazon CloudWatch 和 Amazon OpenSearch Service。將 X-Ray 與 ADOT 搭配使用需要兩個元件：啟用 *OpenTelemetry SDK* 以與 X-Ray 搭配使用，以及啟用 *AWS Distro for OpenTelemetry Collector* 以與 X-Ray 搭配使用。 若要開始使用，請參閱 [AWS Distro for OpenTelemetry Ruby 文件](https://aws-otel.github.io/docs/getting-started/ruby-sdk)。 如需搭配 AWS AWS X-Ray 和其他 使用 Distro for OpenTelemetry 的詳細資訊 AWS 服務，請參閱 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/) 或 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)。 如需語言支援和用量的詳細資訊，請參閱 [AWS GitHub 上的可觀測性](https://github.com/aws-observability)。 # 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 或更新版本 # 設定適用於 Ruby 的 X-Ray 開發套件 **注意** 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)。 適用於 Ruby 的 X-Ray 開發套件具有名為 的類別`XRay.recorder`，可提供全域記錄器。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的中介軟體。 **Topics** + [服務外掛程式](#xray-sdk-ruby-configuration-plugins) + [抽樣規則](#xray-sdk-ruby-configuration-sampling) + [日誌](#xray-sdk-ruby-configuration-logging) + [程式碼中的記錄器組態](#xray-sdk-ruby-configuration-code) + [使用 Rails 的記錄器組態](#xray-sdk-ruby-middleware-configuration-rails) + [環境變數](#xray-sdk-ruby-configuration-envvars) ## 服務外掛程式 使用 `plugins` 記錄託管您應用程式之服務的相關資訊。 **外掛程式** + Amazon EC2 – `ec2` 新增執行個體 ID 和可用區域。 + Elastic Beanstalk – `elastic_beanstalk` 新增環境名稱、版本標籤和部署 ID。 + Amazon ECS – `ecs` 新增容器 ID。 ![\[Segment - Scorekeep overview showing Elastic Beanstalk and EC2 deployment details.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-PUTrules-segment-resources-python09.png) 若要使用外掛程式，請在您傳遞至記錄器的組態物件中指定它。 **Example main.rb – 外掛程式組態** ``` my_plugins = %I[ec2 elastic_beanstalk] config = { plugins: my_plugins, name: 'my app', } XRay.recorder.configure(config) ``` 您也可以使用優先於程式碼中設定值的[環境變數](#xray-sdk-ruby-configuration-envvars)，來設定記錄器。 軟體開發套件也會使用外掛程式設定來設定區段上的 `origin` 欄位。這表示執行您應用程式 AWS 的資源類型。當您使用多個外掛程式時，開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。 ## 抽樣規則 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 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。 若要設定備份規則，請在您傳遞至記錄器的組態物件中定義文件的雜湊。 **Example main.rb – 備份規則組態** ``` require 'aws-xray-sdk' my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` 若要單獨存放抽樣規則，請在單獨的檔案中定義雜湊，然後要求 (require) 檔案來將其提取到您的應用程式中。 **Example config/sampling-rules.rb** ``` my_sampling_rules = { version: 1, default: { fixed_target: 1, rate: 0.1 } } ``` **Example main.rb – 從檔案取樣規則** ``` require 'aws-xray-sdk' require 'config/sampling-rules.rb' config = { sampling_rules: my_sampling_rules, name: 'my app', } XRay.recorder.configure(config) ``` 若要僅使用本機規則，請要求 (require) 抽樣規則並設定 `LocalSampler`。 **Example main.rb – 本機規則取樣** ``` require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config) ``` 您也可以設定全域記錄器來停用所有傳入請求的抽樣和檢測。 **Example main.rb – 停用取樣** ``` require 'aws-xray-sdk' config = { sampling: false, name: 'my app', } XRay.recorder.configure(config) ``` ## 日誌 根據預設，記錄器會將資訊層級的事件輸出到 `$stdout`。您可以透過在傳遞至記錄器的組態物件中定義 [logger](https://ruby-doc.org/stdlib-2.4.2/libdoc/logger/rdoc/Logger.html) 來自定記錄日誌。 **Example main.rb – 記錄** ``` require 'aws-xray-sdk' config = { logger: my_logger, name: 'my app', } XRay.recorder.configure(config) ``` 當您[手動產生子區段](xray-sdk-ruby-subsegments.md)時，可使用除錯日誌來識別問題，例如未結束的子區段。 ## 程式碼中的記錄器組態 可以從 `XRay.recorder` 上的 `configure` 方法取得其他可用設定。 + `context_missing` – 設定為 `LOG_ERROR`以避免在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。 + `daemon_address` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。 + `name` – 設定 SDK 用於區段的服務名稱。 + `naming_pattern` – 設定網域名稱模式以使用[動態命名](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)。 + `plugins` – 使用[外掛程式](#xray-sdk-ruby-configuration-plugins)記錄應用程式 AWS 資源的相關資訊。 + `sampling` – 設定為 `false`以停用取樣。 + `sampling_rules` – 設定包含[取樣規則](#xray-sdk-ruby-configuration-sampling)的雜湊。 **Example main.rb – 停用內容缺少例外狀況** ``` require 'aws-xray-sdk' config = { context_missing: 'LOG_ERROR' } XRay.recorder.configure(config) ``` ## 使用 Rails 的記錄器組態 若您使用 Rails 框架，您可以在位於 `app_root/initializers` 之下的 Ruby 檔案中設定全域記錄器上的選項。X-Ray SDK 支援搭配 Rails 使用的額外組態金鑰。 + `active_record` – 設定為 `true`以記錄 Active Record 資料庫交易的子區段。 在名為 `Rails.application.config.xray` 的組態物件中設定可用設定。 **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app', patch: %I[net_http aws_sdk], active_record: true } ``` ## 環境變數 您可以使用環境變數來設定適用於 Ruby 的 X-Ray 開發套件。軟體開發套件支援以下變數： + `AWS_XRAY_TRACING_NAME` – 設定 SDK 用於區段的服務名稱。覆寫您在 servlet 篩選條件的[區段命名策略](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)中設定的服務名稱。 + `AWS_XRAY_DAEMON_ADDRESS` – 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會將追蹤資料傳送至 `127.0.0.1:2000`。如果您已設定協助程式在[不同的連接埠上接聽](xray-daemon-configuration.md)，或在不同的主機上執行，請使用此變數。 + `AWS_XRAY_CONTEXT_MISSING` – 設定為 `RUNTIME_ERROR` 以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。 **有效值** + `RUNTIME_ERROR` – 擲回執行時間例外狀況。 + `LOG_ERROR` – 記錄錯誤並繼續 （預設）。 + `IGNORE_ERROR` – 忽略錯誤並繼續。 當您嘗試在未開啟請求時執行的啟動程式碼中，或在產生新執行緒的程式碼中，使用經檢測的用戶端時，可能會發生與缺少區段或子區段相關的錯誤。 環境變數會覆寫程式碼中所設的值。 # 使用適用於 Ruby 的 X-Ray 開發套件中介軟體追蹤傳入請求 **注意** 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 開發套件來追蹤應用程式在 Amazon EC2 或 Amazon ECS 中的 EC2 執行個體上提供的傳入 HTTP 請求。 AWS Elastic Beanstalk 若您使用 Rails，請使用 Rails 中介軟體來檢測傳入的 HTTP 請求。當您將中介軟體新增至應用程式並設定區段名稱時，適用於 Ruby 的 X-Ray 開發套件會為每個取樣請求建立區段。任何由額外檢測建立的區段都會成為子區段，位於提供 HTTP 請求及回應資訊的請求層級區段之下。此資訊包括時間、方法，以及請求的處置方式。 每個區段都有一個名稱，可在服務映射中識別您的應用程式。區段可以靜態命名，或者您可以設定 SDK 根據傳入請求中的主機標頭動態命名。動態命名可讓您根據請求中的網域名稱來分組追蹤，並在名稱不符合預期模式時套用預設名稱 （例如，如果主機標頭是偽造的）。 **轉送的請求** 如果負載平衡器或其他中介裝置轉送請求到您的應用程式，X-Ray 會從請求中的 `X-Forwarded-For`標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得用戶端 IP。為轉送請求記錄的用戶端 IP 可能是偽造的，因此不應受信任。 轉送請求時，開發套件會在區段中設定額外的欄位來表示這一點。如果區段包含`x_forwarded_for`設為 的欄位`true`，用戶端 IP 會從 HTTP 請求中的 `X-Forwarded-For`標頭取得。 中介軟體會使用 `http` 區塊為每個傳入的請求建立區段，其中包含以下資訊： + **HTTP 方法** – GET、POST、PUT、DELETE 等。 + **用戶端地址** – 傳送請求之用戶端的 IP 地址。 + **回應碼** – 已完成請求的 HTTP 回應碼。 + **時間** – 開始時間 （收到請求的時間） 和結束時間 （傳送回應的時間）。 + **使用者代理程式** — 來自請求`user-agent`的 。 + **內容長度** — `content-length`來自回應的 。 ## 使用 Rails 中介軟體 若要使用中介軟體，請更新您的 gemfile 以包含必要的 [railtie](http://api.rubyonrails.org/classes/Rails/Railtie.html)。 **Example Gemfile - rails** ``` gem 'aws-xray-sdk', require: ['aws-xray-sdk/facets/rails/railtie'] ``` 若要使用中介軟體，您還必須使用代表追蹤映射中應用程式的名稱來[設定記錄器](xray-sdk-ruby-configuration.md#xray-sdk-ruby-middleware-configuration-rails)。 **Example config/initializers/aws\$1xray.rb** ``` Rails.application.config.xray = { name: 'my app' } ``` ## 手動檢測程式碼 若您沒有使用 Rails，請手動建立區段。您可以為每個傳入請求建立區段，或在修補的 HTTP 或 AWS SDK 用戶端周圍建立區段，以提供記錄器新增子區段的內容。 ``` # Start a segment segment = XRay.recorder.begin_segment 'my_service' # Start a subsegment subsegment = XRay.recorder.begin_subsegment 'outbound_call', namespace: 'remote' # Add metadata or annotation here if necessary my_annotations = { k1: 'v1', k2: 1024 } segment.annotations.update my_annotations # Add metadata to default namespace subsegment.metadata[:k1] = 'v1' # Set user for the segment (subsegment is not supported) segment.user = 'my_name' # End segment/subsegment XRay.recorder.end_subsegment XRay.recorder.end_segment ``` ## 設定區段命名策略 AWS X-Ray 使用*服務名稱*來識別您的應用程式，並將其與您的應用程式使用的其他應用程式、資料庫、外部 APIs AWS 和資源區分開來。當 X-Ray SDK 為傳入請求產生區段時，它會在區段的名稱欄位中記錄應用程式的服務[名稱](xray-api-segmentdocuments.md#api-segmentdocuments-fields)。 X-Ray SDK 可以在 HTTP 請求標頭中的主機名稱之後命名區段。不過，此標頭可以偽造，這可能會導致服務映射中出現非預期的節點。若要防止 SDK 因具有偽造主機標頭的請求而不正確地命名區段，您必須指定傳入請求的預設名稱。 如果您的應用程式為多個網域提供請求，您可以將 SDK 設定為使用動態命名策略，以在區段名稱中反映這一點。動態命名策略可讓軟體開發套件針對符合預期模式的請求使用主機名稱，並將預設名稱套用至不符合的請求。 例如，您可能有一個應用程式向三個子網域提供請求：`www.example.com`、 `api.example.com`和 `static.example.com`。您可以使用動態命名策略搭配 模式`*.example.com`，以不同名稱識別每個子網域的區段，在服務映射上產生三個服務節點。如果您的應用程式收到主機名稱不符合模式的請求，您會在服務映射上看到具有您指定之備用名稱的第四個節點。 若要為所有請求區段使用相同的名稱，請如[上一節](#xray-sdk-ruby-middleware-rails)所述，在設定記錄器時指定您應用程式的名稱。 動態命名策略可定義主機名稱應相符的模式，以及如果 HTTP 請求中的主機名稱不符合模式時要使用的預設名稱。若要動態命名區段，請在組態雜湊中指定命名模式。 **Example main.rb – 動態命名** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` 您可以在模式中使用 '\$1' 來比對任何字串，或是 '?' 來比對任何單一字元。 **注意** 您可以使用 `AWS_XRAY_TRACING_NAME` [環境變數](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars)來覆寫您在程式碼中定義的預設服務名稱。 # 修補程式庫來檢測下游呼叫 **注意** 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)。 若要檢測下游呼叫，請使用適用於 Ruby 的 X-Ray 開發套件來修補應用程式使用的程式庫。適用於 Ruby 的 X-Ray 開發套件可以修補下列程式庫。 **支援的程式庫** + `[net/http](https://ruby-doc.org/stdlib-2.4.2/libdoc/net/http/rdoc/Net/HTTP.html)` – 檢測 HTTP 用戶端。 + `[aws-sdk](https://aws.amazon.com/sdk-for-ruby)` – 檢測 適用於 Ruby 的 AWS SDK 用戶端。 當您使用修補的程式庫時，適用於 Ruby 的 X-Ray 開發套件會為呼叫建立子區段，並記錄來自請求和回應的資訊。區段必須透過軟體開發套件中介軟體或呼叫 `XRay.recorder.begin_segment` 供軟體開發套件使用，以建立子區段。 若要修補程式庫，請在您傳遞給 X-Ray 記錄器的組態物件中指定它們。 **Example main.rb – 修補程式程式庫** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # 使用適用於 Ruby 的 X-Ray AWS 開發套件追蹤 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)。 當您的應用程式呼叫 AWS 服務 來存放資料、寫入佇列或傳送通知時，適用於 Ruby 的 X-Ray 開發套件會在[子區段](xray-sdk-ruby-subsegments.md)中追蹤下游的呼叫。您在這些服務中存取的追蹤 AWS 服務 和資源 （例如 Amazon S3 儲存貯體或 Amazon SQS 佇列），會在 X-Ray 主控台的追蹤地圖上顯示為下游節點。 當您[修補程式`aws-sdk`庫](xray-sdk-ruby-patching.md)時，適用於 Ruby 的 X-Ray 開發套件會自動檢測所有 AWS SDK 用戶端。您無法檢測個別用戶端。 對於所有 服務，您可以在 X-Ray 主控台中查看名為 的 API 名稱。對於服務子集，X-Ray SDK 會將資訊新增至區段，以在服務映射中提供更精細的服務。 例如，當您使用經檢測的 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** – 佇列名稱 # 使用 X-Ray 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)。 子區段會延伸追蹤的[區段](xray-concepts.md#xray-concepts-segments)，其中包含為了處理請求而完成之工作的詳細資訊。每次您與經檢測的用戶端進行呼叫時，X-Ray 開發套件都會記錄子區段中產生的資訊。您可以建立其他子區段來將其他子區段分組、測量程式碼區段的效能，或記錄註釋和中繼資料。 若要管理子區段，請使用 `begin_subsegment` 和 `end_subsegment` 方法。 ``` subsegment = XRay.recorder.begin_subsegment name: 'annotations', namespace: 'remote' my_annotations = { id: 12345 } subsegment.annotations.update my_annotations XRay.recorder.end_subsegment ``` 若要建立函數的子區段，請將它包裝在對 `XRay.recorder.capture` 進行的呼叫中。 ``` XRay.recorder.capture('name_for_subsegment') do |subsegment| resp = myfunc() # myfunc is your function subsegment.annotations.update k1: 'v1' resp end ``` 當您在區段或其他子區段中建立子區段時，X-Ray 開發套件會為其產生 ID，並記錄開始時間和結束時間。 **Example 使用中繼資料的子區段** ``` "subsegments": [{ "id": "6f1605cd8a07cb70", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "Custom subsegment for UserModel.saveUser function", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, ``` # 使用適用於 Ruby 的 X-Ray 開發套件將註釋和中繼資料新增至區段 **注意** 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 開發套件建立的區段，或新增至您建立的自訂子區段。 **註釋**是具有字串、數字或布林值的鍵值對。註釋會編製索引，以便與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。 **中繼資料**是索引鍵/值對，可以具有任何類型的值，包括物件和清單，但不會編製索引以與篩選條件表達式搭配使用。使用中繼資料記錄您希望儲存在追蹤中的其他資料，但不需要搭配搜尋使用。 除了註釋和中繼資料，您也可以在區段上[記錄使用者 ID 字串](#xray-sdk-ruby-segment-userid)。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。 **Topics** + [使用適用於 Ruby 的 X-Ray 開發套件記錄註釋](#xray-sdk-ruby-segment-annotations) + [使用適用於 Ruby 的 X-Ray 開發套件記錄中繼資料](#xray-sdk-ruby-segment-metadata) + [使用適用於 Ruby 的 X-Ray 開發套件記錄使用者 IDs](#xray-sdk-ruby-segment-userid) ## 使用適用於 Ruby 的 X-Ray 開發套件記錄註釋 針對您想要建立索引以用於搜尋的區段或子區段，請使用標註來記錄這些區段上的資訊。 **註釋要求** + **金鑰** – X-Ray 註釋的金鑰最多可有 500 個英數字元。您不能使用點或句點以外的空格或符號 ( 。 ) + **值** – X-Ray 註釋的值最多可有 1，000 個 Unicode 字元。 + **註釋**數量 – 每個追蹤最多可以使用 50 個註釋。 **記錄標註** 1. 從 `xray_recorder` 取得目前區段或子區段的參考。 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 或 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. 使用雜湊值呼叫 `update`。 ``` my_annotations = { id: 12345 } document.annotations.update my_annotations ``` 以下是示範如何使用包含點的`update`註釋索引鍵來呼叫 的範例。 ``` my_annotations = { testkey.test: 12345 } document.annotations.update my_annotations ``` 軟體開發套件會將標註以鍵/值對記錄在區段文件中的 `annotations` 物件內。若使用相同鍵呼叫 `add_annotations` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。 若要尋找具有特定值註釋的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `annotation[key]`關鍵字。 ## 使用適用於 Ruby 的 X-Ray 開發套件記錄中繼資料 針對您不想要建立索引以用於搜尋的區段，請使用中繼資料來記錄這些區段或子區段上的資訊。中繼資料值可以是字串、數字、布林值，或可序列化為 JSON 物件或陣列的任何物件。 **記錄中繼資料** 1. 從 `xray_recorder` 取得目前區段或子區段的參考。 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 或 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_subsegment ``` 1. 使用字串鍵、布林值、數字、字串或物件值，以及字串命名空間，呼叫 `metadata`。 ``` my_metadata = { my_namespace: { key: 'value' } } subsegment.metadata my_metadata ``` 若使用相同鍵呼叫 `metadata` 兩次，則會覆寫之前在相同區段或子區段上記錄的值。 ## 使用適用於 Ruby 的 X-Ray 開發套件記錄使用者 IDs 記錄請求區段上的使用者 ID 以識別傳送請求的使用者。 **記錄使用者 ID** 1. 從 `xray_recorder` 取得目前區段的參考。 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. 將區段上的使用者欄位設為傳送請求的使用者字串 ID。 ``` segment.user = 'U12345' ``` 您可以在控制器中設定使用者，以在應用程式開始處理請求時馬上記錄使用者 ID。 若要尋找使用者 ID 的追蹤，請在[篩選條件表達](xray-console-filters.md)式中使用 `user`關鍵字。