翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # X-Ray SDK for Ruby の設定 **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[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 for Ruby には、グローバルレコーダーを提供する `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/ja_jp/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)を使用して、レコーダーを設定することもできます。 また、SDK はプラグイン設定を使用して、セグメントの `origin` フィールドを設定します。これは、アプリケーションを実行する AWS リソースのタイプを示します。複数のプラグインを使用する場合、SDK は次の解決順序を使用して起点を決定します。ElasticBeanStalk > EKS > ECS > EC2。 ## サンプリングルール SDK は X-Ray コンソールで定義したサンプリングルールを使用し、記録するリクエストを決定します。デフォルトルールでは、最初のリクエストを毎秒トレースし、X-Ray にトレースを送信するすべてのサービスで追加のリクエストの 5% をトレースします。[X-Ray コンソールに追加のルールを作成する](xray-console-sampling.md)をクリックして、各アプリケーションで記録されるデータ量をカスタマイズします。 SDK は、定義された順序でカスタムルールを適用します。リクエストが複数のカスタムルールと一致する場合、SDK は最初のルールのみを適用します。 **注記** SDK が X-Ray に到達してサンプリングルールを取得できない場合、1 秒ごとに最初のリクエストのデフォルトのローカルルールに戻り、ホストあたりの追加リクエストの 5% に戻ります。これは、ホストがサンプリング API を呼び出す権限を持っていない場合や、SDK によって行われる API 呼び出しの TCP プロキシとして機能する X-Ray デーモンに接続できない場合に発生します。 JSON ドキュメントからサンプリングルールをロードするように SDK を設定することもできます。SDK は、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 } } ``` この例では、1 つのカスタムルールとデフォルトルールを定義します。カスタムルールでは、5 パーセントのサンプリングレートが適用され、`/api/move/`以下のパスに対してトレースするリクエストの最小数はありません。デフォルトのルールでは、1秒ごとの最初のリクエストおよび追加リクエストの 10 パーセントをトレースします。 ルールをローカルで定義することの欠点は、固定ターゲットが X-Ray サービスによって管理されるのではなく、レコーダーの各インスタンスによって個別に適用されることです。より多くのホストをデプロイすると、固定レートが重複し、記録されるデータ量の制御が難しくなります。 バックアップルールを設定するには、レコーダーに渡す設定オブジェクトで、ドキュメントのハッシュを定義します。 **Example 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) ``` サンプリングルールを個別に保存するには、別個のファイルにハッシュを定義し、アプリケーションにそのハッシュをプルするようにファイルに要求します。 **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) ``` ローカルルールのみを使用するには、サンプリングルールと `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` に出力します。レコーダーに渡す設定オブジェクトで、[ロガー](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.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` という名前の設定オブジェクトで利用可能な設定を行います。 **Example config/initializers/aws\$1xray.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 がセグメントに使用するサービス名を設定します。サーブレットフィルタの[セグメント命名ルール](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-naming)で設定したサービス名を上書きします。 + `AWS_XRAY_DAEMON_ADDRESS` –X-Ray デーモンリスナーのホストとポートを設定します。デフォルトでは、SDK は、トレースデータをに送信します`127.0.0.1:2000`。この変数は、デーモンを次のように構成している場合に使用します。[別のポートでリッスンする](xray-daemon-configuration.md)または、別のホストで実行されている場合。 + `AWS_XRAY_CONTEXT_MISSING` – 計測されたコードが、セグメントが開いていないときにデータを記録しようとした場合に例外をスローするには、`RUNTIME_ERROR` に設定します。 **有効な値** + `RUNTIME_ERROR`— ランタイム例外をスローします。 + `LOG_ERROR` – エラーをログ記録して続行します (デフォルト)。 + `IGNORE_ERROR` – エラーを無視して続行します。 リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。 環境変数は、コードで設定される値を上書きします。