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

# 設定適用於 Ruby 的 X-Ray 開發套件
<a name="xray-sdk-ruby-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)。

適用於 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)

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

使用 `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。

## 抽樣規則
<a name="xray-sdk-ruby-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 服務管理。當您部署更多主機時，固定速率會倍增，因此更難控制記錄的資料量。

若要設定備份規則，請在您傳遞至記錄器的組態物件中定義文件的雜湊。

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

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

根據預設，記錄器會將資訊層級的事件輸出到 `$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)時，可使用除錯日誌來識別問題，例如未結束的子區段。

## 程式碼中的記錄器組態
<a name="xray-sdk-ruby-configuration-code"></a>

可以從 `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 的記錄器組態
<a name="xray-sdk-ruby-middleware-configuration-rails"></a>

若您使用 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
}
```

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

您可以使用環境變數來設定適用於 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` – 忽略錯誤並繼續。

  當您嘗試在未開啟請求時執行的啟動程式碼中，或在產生新執行緒的程式碼中，使用經檢測的用戶端時，可能會發生與缺少區段或子區段相關的錯誤。

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