翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AWS X-Ray SDK for Ruby **注記** X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日に、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 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は、Ruby ウェブアプリケーション用のライブラリです。トレースデータを作成して X-Ray デーモンに送信するためのクラスとメソッドを提供します。トレースデータには、アプリケーションによって提供される受信 HTTP リクエストに関する情報と、アプリケーションが AWS SDK、HTTP クライアント、またはアクティブなレコードクライアントを使用してダウンストリームサービスに対して行う呼び出しが含まれます。セグメントを手動で作成し、注釈およびメタデータにデバッグ情報を追加することもできます。 gemfile に追加し、`bundle install` を実行することで、SDK をダウンロードできます。 **Example Gemfile** ``` gem 'aws-sdk' ``` Rails を使用する場合は、最初に [X-Ray SDK ミドルウェアを追加](xray-sdk-ruby-middleware.md)して受信リクエストをトレースします。リクエストフィルタにより、[セグメント](xray-concepts.md#xray-concepts-segments)が作成されます。セグメントが開いている間、SDK クライアントのメソッドを使用してセグメントに情報を追加し、サブセグメントを作成してダウンストリーム呼び出しをトレースできます。また、SDK では、セグメントが開いている間にアプリケーションがスローする例外を自動的に記録します。Rails 以外のアプリケーションの場合、[手動でセグメントを作成](xray-sdk-ruby-middleware.md#xray-sdk-ruby-middleware-manual)することができます。 次に、X-Ray SDK を使用して AWS SDK for Ruby、関連するライブラリにパッチを適用するように[レコーダーを設定](xray-sdk-ruby-patching.md)して、、HTTP、SQL クライアントを計測します。計測されたクライアントを使用してダウンストリーム AWS のサービス またはリソースを呼び出すたびに、SDK は呼び出しに関する情報をサブセグメントに記録します。 AWS のサービス サービス内でアクセスするリソースは、トレースマップにダウンストリームノードとして表示され、個々の接続でエラーやスロットリングの問題を特定するのに役立ちます。 SDK を入手したら、[レコーダーを設定](xray-sdk-ruby-configuration.md)して動作をカスタマイズします。プラグインを追加して、アプリケーションを実行しているコンピューティングリソースに関するデータを記録したり、サンプリングルールを定義することでサンプリングの動作をカスタマイズしたり、ロガーを提供してアプリケーションログに SDK からの情報をより多くあるいは少なく表示することができます。 アプリケーションが[注釈やメタデータ](xray-sdk-ruby-segment.md)で行うリクエストや作業に関する追加情報を記録します。注釈は、[フィルタ式](xray-console-filters.md)で使用するためにインデックス化されたシンプルなキーと値のペアで、特定のデータが含まれているトレースを検索できます。メタデータのエントリは制約が緩やかで、JSON にシリアル化できるオブジェクトと配列全体を記録できます。 **注釈とメタデータ** 注釈およびメタデータとは、X-Ray SDK を使用してセグメントに追加する任意のテキストです。注釈は、フィルタ式用にインデックス付けされます。メタデータはインデックス化されませんが、X-Ray コンソールまたは API を使用して raw セグメントで表示できます。X-Ray への読み取りアクセスを許可した人は誰でも、このデータを表示できます。 コードに多数の計測されたクライアントがある場合、単一のリクエストセグメントには計測されたクライアントで行われた呼び出しごとに 1 個の多数のサブセグメントを含めることができます。[カスタムサブセグメント](xray-sdk-ruby-subsegments.md)で、クライアント呼び出しをラップすることで、サブセグメントを整理してグループできます。関数全体またはコードの任意のセクションのサブセグメントを作成し、親セグメントにすべてのレコードを記述する代わりにサブセグメントにメタデータと注釈を記録できます。 SDK のクラスとメソッドのリファレンス ドキュメントについては、[AWS X-Ray SDK for Ruby API リファレンス](https://docs.aws.amazon.com/xray-sdk-for-ruby/latest/reference)を参照してください。 ## 要件 X-Ray SDK では Ruby 2.3 以降が必要です。また、次のライブラリと互換性があります。 + AWS SDK for Ruby バージョン 3.0 以降 + Rails バージョン 5.1 以降 # 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` – エラーを無視して続行します。 リクエストが開かれていないときに実行されるスタートアップコード、または新しいスレッドを生成するコードで測定されたクライアントを使用しようとしたときに発生する可能性があるセグメントまたはサブセグメントの欠落に関連するエラー。 環境変数は、コードで設定される値を上書きします。 # 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 を使用して、アプリケーションが Amazon EC2 の EC2 インスタンス AWS Elastic Beanstalk、または Amazon ECS で処理する受信 HTTP リクエストをトレースできます。 Amazon EC2 Rails を使用する場合は、Rails ミドルウェアを使用して、受信 HTTP リクエストを計測します。ミドルウェアをアプリケーションに追加してセグメント名を設定すると、X-Ray SDK for Ruby はサンプリングされたリクエストごとにセグメントを作成します。追加実装で作成されたセグメントは、HTTP リクエストおよびレスポンスに関する情報を提供するリクエストレベルのセグメントのサブセグメントになります。この情報には、時間、メソッド、リクエストの処理などがあります。 各セグメントには、サービスマップ内のアプリケーションを識別する名前があります。セグメントの名前は静的に指定することも、受信リクエストのホストヘッダーに基づいて動的に名前を付けるように SDK を設定することもできます。動的ネーミングでは、リクエスト内のドメイン名に基づいてトレースをグループ化でき、名前が予想されるパターンと一致しない場合（たとえば、ホストヘッダーが偽造されている場合）、デフォルト名を適用できます。 **転送されたリクエスト** ロードバランサーまたは他の仲介者がアプリケーションにリクエストを転送する場合、X-Ray は、クライアントの IP をIP パケットの送信元 IP からではなく、リクエストの`X-Forwarded-For`ヘッダーから取得します。転送されたリクエストについて記録されたクライアント IP は偽造される可能性があるため、信頼されるべきではありません。 リクエストが転送されると、それを示す追加フィールドが SDK によってセグメントに設定されます。セグメントのフィールド `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 を設定できます。動的ネーミングストラテジーにより、SDK は予想されるパターンに一致するリクエストにホスト名を使用し、そうでないリクエストにデフォルト名を適用できます。 たとえば、3 つのサブドメイン（`www.example.com`,`api.example.com`,および`static.example.com`）に対してリクエストを処理する単一のアプリケーションがあるとします。動的ネーミングストラテジーをパターン `*.example.com` で使用して、異なる名前を持つ各サブドメインのセグメントを識別することができます。結果的にはサービスマップ上に 3 つのサービスノードを作成することになります。アプリケーションがパターンと一致しないホスト名のリクエストを受信すると、指定したフォールバック名を持つ 4 番目のノードがサービスマップに表示されます。 すべてのリクエストセグメントに同じ名前を使用するには、[前のセクション](#xray-sdk-ruby-middleware-rails)で示されたように、レコーダーを設定するときにアプリケーションの名前を指定します｡ 動的命名ルールは、ホスト名と一致するようパターンを定義し、HTTP リクエストのホスト名がパターンと一致しない場合はデフォルトの名前を使用します。セグメントに動的に名前を付けるには、config ハッシュで命名パターンを指定します。 **Example main.rb – 動的命名** ``` config = { naming_pattern: '*mydomain*', name: 'my app', } XRay.recorder.configure(config) ``` パターン内で任意の文字列に一致させるには「\$1」を､また、任意の 1 文字に一致させるには「?」を使用することができます。 **注記** コードで定義したデフォルトのサービス名は、`AWS_XRAY_TRACING_NAME` [環境変数](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-envvars)で上書きできます。 # ダウンストリームコールを実装するためのライブラリへのパッチ適用 **注記** 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 を使用して、アプリケーションが使用するライブラリにパッチを適用します。X-Ray SDK for Ruby では、次のライブラリにパッチを適用できます。 **サポートされているライブラリ** + `[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)` – クライアントを計測 AWS SDK for Ruby します。 パッチ適用されたライブラリを使用すると、X-Ray SDK for Ruby はコールのサブセグメントを作成し、リクエストとレスポンスの情報を記録します。SDK ミドルウェアまたは `XRay.recorder.begin_segment` のコールのいずれかから、サブセグメントを作成するために SDK でセグメントを使用できる必要があります。 ライブラリにパッチを適用するには、X-Ray レコーダーに渡す設定オブジェクトでそのパッチを指定します。 **Example main.rb – パッチライブラリ** ``` require 'aws-xray-sdk' config = { name: 'my app', patch: %I[net_http aws_sdk] } XRay.recorder.configure(config) ``` # X-Ray AWS SDK for Ruby を使用した SDK 呼び出しのトレース **注記** 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)」を参照してください。 アプリケーションが AWS のサービス を呼び出してデータの保存、キューへの書き込み、または通知の送信を行うと、X-Ray SDK for Ruby は[サブセグメントのダウンストリームの呼び出しを追跡します](xray-sdk-ruby-subsegments.md)。これらのサービス内でアクセスするトレースされた AWS のサービス およびリソース (Amazon S3 バケットや Amazon SQS キューなど) は、X-Ray コンソールのトレースマップにダウンストリームノードとして表示されます。 X-Ray SDK for Ruby は、ライブラリにパッチを適用すると、すべての AWS SDK クライアントを自動的に計測します。 [`aws-sdk`](xray-sdk-ruby-patching.md)個々のクライアントを実装することはできません。 すべてのサービスにおいて、X-Ray コンソールでコールされた API の名前を確認できます。サービスのサブセットの場合、X-Ray SDK はセグメントに情報を追加して、サービスマップでより細かく指定します。 たとえば、実装された DynamoDB クライアントでコールすると、SDK はテーブルをターゲットとするコールのセグメントにテーブル名を追加します。コンソールで、各テーブルはサービスマップ内に個別のノードとして表示され、テーブルをターゲットにしないコール用の汎用の 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 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)」を参照してください。 サブセグメントはリクエストを処理するために行われた作業の詳細を含んだトレースの[セグメント](xray-concepts.md#xray-concepts-segments)を拡張します。計測済みクライアント内で呼び出しを行うたびに、X-Ray SDK によってサブセグメントに生成された情報が記録されます。追加のサブセグメントを作成して、他のサブセグメントをグループ化したり、コードセクションのパフォーマンスを測定したり、注釈とメタデータを記録したりできます。 サブセグメントを管理するには、`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 SDK によってその 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" } }, ``` # 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 が作成するセグメントまたは作成するカスタムサブセグメントに、注釈およびメタデータを追加できます。 **注釈**は文字列、数値、またはブール値を使用したキーと値のペアです。注釈は、[フィルタ式](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** + [X-Ray SDK for Ruby で注釈を記録する](#xray-sdk-ruby-segment-annotations) + [X-Ray SDK for Ruby でメタデータを記録する](#xray-sdk-ruby-segment-metadata) + [X-Ray SDK for Ruby でユーザー ID を記録する](#xray-sdk-ruby-segment-userid) ## X-Ray SDK for Ruby で注釈を記録する 注釈を使用して、検索用にインデックスを作成するセグメントまたはサブセグメントに情報を記録します。 **注釈の要件** + **キー** – 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 ``` SDK は、セグメントドキュメントの `annotations` オブジェクトにキーと値のペアとして、注釈を記録します。同じキーで `add_annotations` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。 特定の値を持つ注釈のあるトレースを見つけるには、`annotation[key]`フィルタ式[の ](xray-console-filters.md) キーワードを使用します。 ## X-Ray SDK for Ruby でメタデータを記録する メタデータを使用して、検索用にインデックスを作成する必要のないセグメントまたはサブセグメントに情報を記録します。メタデータ値は、文字列、数値、ブール値、または JSON オブジェクトや 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` を 2 回呼び出すと、同じセグメントまたはサブセグメントに以前記録された値が上書きされます。 ## X-Ray SDK for Ruby でユーザー ID を記録する リクエストセグメントにユーザー ID を記録して、リクエストを送信したユーザーを識別します。 **ユーザー ID を記録するには** 1. `xray_recorder` から現在のセグメントへの参照を取得します。 ``` require 'aws-xray-sdk' ... document = XRay.recorder.current_segment ``` 1. セグメントのユーザーフィールドを、リクエストを送信したユーザーの文字列 ID に設定します。 ``` segment.user = 'U12345' ``` コントローラーでユーザーを設定し、アプリケーションがリクエストの処理を開始するとすぐに、ユーザー ID を記録できます。 ユーザー ID のトレースを見つけるには、`user`フィルタ式[で、](xray-console-filters.md) キーワードを使用します。