X-Ray SDK for Ruby の設定

X-Ray SDK for Ruby には、グローバルレコーダーを提供する 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)

また、コードで設定した値よりも優先される環境変数を使用して、レコーダーを設定することもできます。

また、SDK はプラグイン設定を使用して、セグメントの origin フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用してオリジンを決定します： ElasticBeanstalk > EKS > ECS > EC2。

サンプリングルール

SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。X-Ray コンソールに追加のルールを作成するをクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。

SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。

注記

SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに受信された最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。

JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、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
  }
}

この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、/api/move/以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。

ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが重複し、記録されるデータ量の制御が難しくなります。

バックアップルールを設定するには、レコーダーに渡す設定オブジェクトで、ドキュメントのハッシュを定義します。

例 main.rb – Backupルールの設定

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)

サンプリングルールを個別に保存するには、別個のファイルにハッシュを定義し、アプリケーションにそのハッシュをプルするようにファイルに要求します。

例 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)

ローカルルールのみを使用するには、サンプリングルールと 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 に出力します。レコーダーに渡す設定オブジェクトで、ロガーを定義してログ記録をカスタマイズできます。

例 main.rb – ログ記録

require 'aws-xray-sdk'
config = {
  logger: my_logger,
  name: 'my app',
}
XRay.recorder.configure(config)

デバッグログを使用して問題を識別します。たとえば、「サブセグメントを手動で生成する」場合にサブセグメントが閉じない問題などです。

コード内のレコーダー設定

追加の設定は、XRay.recorder の configure メソッドから利用できます。

• context_missing - 測定されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外のスローを回避するには、LOG_ERROR に設定します。

• daemon_address – X-Ray デーモンリスナーのホストとポートを設定します。

• name – SDK がセグメントに使用するサービス名を設定します。

• naming_pattern – 動的な命名を使用するようにドメイン名を設定します。

• plugins – プラグインを使用して、アプリケーションの AWS リソースに関する情報を記録します。

• sampling – false に設定してサンプリングを無効にします。

• sampling_rules – サンプリングルールを含むハッシュを設定します。

例 main.py – コンテキスト欠落例外を無効にする

require 'aws-xray-sdk'
config = {
  context_missing: 'LOG_ERROR'
}

XRay.recorder.configure(config)

Rails でのレコーダー設定

Rails フレームワークを使用している場合は、Ruby ファイルの app_root/initializers 以下で、グローバルレコーダーのオプションを設定できます。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
}

環境変数

環境変数を使用して、X-Ray SDK for Ruby を設定できます。SDK は次の変数をサポートしています。

• AWS_XRAY_TRACING_NAME – SDK がセグメントに使用するサービス名を設定します。サーブレットフィルタのセグメント命名ルールで設定したサービス名を上書きします。

• AWS_XRAY_DAEMON_ADDRESS –X-Ray デーモンリスナーのホストとポートを設定します。デフォルトでは、SDK は、トレースデータをに送信します127.0.0.1:2000。この変数は、デーモンを次のように構成している場合に使用します。別のポートでリッスンするまたは、別のホストで実行されている場合。

• AWS_XRAY_CONTEXT_MISSING – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、RUNTIME_ERROR に設定します。

  有効な値

  • RUNTIME_ERROR— ランタイム例外をスローします。

  • LOG_ERROR – エラーをログ記録して続行します (デフォルト)。

  • IGNORE_ERROR – エラーを無視して続行します。

  リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。

環境変数は、コードで設定される値を上書きします。