本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
設定適用於 Ruby 的 X-Ray 開發套件
適用於 Ruby 的 X-Ray 開發套件具有名為 的類別XRay.recorder，可提供全域記錄器。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的中介軟體。
服務外掛程式
使用 plugins 記錄託管您應用程式之服務的相關資訊。
外掛程式
-
Amazon EC2 –
ec2新增執行個體 ID 和可用區域。 -
Elastic Beanstalk –
elastic_beanstalk新增環境名稱、版本標籤和部署 ID。 -
Amazon ECS –
ecs新增容器 ID。
若要使用外掛程式，請在您傳遞至記錄器的組態物件中指定它。
範例 main.rb – 外掛程式組態
my_plugins = %I[ec2 elastic_beanstalk]
config = {
plugins: my_plugins,
name: 'my app',
}
XRay.recorder.configure(config)您也可以使用優先於程式碼中設定值的環境變數，來設定記錄器。
軟體開發套件也會使用外掛程式設定來設定區段上的 origin 欄位。這表示執行應用程式的 AWS 資源類型。當您使用多個外掛程式時，軟體開發套件會使用下列解析順序來判斷原始伺服器：ElasticBeanstalk > EKS > ECS > EC2。
抽樣規則
SDK 會使用您在 X-Ray 主控台中定義的取樣規則來判斷要記錄的請求。預設規則每秒追蹤第一個請求，以及所有傳送追蹤至 X-Ray 服務的任何其他請求的 5%。在 X-Ray 主控台中建立其他規則，以自訂為每個應用程式記錄的資料量。
軟體開發套件會依定義順序套用自訂規則。如果請求符合多個自訂規則，則 SDK 只會套用第一個規則。
注意
如果 SDK 無法達到 X-Ray 以取得取樣規則，它會每秒還原為第一個請求的預設本機規則，以及每個主機任何額外請求的 5%。如果主機沒有呼叫取樣 APIs的許可，或無法連線至 X-Ray 協助程式，而該常駐程式可作為 SDK 所發出 API 呼叫的 TCP 代理，則可能會發生這種情況。
您也可以設定 SDK 以從 JSON 文件載入取樣規則。對於無法使用 X-Ray 取樣的情況，軟體開發套件可以使用本機規則做為備份，或僅使用本機規則。
範例 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 服務管理。當您部署更多主機時，固定速率會乘以，使得難以控制記錄的資料量。
若要設定備份規則，請在您傳遞至記錄器的組態物件中定義文件的雜湊。
範例 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) 檔案來將其提取到您的應用程式中。
範例 config/sampling-rules.rb
my_sampling_rules = {
version: 1,
default: {
fixed_target: 1,
rate: 0.1
}
}範例 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。
範例 main.rb – 本機規則取樣
require 'aws-xray-sdk' require 'aws-xray-sdk/sampling/local/sampler' config = { sampler: LocalSampler.new, name: 'my app', } XRay.recorder.configure(config)
您也可以設定全域記錄器來停用所有傳入請求的抽樣和檢測。
範例 main.rb – 停用取樣
require 'aws-xray-sdk'
config = {
sampling: false,
name: 'my app',
}
XRay.recorder.configure(config)日誌
根據預設，記錄器會將資訊層級的事件輸出到 $stdout。您可以透過在傳遞至記錄器的組態物件中定義 logger
範例 main.rb – 記錄
require 'aws-xray-sdk'
config = {
logger: my_logger,
name: 'my app',
}
XRay.recorder.configure(config)當您手動產生子區段時，可使用除錯日誌來識別問題，例如未結束的子區段。
程式碼中的記錄器組態
可以從 XRay.recorder 上的 configure 方法取得其他可用設定。
範例 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 的組態物件中設定可用設定。
範例 config/initializers/aws_xray.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 篩選條件的區段命名策略中設定的服務名稱。 AWS_XRAY_DAEMON_ADDRESS– 設定 X-Ray 協助程式接聽程式的主機和連接埠。根據預設，軟體開發套件會將追蹤資料傳送至127.0.0.1:2000。如果您已設定協助程式在不同的連接埠上監聽，或在不同主機上執行，請使用此變數。AWS_XRAY_CONTEXT_MISSING– 設定為RUNTIME_ERROR以在未開啟區段時，檢測程式碼嘗試記錄資料時擲回例外狀況。有效值
-
RUNTIME_ERROR– 捨棄執行時間例外狀況。 -
LOG_ERROR– 記錄錯誤並繼續 （預設）。 -
IGNORE_ERROR– 忽略錯誤並繼續。
當您嘗試在未開啟請求時執行的啟動程式碼中使用檢測用戶端，或在產生新執行緒的程式碼中，可能會發生與缺少區段或子區段相關的錯誤。
-
環境變數會覆寫程式碼中所設的值。
