翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# インターフェイスの選択
AWS X-Ray は、アプリケーションがどのように機能し、他の のサービスやリソースとどのように相互作用するかに関するインサイトを提供します。アプリケーションの計測または設定を実行すると、X-Ray はアプリケーションがリクエストを処理するときのトレースデータを収集します。このトレースデータを分析すると、パフォーマンスの問題を特定し、エラーのトラブルシューティングを行い、リソースを最適化できます。このガイドでは、以下のガイドラインにより X-Ray を操作する方法について説明します。
+ すぐに使用を開始する場合や、構築済みの視覚化を使用して基本的なタスクを実行できる AWS マネジメントコンソール 場合は、 を使用します。
+ X-Ray コンソールのすべての機能を含む最新のユーザーエクスペリエンスを使用する場合は、Amazon CloudWatch コンソールを選択します。
+ より単純なインターフェイスを使用、または X-Ray の操作方法を変更しない場合は、X-Ray コンソールを使用します。
+ が提供するよりも多くのカスタムトレース、モニタリング、またはログ記録機能が必要な場合は、 SDK を使用します AWS マネジメントコンソール 。
+ AWS セキュリティと最適化のレイヤーを追加したオープンソース OpenTelemetry SDK に基づく、ベンダーに依存しない SDK を使用する場合は、ADOT SDK を選択します。
+ より単純な SDK が必要な場合、またはアプリケーションコードを更新しない場合は、X-Ray SDK を選択します。
+ SDK がご使用のアプリケーションのプログラミング言語をサポートしていない場合は、X-Ray API オペレーションを使用します。
次の図は、X-Ray の操作方法の選択に役立ちます。
![\[X-Ray は、アプリケーションリクエストに関する詳細情報を表示します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/xray-choose-interface.png)
**Topics**
+ [SDK を使用する](aws-xray-interface-sdk.md)
+ [コンソールを使用する](aws-xray-interface-console.md)
+ [X-Ray API を使用する](xray-api.md)
# 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 マネジメントコンソールで利用可能なものよりも多くのカスタムトレース、モニタリング、またはログ機能が必要な場合は、SDK を使用します。 AWS SDK を使用して、X-Ray APIs を使用するプログラムを開発することもできます。 AWS Distro for OpenTelemetry (ADOT) SDK または X-Ray SDK のいずれかを使用できます。
SDK を使用する場合は、アプリケーションを計測するときと、コレクターまたはエージェントを設定するときに、ワークフローにカスタマイズを追加できます。SDK を使用すると、 AWS マネジメントコンソールでは実行できない以下のタスクを実行できます。
+ カスタムメトリクスの公開 - 1 秒までの高解像度でメトリクスをサンプリングして、複数のディメンションを使用しメトリクスに関する情報を追加し、データポイントを統計セットに集約します。
+ コレクターのカスタマイズ - レシーバー、プロセッサ、エクスポーター、コネクタなど、コレクターの設定の任意の部分をカスタマイズします。
+ 計測のカスタマイズ - セグメントとサブセグメントをカスタマイズして、カスタムキーと値のペアを属性として追加し、カスタムメトリクスを作成します。
+ プログラムでサンプリングルールを作成および更新します。
AWS セキュリティと最適化のレイヤーを追加した標準化ADOTされた SDK を柔軟に使用する場合は、 OpenTelemetry SDK を使用します。 AWS Distro for OpenTelemetry (ADOT) SDK はベンダーに依存しないパッケージで、コードを再計測することなく、他のベンダーや非AWS サービスのバックエンドと統合できます。
X-Ray SDK を既に使用していて、 AWS バックエンドのみと統合し、X-Ray またはアプリケーションコードの操作方法を変更しない場合は、X-Ray SDK を使用します。
各機能の詳細については、「[AWS Distro for OpenTelemetry と X-Ray SDKs の選択](xray-instrumenting-your-app.md#xray-instrumenting-choosing)」を参照してください。
## ADOT SDK を使用する
ADOT SDK は、バックエンドサービスにデータを送信する一連のオープンソース APIs、ライブラリ、エージェントです。 ADOTは、 でサポートされ AWS、複数のバックエンドとエージェントと統合され、OpenTelemetryコミュニティによって管理される多数のオープンソースライブラリを提供します。ADOT SDK を使用してご使用のアプリケーションを計測して、ログ、メタデータ、メトリクス、トレースを収集します。ADOT を使用してサービスをモニタリングし、CloudWatch のメトリクスに基づいてアラームを設定することもできます。
ADOT SDK を使用する場合は、エージェントとの組み合わせで、次のオプションがあります。
+ [CloudWatch エージェント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)で ADOT SDK を使用する - 推奨。
+ [ADOT コレクター](https://aws-otel.github.io/docs/getting-started/collector)で ADOT SDK を使用する – セキュリティと最適化の AWS レイヤーでベンダーに依存しないソフトウェアを使用する場合は推奨されます。
ADOT SDK を使用する場合は、以下を実行します。
+ ADOT SDK を使用してご使用のアプリケーションを計測します。詳細については、「[ADOT 技術ドキュメント](https://aws-otel.github.io/docs/introduction)」の、ご使用のプログラミング言語のドキュメントを参照してください。
+ ADOT Collector を設定して、収集データの送信先を指定します。
ADOT コレクターは、データを受信すると、ADOT設定で指定したバックエンドに送信します。 は AWS、次の図に示すように、外部のベンダーを含む複数のバックエンドにデータを送信ADOTできます。
![\[ADOT Collector は、アプリケーションを計測してコレクターを設定するときにカスタマイズできます。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/adot-sdk.png)
AWS は定期的に を更新ADOTして機能を追加し、[OpenTelemetry](https://opentelemetry.io/docs/) フレームワークに合わせます。ADOT の更新および今後の開発計画は一般公開[ロードマップ](https://github.com/orgs/aws-observability/projects/4)の一部です。ADOT は以下を含むいくつかのプログラミング言語をサポートしています。
+ Go
+ Java
+ JavaScript
+ Python
+ .NET
+ Ruby
+ PHP
Python を使用する場合、ADOT はアプリケーションを自動的に計測できます。の使用を開始するにはADOT、[https://aws-otel.github.io/docs/introduction](https://aws-otel.github.io/docs/introduction)[AWS 「 Distro for OpenTelemetry Collector の概要と開始方法](https://aws-otel.github.io/docs/getting-started/collector)」を参照してください。
## X-Ray SDK を使用する
X-Ray SDK は、バックエンドサービスに AWS データを送信する一連の AWS APIsとライブラリです。X-Ray SDK を使用してアプリケーションを計測しトレースデータを収集します。X-Ray SDK を使用したログまたはメトリクスデータの収集はできません。
X-Ray SDK を使用する場合は、エージェントとの組み合わせで、次のオプションがあります。
+ [AWS X-Ray デーモン](xray-daemon.md) で X-Ray SDK を使用する - アプリケーションコードを更新しない場合はこれを使用します。
+ CloudWatch エージェントで X-Ray SDK を使用する - (推奨) CloudWatch エージェントは X-Ray SDK と互換性があります。
SDK を使用する場合は、以下を実行します。
+ X-Ray SDK を使用してご使用のアプリケーションを計測します。
+ コレクターを設定して、収集データの送信先を指定します。CloudWatch エージェントまたは X-Ray デーモンを使用すると、トレース情報を収集できます。
コレクターまたはエージェントがデータを受信すると、エージェント設定で指定した AWS バックエンドに送信されます。次の図に示すように、X-Ray SDK は AWS バックエンドにのみデータを送信できます。
![\[CloudWatch エージェントまたは X-Ray デーモンのいずれかで、X-Ray SDK を使用します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/xray-sdk.png)
Java を使用する場合は、X-Ray SDK を使用してアプリケーションを自動的に計測できます。X-Ray SDK の使用を開始する場合は、次のプログラミング言語に関連付けられているライブラリを参照してください。
+ [Go](xray-go.md)
+ [Java](xray-java.md)
+ [Node.js](xray-nodejs.md)
+ [Python](xray-python.md)
+ [.NET](xray-dotnet.md)
+ [Ruby](xray-ruby.md)
# コンソールを使用する
グラフィカルユーザーインターフェイス (GUI) で必要なコーディングを最小限にする場合は、コンソールを使用します。X-Ray を初めて使用するユーザーは、構築済みの視覚化を使用すると、基本的なタスクをすばやく開始できます。コンソールから以下の内容を直接実行できます。
+ X-Ray を有効にします。
+ アプリケーションのパフォーマンスについてハイレベルの概要を表示します。
+ アプリケーションのヘルスステータスを確認します。
+ ハイレベルのエラーを特定します。
+ 基本的トレースの概要を表示します。
[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) の Amazon CloudWatch コンソールまたは [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) の X-Ray コンソールを使用して、X-Ray を操作できます。
## Amazon CloudWatch コンソールを使用する
CloudWatch コンソールには、X-Ray コンソールから再設計された、使いやすい新規 X-Ray 機能が含まれています。CloudWatch コンソールを使用する場合は、X-Ray トレースデータと共に、CloudWatch ログとメトリクスを表示できます。CloudWatch コンソールを使用して以下が含まれるデータを表示および分析します。
+ X-Ray トレース - アプリケーションがリクエストを処理する際、アプリケーションに関連付けられたトレースを表示、分析、フィルタリングします。これらのトレースを使用して、高レイテンシーの検出、エラーのデバッグ、アプリケーションワークフローの最適化を実行します。トレースマップとサービスマップを表示して、ご使用のアプリケーションワークフローの視覚的表現を確認します。
+ ログ - ご使用のアプリケーションが生成するログを表示、分析、フィルタリングします。ログを使用してエラーをトラブルシューティングし、特定のログ値に基づくモニタリングを設定します。
+ メトリクス - ご使用のリソースが出力するメトリクスを使用、または独自のメトリクスを作成して、アプリケーションのパフォーマンスを測定およびモニタリングします。これらのメトリクスをグラフとチャートで表示します。
+ ネットワークとインフラストラクチャのモニタリング - コンテナ化されたアプリケーション、他の AWS サービス、クライアントを含む主要なネットワークの機能停止とインフラストラクチャの正常性やパフォーマンスのモニタリングを実行します。
+ 次の **X-Ray コンソールを使用する**セクションに記載されている X-Ray コンソールのすべての機能。
CloudWatch コンソールの詳細については、「[CloudWatch の開始方法](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html)」を参照してください。
[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) で Amazon CloudWatch コンソールにログインします。
## X-Ray コンソールを使用する
X-Ray コンソールはアプリケーションリクエストの分散トレースを提供しています。より単純なコンソールエクスペリエンスにする場合、またはアプリケーションコードを更新しない場合は、X-Ray コンソールを使用します。AWS は X-Ray コンソールの開発を中止しました。X-Ray コンソールには計測されたアプリケーションのための以下の機能が含まれています。
+ [Insights](xray-console-insights.md) - アプリケーションのパフォーマンスの異常を自動的に検出して根本的な原因を見つけます。Insights は、**[Insights]** の CloudWatch コンソールに含まれています。詳細については、[X-Ray コンソールを使用する](#xray-console) の「**X-Ray Insights を使用する**」を参照してください。
+ サービスマップ - アプリケーションのグラフィカル構造、およびクライアント、リソース、サービス、依存関係との接続を表示します。
+ トレース - アプリケーションがリクエスト処理の際に生成するトレースの概要を参照します。トレースデータを使用して、HTTP レスポンスや応答時間などの、基本的なメトリクスに対するアプリケーションのパフォーマンスを把握します。
+ 分析 - 応答時間の分散のグラフを使用して、トレースデータを解釈、調査、分析します。
+ 設定 - カスタマイズしたトレースを作成して次のデフォルト設定を変更します。
+ サンプリング - トレース情報のためのアプリケーションサンプリング頻度を定義するルールを作成します。詳細については、[X-Ray コンソールを使用する](#xray-console) の「**サンプリングルールを設定する**」を参照してください。
+ [暗号化](xray-console-encryption.md) - AWS Key Management Service を使用して監査または無効化できるキーで、保管中のデータを暗号化します。
+ グループ - フィルター式を使用して、URL の名前や応答時間などの一般的な特徴量を持つトレースのグループを定義します。詳細については、「[グループを設定する](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups)」を参照してください。
[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) で X-Ray コンソールにログインします。
## X-Ray コンソールを使用する
X-Ray コンソールを使用して、アプリケーションが処理するリクエストのサービスと関連するトレースのマップを表示し、トレースが X-Ray に送信される方法に影響するグループとサンプリングルールを設定します。
**注記**
X-Ray Service マップと CloudWatch ServiceLens マップは、Amazon CloudWatch コンソール内の X-Ray トレースマップに統合済みです。[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch/)を開き、左側のナビゲーションペインから **[X-Ray トレース]** の下の **[トレースマップ]** を選択します。
CloudWatch には、アプリケーションサービス、クライアント、Synthetics Canary、サービスの依存関係を検出してモニタリングできる [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) が含まれるようになりました。Application Signals を使用すると、サービスのリストやビジュアルマップを確認したり、サービスレベル目標 (SLO) に基づくヘルスメトリクスを表示したり、ドリルダウンして相関関係のある X-Ray トレースを確認したりして、より詳細なトラブルシューティングを行うことができます。
X-Ray コンソールの主要ページはトレースマップで、アプリケーションによって生成されたトレースデータから X-Ray が生成した JSON サービスグラフがビジュアルで表現されます。マップは、リクエストを処理するアカウント内の各アプリケーションのサービスノード、リクエストの送信元を示すアップストリームクライアントノード、リクエストの処理中にアプリケーションが使用するウェブサービスとリソースを示すダウンストリームサービスノードで構成されます。他にも、トレースとトレースの詳細を表示したり、グループやサンプリングルールを設定したりするためのページがあります。
X-Ray のコンソールエクスペリエンスを表示し、以下のセクションの CloudWatch コンソールと比較します。
**Topics**
+ [Amazon CloudWatch コンソールを使用する](#aws-xray-interface-console-cw)
+ [X-Ray コンソールを使用する](#xray-console)
+ [X-Ray コンソールを使用する](#xray-console-explore)
+ [X-Ray トレースマップの使用](xray-console-servicemap.md)
+ [トレースとトレースの詳細の表示](xray-console-traces.md)
+ [フィルター式の使用](xray-console-filters.md)
+ [クロスアカウントトレース](xray-console-crossaccount.md)
+ [イベント駆動型アプリケーションのトレース](xray-tracelinking.md)
+ [レイテンシーヒストグラムの使用](xray-console-histograms.md)
+ [X-Ray インサイトの使用](xray-console-insights.md)
+ [Analytics コンソールとのやり取り](xray-console-analytics.md)
+ [グループの設定](xray-console-groups.md)
+ [サンプリングルールの設定](xray-console-sampling.md)
+ [アダプティブサンプリングの設定](xray-adaptive-sampling.md)
+ [コンソールのディープリンク](xray-console-deeplinks.md)
# X-Ray トレースマップの使用
X-Ray トレースマップを表示して、エラーが発生しているサービス、高レイテンシーの接続、失敗したリクエストのトレースを識別します。
**注記**
CloudWatch には、アプリケーションサービス、クライアント、Synthetics Canary、サービスの依存関係を検出してモニタリングできる [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) が含まれるようになりました。Application Signals を使用すると、サービスのリストやビジュアルマップを確認したり、サービスレベル目標 (SLO) に基づくヘルスメトリクスを表示したり、ドリルダウンして相関関係のある X-Ray トレースを確認したりして、より詳細なトラブルシューティングを行うことができます。
X-Ray サービスマップと CloudWatch ServiceLens マップは、Amazon CloudWatch コンソール内の X-Ray トレースマップに結合されました。[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch/)を開き、左側のナビゲーションペインから **[X-Ray トレース]** の下の **[トレースマップ]** を選択します。
## トレースマップの表示
トレースマップは、アプリケーションによって生成されたトレースデータをビジュアルに表現したものです。リクエストを処理するサービスノード、リクエストの送信元を示すアップストリームクライアントノード、リクエストの処理中にアプリケーションが使用するウェブサービスとリソースを示すダウンストリームサービスノードがマップに表示されます。
トレースマップには、Amazon SQS と Lambda を使用するイベント駆動型アプリケーション全体のトレースの接続されたビューが表示されます。詳細については、「[イベント駆動型アプリケーションのトレース](xray-tracelinking.md)」を参照してください。トレースマップは[クロスアカウントトレーシング](xray-console-crossaccount.md)もサポートし、複数のアカウントのノードを 1 つのマップに表示します。
------
#### [ CloudWatch console ]
**CloudWatch コンソールを使用してトレースマップを表示するには**
1. [CloudWatch コンソールを開きます](https://console.aws.amazon.com/cloudwatch/)。左側のナビゲーションペインの **[X-Ray トレース]** セクションで **[トレースマップ]** を選択します。
![\[CloudWatch コンソールトのレースマップページ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-servicemap-cw.png)
1. そのノードのリクエスト、または 2 つのノード間のエッジを表示するサービスノードを選択して、やり取りされた接続のリクエストを表示します。
1. メトリクス、アラート、応答時間の分布のタブなど、追加情報がトレースマップの下に表示されます。**[メトリクス]** タブでは、各グラフ内の範囲を選択してドリルダウンして詳細を表示するか、**[障害]** または **[エラー]** オプションを選択してトレースをフィルタリングします。**[応答時間の分布]** タブでは、応答時間でトレースをフィルタリングするグラフ内の範囲を選択します。
![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-cw-servicemap-node-detail.png)
1. **[トレースを表示]** を選択してトレースを表示するか、フィルターが適用されている場合は **[フィルタリングされたトレースの表示]** を選択します。
1. **[ログを表示]** を選択すると、選択したノードに関連付けられた CloudWatch ログが表示されます。すべてのトレースマップノードがログの表示をサポートしているわけではありません。詳細については、「[CloudWatch ログのトラブルシューティング](xray-troubleshooting.md#xray-troubleshooting-Nologs)」を参照してください。
トレースマップでは、各ノード内の問題を色分けして示します。
+ **赤**は、サーバー障害 (500 系のエラー)
+ **黄**は、クライアントエラー (400 系のエラー)
+ **紫**は、スロットリングエラー (429 リクエストが多すぎる)
トレースマップが大きい場合は、画面のコントロールまたはマウスを使用して、マップを拡大/縮小したり移動したりします。
------
#### [ X-Ray console ]
**サービスマップを表示するには**
1. [[X-Ray console (X-Ray コンソール)](https://console.aws.amazon.com/xray/home#)] を開きます。デフォルトでは、サービスマップが表示されます。左側のナビゲーションペインで **[サービスマップ]** を選択することもできます。
![\[X-Ray コンソールサービスマップページ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-servicemap-xray.png)
1. そのノードのリクエスト、または 2 つのノード間のエッジを表示するサービスノードを選択して、やり取りされた接続のリクエストを表示します。
1. レスポンスディストリビューション[ヒストグラム](xray-console-histograms.md)を使用して、期間ごとにトレースをフィルタリングし、トレースを表示するステータスコードを選択します。[**View traces (トレースの表示)**] を選択し、フィルタ式を適用してトレースリストを開きます。
![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png)
このサービスマップは、各ノードの状態をエラーと障害に対する正常な呼び出しの比率に基づいて色分けしたものです。
+ **緑**は、正常な呼び出し
+ **赤**は、サーバー障害 (500 系のエラー)
+ **黄**は、クライアントエラー (400 系のエラー)
+ **紫**は、スロットリングエラー (429 リクエストが多すぎる)
サービスマップが大きい場合は、画面のコントロールまたはマウスを使用して、マップを拡大/縮小したり移動したりします。
------
**注記**
X-Ray トレースマップは、最大 10,000 個のノードを表示できます。まれに、サービスノードの総数がこの制限を超えると、エラーが表示され、コンソールに完全なトレースマップを表示できない場合があります。
## グループ別のトレースマップのフィルタリング
[フィルター式](xray-console-filters.md)を使用すると、グループに含めるトレースの基準を定義できます。次のステップに従って、トレースマップにその特定のグループを表示します。
------
#### [ CloudWatch console ]
トレースマップの左上にあるグループフィルターからグループ名を選択します。
![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-servicemap-groups-cw.png)
------
#### [ X-Ray console ]
検索バーの左側にあるドロップダウンメニューからグループ名を選択します。
![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-select-console.png)
------
これで、サービスマップがフィルタリングされ、選択したグループのフィルター式と一致するトレースが表示されます。
## トレースマップの凡例とオプション
トレースマップには、マップ表示をカスタマイズするための凡例といくつかのオプションがあります。
------
#### [ CloudWatch console ]
マップの右上にある **[凡例とオプション]** ドロップダウンを選択します。以下のノード内に表示する内容を選択します。
+ **メトリクス**には、選択した時間範囲の平均応答時間と 1 分あたりに送信されたトレース数が表示されます。
+ **ノード**には、各ノード内のサービスアイコンが表示されます。
**[設定]** ペインから追加のマップ設定を選択します。このペインには、マップの右上にある歯車アイコンからアクセスできます。これらの設定には、各ノードのサイズを決定するために使用するメトリクスや、マップに表示する Canary の選択などがあります。
------
#### [ X-Ray console ]
サービスマップの凡例を表示するには、マップの右上にある **[マップの凡例]** リンクを選択します。トレースマップの右下で、次のようなサービスマップのオプションを選択できます。
+ **サービスアイコン** 各ノード内の表示内容を切り替えて、サービスアイコンを表示するか、または選択した時間範囲の平均応答時間と 1 分あたりに送信されたトレース数を表示します。
+ **ノードサイズ : なし** すべてのノードを同じサイズに設定します。
+ **ノードサイズ : ヘルス** エラー、障害、スロットリングされたリクエストなど、影響を受けるリクエストの数に応じてノードのサイズを設定します。
+ **ノードサイズ : トラフィック** リクエストの合計数に応じてノードのサイズを設定します。
------
# トレースとトレースの詳細の表示
X-Ray コンソールの **[トレース] **ページを使用して、URL、レスポンスコード、トレース概要のその他のデータでトレースを検索します。トレースリストからトレースを選択すると、**[トレースの詳細]** ページには、選択したトレースに関係するサービスノードのマップと、トレースセグメントのタイムラインが表示されます。
## トレースの表示
------
#### [ CloudWatch console ]
**CloudWatch コンソールでトレースを表示するには**
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインで、**[X-Ray トレース]** を選択してから **[トレース]** を選択します。グループでフィルタリングすることも、[フィルター式](xray-console-filters.md)を入力することもできます。これにより、ページ下部の **[トレース]** セクションに表示されるトレースがフィルタリングされます。
または、サービスマップを使用して特定のサービスノードに移動してから、トレースを表示できます。これにより、クエリを既に適用済みの **[トレース]** ページが開きます。
1. **[クエリリファイナー]** セクションでクエリを絞り込みます。共通属性でトレースをフィルタリングするには、**[クエリを絞り込む]** の横にある下矢印からオプションを選択します。オプションは以下のとおりです。
+ ノード - サービスノードでトレースをフィルタリングします。
+ リソース ARN - トレースに関連付けられたリソースでトレースをフィルタリングします。これらのリソースの例には、Amazon Elastic Compute Cloud (Amazon EC2) インスタンス、AWS Lambda 関数、または Amazon DynamoDB テーブルが含まれます。
+ ユーザー - ユーザー ID でトレースをフィルタリングします。
+ エラー根本原因メッセージ - エラー根本原因でトレースをフィルタリングします。
+ URL - アプリケーションで使用される URL パスでトレースをフィルタリングします。
+ HTTP ステータスコード - アプリケーションが返した HTTP ステータスコードでトレースをフィルタリングします。カスタムレスポンスコードを指定、または以下から選択できます。
+ `200` - リクエストが成功しました。
+ `401` - リクエストには有効な認証情報がありませんでした。
+ `403` - リクエストには有効なアクセス許可がありませんでした。
+ `404` - サーバーがリクエストされたリソースを見つけることができませんでした。
+ `500` - サーバーにより予期しない状態が検出され、内部エラーを生成しました。
1 つまたは複数のエントリを選択してから **[クエリに追加]** を選択すると、ページ上部のフィルター式に追加されます。
1. 単一トレースを検索するには、[トレース ID](xray-api-sendingdata.md#xray-api-traceids) をクエリフィールドに直接入力します。X-Ray 形式または World Wide Web Consortium (W3C) 形式を使用できます。例えば、[AWS Distro for OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) を使用して作成されたトレースは W3C 形式です。
**注記**
W3C 形式のトレース ID で作成されたトレースをクエリするときは、一致するトレースが X-Ray 形式でコンソールに表示されます。例えば、W3C 形式で `4efaaf4d1e8720b39541901950019ee5` にクエリを実行すると、コンソールには X-Ray に相当する `1-4efaaf4d-1e8720b39541901950019ee5` が表示されます。
1. **[クエリを実行]** を選択すると、いつでもページ下部の **[トレース]** セクションに一致するトレースのリストが表示されます。
1. 単一トレースの **[トレースの詳細]** ページを表示するには、リストからトレース ID を選択します。
次の図は、トレースに関連付けられたサービスノードと、トレースを構成するセグメントが取得したパスを表すノード間のエッジを含む、**[トレースマップ]** を示しています。**[トレース概要]** が **[トレースマップ]** に続きます。概要には、サンプルの `GET` オペレーション、**[レスポンスコード]**、トレースの実行に要した **[所要時間]**、リクエストの **[経過時間]** に関する情報が含まれます。**[セグメントのタイムライン]** がトレースのセグメントとサブセグメントの所要時間を示す **[トレース概要]** に続きます。
![\[トレースマップ、概要、セグメントのタイムラインは、トレース内のサービスノードとセグメントに関する情報を列挙します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/xray-trace-details-cw.png)
Amazon SQS と Lambda を使用するイベント駆動型アプリケーションがある場合は、**[トレースマップ]** で各リクエストのトレースが接続された表示を確認できます。マップでは、メッセージプロデューサーからのトレースは AWS Lambda コンシューマーからのトレースにリンクされ、破線のエッジとして表示されます。イベント駆動型アプリケーションの詳細については、「[イベント駆動型アプリケーションのトレース](xray-tracelinking.md)」を参照してください。
**[トレース]** と **[トレースの詳細]** ページは[クロスアカウントトレース](xray-console-crossaccount.md)にも対応しており、これにより複数のアカウントのトレースをトレースリストと 1 つのトレースマップ内に表示できます。
------
#### [ X-Ray console ]
**X-Ray コンソールでトレースを表示するには**
1. X-Ray コンソールの[トレース](https://console.aws.amazon.com/xray/home#/traces)ページを開きます。**[トレース概要]** パネルには、**[エラーの根本原因]**、**[ResourceARN]**、**[InstanceId]** などの、共通機能でグループ化されたトレースのリストが表示されます。
1. トレースのグループ化されたセットを表示する共通機能を選択するには、**[グループ別]** の横にある下矢印を展開します。次の図は、[AWS X-Ray サンプルアプリケーション](xray-scorekeep.md) の URL でグループ化されたトレースのトレース概要と、関連するトレースのリストを示しています。
![\[URL でグループ化されたトレースの次は、[ID]、[方法]、[応答] などの詳細を含むトレースリストです。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-traces.png)
1. トレースの **[ID]** を選択すると **[トレースのリスト]** の下に表示されます。ナビゲーションペインで **[サービスマップ]** を選択して特定のサービスノードのトレースを表示することもできます。そうすると、そのノードに関連付けられているトレースを表示できます。
**[タイムライン]** タブにはトレースのリクエストフローが表示されますが、以下のものが含まれます。
+ 各トレース内のセグメントのパスのマップ。
+ セグメントがトレースマップのノードに到達するまでにかかった時間。
+ トレースマップのノードに対して実行されたリクエスト数。
次の図は、サンプルアプリケーションに対して実行された `GET` リクエストに関連付けられた、**[トレースマップ]** の例を示しています。矢印は各セグメントがリクエスト完了のために用いたパスを示しています。サービスノードには `GET` リクエスト中に実行されたリクエスト数が表示されます。
![\[トレースマップの後に、セグメント、その期間、オリジン、それぞれの終了を示すタイムラインが続きます。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/xray-trace-details.png)
**[タイムライン]** タブの詳細については、次の「**トレースのタイムラインの探索**」セクションを参照してください。
**[未加工データ]** タブには、トレース、およびトレースを構成するセグメントとサブセグメントに関する情報が `JSON` 形式で表示されます。この情報には、次の内容が含まれます。
+ タイムスタンプ
+ 一意の ID
+ セグメントまたはサブセグメントに関連付けられたリソース
+ セグメントまたはサブセグメントのソース、またはオリジン
+ HTTP リクエストのレスポンスなど、アプリケーションへのリクエストに関する追加情報
------
## トレースのタイムラインの探索
**[タイムライン]** セクションには、タスクの完了にかかった時間に対応する水平バーの横にある、セグメントとサブセグメントの階層が表示されます。リスト内の最初のエントリは、1 回のリクエストに対してサービスによって記録されたすべてのデータを表すセグメントです。サブセグメントはインデントされてセグメントの後に一覧表示されます。列には各セグメントに関する情報が含まれます。
------
#### [ CloudWatch console ]
CloudWatch コンソールでは、**[セグメントのタイムライン]** に次の情報が表示されます。
+ 最初の列: 選択したトレース内のセグメントとサブセグメントが表示されます。
+ **[セグメントステータス]** 列: 各セグメントとサブセグメントのステータスの結果が表示されます。
+ **[レスポンスコード]** 列: セグメントまたはサブセグメントが実行したブラウザリクエストがある場合、その TTTP レスポンスステータスコードが表示されます。
+ **[期間]** 列: セグメントまたはサブセグメントの実行期間が表示されます。
+ **[次でホストされています:]** 列: 必要に応じて、セグメントまたはサブセグメントが実行される名前空間または環境が表示されます。詳細については、「[収集されるディメンションと、ディメンションの組み合わせ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions)」を参照してください。
+ 最後の列: タイムライン内の他のセグメントまたはサブセグメントと関連する、セグメントまたはサブセグメントの実行期間に対応する水平バーが表示されます。
サービスノード別にセグメントとサブセグメントのリストをグループ化するには、**[ノード別にグループ化]** をオンにします。
------
#### [ X-Ray console ]
トレースの詳細ページで **[タイムライン]** タブを選択すると、トレースを構成する各セグメントとサブセグメントのタイムラインが表示されます。
X-Ray コンソールの **[タイムライン]** には次の情報が表示されます。
+ **[名前]** 列: トレース内のセグメントとサブセグメントの名前が表示されます。
+ **[Res.]** 列: セグメントまたはサブセグメントによって実行されたブラウザリクエストがある場合、その HTTP レスポンスステータスコードが表示されます。
+ **[期間]** 列: セグメントまたはサブセグメントの実行期間が表示されます。
+ **[ステータス]** 列: セグメントまたはサブセグメントのステータスの結果が表示されます。
+ 最後の列: タイムライン内の他のセグメントまたはサブセグメントと関連する、セグメントまたはサブセグメントの実行期間に対応する水平バーが表示されます。
コンソールがタイムラインの生成のために使用する未加工トレースデータを表示するには、**[未加工データ]** タブを選択します。未加工データには、トレース、およびトレースを構成するセグメントとサブセグメントに関する情報が `JSON` 形式で表示されます。この情報には、次の内容が含まれます。
+ タイムスタンプ
+ 一意の ID
+ セグメントまたはサブセグメントに関連付けられたリソース
+ セグメントまたはサブセグメントのソース、またはオリジン
+ HTTP リクエストのレスポンスなど、アプリケーションへのリクエストに関する追加情報
------
計測された AWS SDK、HTTP、または SQL クライアントを使用して外部リソースを呼び出すと、X-Ray SDK はサブセグメントを自動的に記録します。また、X-Ray SDK を使用して任意の関数またはコードブロックのカスタムサブセグメントを記録することもできます。カスタムサブセグメントが開いている間に記録された追加サブセグメントは、カスタムサブセグメントの子になります。
## セグメントの詳細を表示する
トレースの **[タイムライン]** から、詳細を表示するセグメントの名前を選択します。
**[セグメントの詳細]** パネルには、**[概要]**、**[リソース]**、**[注釈]**、**[メタデータ]**、**[例外]**、および **[SQL]** タブが表示されます。以下が適用されます。
+ [**概要**] タブには、リクエストと応答に関する情報が表示されます。情報には、名前、開始時間、終了時間、期間、リクエスト URL、リクエストオペレーション、リクエストレスポンスコード、エラーや障害が含まれます。
+ セグメントの **[リソース]** タブには、X-Ray SDK からの情報、およびアプリケーションを実行している AWS リソースに関する情報が表示されます。Amazon EC2、AWS Elastic Beanstalk、または X-Ray SDK 用の Amazon ECS プラグインを使用して、サービス固有のリソース情報を記録します。プラグインの詳細については、[X-Ray SDK for Java の設定](xray-sdk-java-configuration.md) の「**サービスプラグイン**」セクションを参照してください。
+ その他のタブには、セグメントに記録されている **[注釈]**、**[メタデータ]**、**[例外]** が表示されます。計測されたリクエストから生成されると例外は自動的にキャプチャされます。注釈とメタデータには X-Ray SDK が提供するオペレーションを使用して記録される追加情報が含まれています。セグメントに注釈またはメタデータを追加するには、X-Ray SDK を使用します。詳細については、[のアプリケーションの計測 AWS X-Ray](xray-instrumenting-your-app.md) の「AWS X-Ray SDK でアプリケーションを計測する」に記載されている、言語固有のリンクを参照してください。
## サブセグメントの詳細を表示する
トレースタイムラインから、詳細を表示するサブセグメントの名前を選択します。
+ **[概要]** タブにはリクエストとレスポンスに関する情報が表示されます。これには、名前、開始時間、終了時間、期間、リクエスト URL、リクエストオペレーション、リクエストレスポンスコード、エラーや障害が含まれます。計測されたクライアントを使用して生成されたサブセグメントについては、[**概要**] タブにアプリケーションの視点からのリクエストと応答に関する情報が含まれています。
+ サブセグメントの **[リソース]** タブには、サブセグメントの実行に使用された AWS リソースの詳細が表示されます。例えば、リソースタブには、AWS Lambda 関数 ARN、DynamoDB テーブルに関する情報、呼び出されるオペレーション、リクエスト ID が含まれる場合があります。
+ その他のタブには、サブセグメントに記録されている **[注釈]**、**[メタデータ]**、**[例外]** が表示されます。計測されたリクエストから生成されると例外は自動的にキャプチャされます。注釈とメタデータには X-Ray SDK が提供するオペレーションを使用して記録される追加情報が含まれています。セグメントに注釈またはメタデータを追加するには、X-Ray SDK を使用します。詳細については、[のアプリケーションの計測 AWS X-Ray](xray-instrumenting-your-app.md) の「**AWS X-Ray SDK でアプリケーションを計測する**」に記載されている、言語固有のリンクを参照してください。
カスタムサブセグメントの場合、[**概要**] タブには記録するコードまたは関数の領域を指定するために設定できるサブセグメントの名前が表示されます。詳細については、[X-Ray SDK for Java を使用したカスタムサブセグメントの生成](xray-sdk-java-subsegments.md) の「**AWS X-Ray SDK でアプリケーションを計測する**」に記載されている、言語固有のリンクを参照してください。
次の図は、カスタムサブセグメントの **[概要]** タブを示しています。概要には、サブセグメント ID、親 ID、名前、開始時間と終了時間、期間、ステータス、エラーまたは障害が含まれます。
![\[ID、親 ID、名前、時間、エラー、障害などを含む、サブセグメントの概要情報。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png)
カスタムサブセグメントの **[メタデータ]** タブには、そのサブセグメントで使用されるリソースに関する情報が JSON 形式で含まれています。
# フィルター式の使用
*フィルター式*を使用して、特定のリクエスト、サービス、2 つのサービス間の接続 (エッジ)、または条件を満たすリクエストのトレースマップまたはトレースを表示できます。X-Ray にはフィルタ式言語があり、リクエストヘッダー、レスポンスステータス、元セグメントのインデックス付きフィールドのデータに基づいて、リクエスト、サービス、エッジをフィルタリングできます。
X-Ray コンソールで表示するトレースの期間を選択すると、コンソールが表示できる以上の結果が得られることがあります。右上隅には、スキャンしたトレースの数と使用可能なトレースが他にもあるかどうかがコンソールに表示されます。フィルター式を使用して、検索するトレースだけに結果を絞り込むことができます。
**Topics**
+ [フィルタ式の詳細](#xray-console-filters-details)
+ [グループでフィルタ式を使用する](#groups)
+ [フィルタ式の構文](#console-filters-syntax)
+ [ブール型キーワード](#console-filters-boolean)
+ [数値型キーワード](#console-filters-number)
+ [文字列型キーワード](#console-filters-string)
+ [複合型キーワード](#console-filters-complex)
+ [id 関数](#console-filters-functions)
## フィルタ式の詳細
[トレースマップのノードを選択する](xray-console-servicemap.md)と、コンソールはノードのサービス名と選択に基づいて、存在するエラーのタイプに基づいてフィルター式を構成します。パフォーマンスの問題を示すトレースや特定のリクエストに関連するトレースを見つけるには、コンソールが提供する式を調整するか、独自の式を作成します。X-Ray SDK で注釈を追加する場合は、注釈キーまたはキーの値に基づいてフィルターを適用することもできます。
**注記**
トレースマップで相対的な時間範囲を選択し、ノードを選択した場合、コンソールによって時間範囲が絶対開始時刻と終了時刻に変換されます。ノードのトレースが検索結果に確実に表示され、ノードがアクティブでないときのスキャン時間を避けるために、時間範囲にはノードがトレースを送信した時間だけが含まれます。現在の時刻を基準にして検索するには、トレースページで相対的な時間範囲に戻って再度スキャンすることができます。
コンソールが表示できるものより多くの結果がまだある場合、コンソールには一致したトレースの数とスキャンされたトレースの数が表示されます。表示される割合は、スキャンされた選択済みの時間枠の割合です。結果に表示されているすべての一致するトレースを確認するには、フィルタ式をさらに絞り込むか、より短い時間枠を選択します。
一番新しい結果を得るために、コンソールは時間範囲の終わりにスキャンを開始し、逆方向に動作します。多数のトレースがあるが結果が少ない場合、コンソールは時間範囲をチャンクに分割し、それらを並行してスキャンします。進行状況バーには、スキャンされた時間範囲の一部が表示されます。
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-tracescan-parallel.png)
## グループでフィルタ式を使用する
グループは、フィルタ式で定義されるトレースのコレクションです。グループを使用して、追加のサービスグラフを生成し、Amazon CloudWatch メトリクスを指定できます。
グループは名前または Amazon リソースネーム (ARN) で識別され、フィルタ式を含みます。サービスは着信トレースを式と比較し、それに応じてそれらを保管します。
フィルタ式検索バーの左側にあるドロップダウンメニューを使用して、グループを作成および変更できます。
**注記**
グループの認定中に、サービスでエラーが検出された場合、そのグループは着信トレースの処理に含まれなくなり、エラーメトリクスが記録されます。
グループの詳細については、[グループの設定](xray-console-groups.md)を参照してください。
## フィルタ式の構文
フィルタ式に*キーワード*、単項またはバイナリの*演算子*、*値*を追加して比較することができます。
```
keyword operator value
```
演算子が異なる場合は、異なるタイプのキーワードを使用できます。たとえば、`responsetime` は、数値型キーワードを指し、数値に関する演算子と比較することができます。
**Example - 応答時間が 5 秒を超えたリクエスト**
```
responsetime > 5
```
`AND` 演算子および `OR` 演算子を使用して、複合式内で複数の式を結合できます。
**Example - 総所要時間が 5〜8 秒のリクエスト**
```
duration >= 5 AND duration <= 8
```
キーワードおよび演算子をシンプルにすると、トレースレベルでのみ問題を見つけることができます。エラーによってダウンロードが発生したが、アプリケーションによって処理され、ユーザーに返らない場合、`error` の検索では見つけることができません。
ダウンストリームの問題があるトレースを見つけるには、「[複合型キーワード](#console-filters-complex)」、`service()`、および `edge()` を使用できます。これらのキーワードを使用して、すべてのダウンストリームノード、単一のダウンストリームノード、または 2 つのノード間のエッジにフィルタ式を適用することができます。さらに詳細にする場合は、「[id() 関数](#console-filters-functions)」を使用して、タイプごとにサービスおよびエッジをフィルタリングすることができます。
## ブール型キーワード
ブール値のキーワード値は true または false です。これらのキーワードを使用して、エラーの原因となったトレースを見つけます。
**ブール型キーワード**
+ `ok` - レスポンスステータスコードは 2XX Success でした。
+ `error` - レスポンスステータスコードは 4XX Client Error でした。
+ `throttle` - レスポンスステータスコードは 429 Too Many Requests でした。
+ `fault` - レスポンスステータスコードは 5XX Server Error でした。
+ `partial` - リクエスト内に不完全なセグメントがあります。
+ `inferred` - リクエスト内に推定セグメントがあります。
+ `first` - 要素は列挙リストの最初です。
+ `last` - 要素は列挙リストの最後です。
+ `remote` - 根本原因のエンティティがリモートです。
+ `root` - サービスはエントリポイント、またはトレースのルートセグメントです。
ブール演算子は、指定されたキーが `true` または `false` のセグメントを見つけます。
**ブール演算子**
+ none - キーワードが true の場合、式は true と評価されます。
+ `!` - キーワードが false の場合、式は true と評価されます。
+ `=`,`!=` - キーワードの値を文字列 `true`または`false` と比較します。これらの演算子は、他の演算子と同じように動作しますが、より明示的です。
**Example - レスポンスステータスが 2XX OK である**
```
ok
```
**Example - レスポンスステータスが 2XX OK ではない**
```
!ok
```
**Example - レスポンスステータスが 2XX OK ではない**
```
ok = false
```
**Example - 最後の列挙障害トレースにエラー名「逆シリアル化」がある**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example - カバレッジが 0.7 より大きく、サービス名が「トレース」であるリモートセグメントを持つリクエスト**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example - サービスタイプが「AWS:DynamoDB」の推定セグメントがあるリクエスト**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example - ルートとして「data-plane」という名前のセグメントのあるリクエスト**
```
service("data-plane") {root = true and fault = true}
```
## 数値型キーワード
数値型キーワードを使用して、特定の応答時間、期間、応答ステータスを含むリクエストを検索します。
**数値型キーワード**
+ `responsetime` - サーバーでレスポンスの送信に要した時間。
+ `duration` - すべてのダウンストリーム呼び出しを含むリクエスト総所要時間。
+ `http.status` - レスポンスステータスコード。
+ `index` - 列挙リスト内の要素の位置。
+ `coverage` - ルートセグメントの応答時間に対するエンティティの応答時間の 10 進数の割合。応答時間の根本原因のエンティティにのみ適用されます。
**数値型演算子**
数値型キーワードでは、標準の品質と比較演算子を使用しています。
+ `=`,`!=` - キーワードが数値と同等か、等しくない。
+ `<`、`<=`、`>`、`>=` – キーワードが数値より小さい、または大きい。
**Example - レスポンスステータスが 200 OK ではない**
```
http.status != 200
```
**Example - 総所要時間が 5〜8 秒のリクエスト**
```
duration >= 5 AND duration <= 8
```
**Example - すべてのダウンストリーム呼び出しを含めて 3 秒未満で正常に完了したリクエスト**
```
ok !partial duration <3
```
**Example - 5 より大きいインデックスを持つ列挙型リストエンティティ**
```
rootcause.fault.service { index > 5 }
```
**Example - 最後のエンティティが 0.8 より大きいカバレッジを持つリクエスト**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## 文字列型キーワード
文字列型キーワードを使用すると、リクエストヘッダーに特定のテキストを含むトレースや特定のユーザー ID のトレースを見つけることができます。
**文字列型キーワード**
+ `http.url` - リクエストの URL。
+ `http.method` - リクエストメソッド。
+ `http.useragent` - リクエストのユーザーエージェント文字列。
+ `http.clientip` - リクエスタの IP アドレス。
+ `user` - Trace の任意の セグメント におけるユーザーフィールドの値。
+ `name` - サービスの名前、または例外。
+ `type` - サービスタイプ。
+ `message` - 例外メッセージ。
+ `availabilityzone` - トレース内の任意のセグメントのアベイラビリティーゾーンフィールドの値。
+ `instance.id` - トレース内の任意のセグメントのインスタンス ID フィールドの値。
+ `resource.arn` - トレース内の任意のセグメントのリソース ARN フィールドの値。
文字列演算子は、特定のテキストと一致する値、または特定のテキストを含む値を見つけます。値は、必ず引用符で囲います。
**文字列演算子**
+ `=`,`!=` - キーワードが数値と同等か、等しくない。
+ `CONTAINS` - キーワードに特定の文字列が含まれている。
+ `BEGINSWITH` , `ENDSWITH` - キーワードが特定の文字列で始まる、または終わる。
**Example - Http.url フィルター**
```
http.url CONTAINS "/api/game/"
```
フィールドがトレースに存在するかどうかをテストするには、その値に関係なく、空の文字列が含まれているかどうかを確認します。
**Example - ユーザー フィルター**
ユーザー ID を持つすべてのトレースを見つけます。
```
user CONTAINS ""
```
**Example - 「Auth」という名前のサービスを含む、障害の根本原因を含むトレースの選択**
```
rootcause.fault.service { name = "Auth" }
```
**Example - 最後のサービスに DynamoDB タイプがある応答時間の根本原因を含むトレースの選択**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example - 最後の例外に「account\$1id:1234567890 のアクセスが拒否されました」というメッセージのある障害の根本原因を含むトレースの選択**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## 複合型キーワード
複雑なキーワードを使用し、サービス名、エッジ名、または注釈値に基づいてリクエストを見つけます。サービスとエッジについては、サービスまたはエッジに適用される追加のフィルタ式を指定できます。注釈では、ブール値、数値、または文字列演算子を使用して、特定のキーで注釈の値をフィルタリングできます。
**複合型キーワード**
+ `annotation[key]` - フィールド *[key]* (キー)の注釈の値。注釈の値は、ブール値、数値、文字列のいずれかであるため、このタイプの比較演算子のいずれも使用することができます。このキーワードは `service` または `edge` キーワードと組み合わせて使用することができます。ドット (ピリオド) を含む注釈キーは角かっこで囲む必要があります (**[ ]**)。
+ `edge(source, destination) {filter}` - *[source]* (ソース)サービスと *[destination]* (宛先) サービス間の接続。オプションの中括弧には、この接続のセグメントに適用されるフィルタ式を含めることができます。
+ `group.name / group.arn` — グループ名またはグループ ARN で参照されるグループのフィルター式の値。
+ `json` - JSON 根本原因オブジェクト。JSON エンティティをプログラムで作成する手順については、[AWS 「X-Ray からデータを取得する](xray-api-gettingdata.md)」を参照してください。
+ `service(name) {filter}` - 名前が *[name]* のサービス。オプションの中括弧には、サービスで作成されたセグメントに適用されるフィルタ式を含めることができます。
サービスのキーワードを使用して、トレースマップの特定のノードにヒットするリクエストのトレースを見つけます。
複合型キーワード演算子は、指定されたキーが設定されている、または設定されていないセグメントを見つけます。
**複合型キーワード演算子**
+ none - キーワードが 設定されている場合、式は true と評価されます。キーワードがブール型の場合は、ブール値として評価されます。
+ `!` - キーワードが setでない場合、式は true と評価されます。キーワードがブール型の場合は、ブール値として評価されます。
+ `=`,`!=` — キーワードの値を比較します。
+ `edge(source, destination) {filter}` - *[source]* (ソース) サービスと *[destination]* (宛先) サービス間の接続。オプションの中括弧には、この接続のセグメントに適用されるフィルタ式を含めることができます。
+ `annotation[key]` - フィールド *[key]* (キー)の注釈の値。注釈の値は、ブール値、数値、文字列のいずれかであるため、このタイプの比較演算子のいずれも使用することができます。このキーワードは `service` または `edge` キーワードと組み合わせて使用することができます。
+ `json` - JSON 根本原因オブジェクト。JSON エンティティをプログラムで作成する手順については、[AWS 「X-Ray からデータを取得する](xray-api-gettingdata.md)」を参照してください。
サービスのキーワードを使用して、トレースマップの特定のノードにヒットするリクエストのトレースを見つけます。
**Example - サービスフィルター**
障害 (500 シリーズのエラー) が発生した `api.example.com` の呼び出しを含んだリクエスト。
```
service("api.example.com") { fault }
```
サービス名を除外して、フィルタ式をサービスマップのすべてのノードに適用することができます。
**Example - サービスフィルター**
トレースマップの任意の場所で障害が発生したリクエスト。
```
service() { fault }
```
エッジキーワードは、フィルタ式を 2 つのノード間の接続に適用します。
**Example - エッジ フィルター**
サービス `api.example.com` から `backend.example.com` への呼び出しが失敗してエラーが発生したリクエスト。
```
edge("api.example.com", "backend.example.com") { error }
```
また、サービスまたはエッジのキーワードを含む `!` 演算子を使用して、サービスまたはエッジを他のフィルタ式の結果から除外することもできます。
**Example - サービスおよびリクエスト フィルター**
URL が `http://api.example.com/` で始まって `/v2/` を含むが、`api.example.com` という名前のサービスに達しないリクエスト。
```
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
```
**Example — サービスと応答時間のフィルター**
`http url` が設定され、応答時間が 2 秒を超えているトレースを見つけてください。
```
http.url AND responseTime > 2
```
注釈について、`annotation[key]` が設定されているか、値のタイプに対応する比較演算子を使用しているかすべてのトレースを呼び出すことができます。
**Example - 文字列値を含む注釈**
文字列値 `gameid` の `"817DL6VO"` という名前のリクエスト。
```
annotation[gameid] = "817DL6VO"
```
**Example — 注釈が設定されている**
`age` 設定という名前の注釈を持つリクエスト。
```
annotation[age]
```
**Example — 注釈が設定されていません**
`age` 設定という名前の注釈のないリクエスト。
```
!annotation[age]
```
**Example - 数値を含む注釈**
アノテーション期間が数値 29 より大きいリクエスト。
```
annotation[age] > 29
```
**Example – サービスまたはエッジと組み合わせた注釈**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example — ユーザーとグループ化**
トレースが`high_response_time` グループフィルター (例:`responseTime > 3`) を満たし、ユーザーの名前が Alice のリクエスト。
```
group.name = "high_response_time" AND user = "alice"
```
**Example - 根本原因のエンティティを含む JSON**
根本原因エンティティが一致するリクエスト
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
## id 関数
`service` または `edge` のキーワードにサービス名を入力すると、そのサービス名を含むすべてのノードの結果が得られます。詳細にフィルタリングする場合は、`id` 関数を使用してサービスのタイプと名前を指定し、同一名を持つノードを区別することができます。
モニタリングアカウント内の複数のアカウントのトレースを表示する場合、`account.id` 関数を使用してサービスの特定のアカウントを指定します。
```
id(name: "service-name", type:"service::type", account.id:"account-ID")
```
サービスフィルタおよびエッジフィルタで、サービス名ではなく、`id` 関数を使用することもできます。
```
service(id(name: "service-name", type:"service::type")) { filter }
```
```
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
```
たとえば、 AWS Lambda 関数はトレースマップに 2 つのノードを作成します。1 つは関数の呼び出し用、もう 1 つは Lambda サービス用です。この 2 つのノードは同じ名前ですが、タイプが異なります。標準サービスフィルタは、両ノードのトレースを見つけます。
**Example - サービスフィルター**
`random-name` という名前を持つすべてのサービスにエラーを含むリクエスト。
```
service("random-name") { error }
```
`id` 関数を使用して、関数そのもののエラーを絞り込み、サービスからエラーを除外します。
**Example - id 関数を使用したサービスフィルター**
サービスタイプが `random-name` の `AWS::Lambda::Function` という名前のサービスにエラーを含むリクエスト。
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
タイプ別にノードを検索するには、名前を完全に除外します。
**Example – id 関数とサービスタイプを使用したサービスフィルター**
サービスタイプが `AWS::Lambda::Function` のサービスにエラーを含むリクエスト。
```
service(id(type: "AWS::Lambda::Function")) { error }
```
特定のノードを検索するには AWS アカウント、アカウント ID を指定します。
**Example – id 関数とアカウント ID を使用したサービスフィルター**
特定のアカウント ID `AWS::Lambda::Function` 内のサービスを含むリクエスト。
```
service(id(account.id: "account-id"))
```
# クロスアカウントトレース
AWS X-Ray の*クロスアカウントオブザーバビリティ*を使用すると、AWS リージョン 内の複数のアカウントにまたがるアプリケーションをモニタリングおよびトラブルシューティングできます。リンクされたアカウントのメトリクス、ログ、トレースをまとめてシームレスに検索、可視化、分析できます。これにより、複数のアカウントにまたがるリクエストの全体像を把握できます。クロスアカウントトレースは X-Ray のトレースマップと、[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch/)内のトレースページで表示できます。
共有されるオブザーバビリティデータには、次のいずれかのタイプのテレメトリが含まれます。
+ Amazon CloudWatch のメトリクス
+ Amazon CloudWatch Logs のロググループ
+ AWS X-Ray のトレース
+ Amazon CloudWatch Application Insights のアプリケーション
## クロスアカウントオブザーバビリティの設定
クロスアカウントオブザーバビリティを有効にするには、1 つ以上の AWS *モニタリング*アカウントを設定し、複数の*ソース*アカウントにリンクさせます。モニタリングアカウントは、ソースアカウントから生成されたオブザーバビリティデータを表示して操作できる中心的な AWS アカウント です。ソースアカウントは、そのアカウント内にあり、リソースのオブザーバビリティデータを生成する個々の AWS アカウント です。
ソースアカウントは、オブザーバビリティデータをモニタリングアカウントと共有します。トレースは各ソースアカウントから最大 5 つのモニタリングアカウントにコピーされます。ソースアカウントから最初のモニタリングアカウントへのトレースのコピーは無料です。追加のモニタリングアカウントに送信されたトレースのコピーは、標準料金に基づいて各ソースアカウントに請求されます。詳細については、[AWS X-Ray 料金表](https://aws.amazon.com/xray/pricing/)および [Amazon CloudWatch 料金表](https://aws.amazon.com/cloudwatch/pricing/)を参照してください。
モニタリングアカウントとソースアカウント間のリンクを作成するには、CloudWatch コンソール、または AWS CLI と API の新しいオブザーバビリティ Access Manager コマンドを使用します。詳細については、「[CloudWatch のクロスアカウントオブザーバビリティ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)」を参照してください。
**注記**
X-Ray トレースは、受信した AWS アカウント に請求されます。[サンプリング](xray-concepts.md#xray-concepts-sampling)されたリクエストが複数の AWS アカウント にまたがる場合、各アカウントは個別のトレースを記録し、すべてのトレースが同じトレース ID を共有します。クロスアカウントオブザーバビリティ料金の詳細については、[AWS X-Ray 料金](https://aws.amazon.com/xray/pricing/)と [Amazon CloudWatch 料金](https://aws.amazon.com/cloudwatch/pricing/)をご覧ください。
## クロスアカウントトレースの表示
クロスアカウントトレースはモニタリングアカウントに表示されます。各ソースアカウントには、その特定のアカウントのローカルトレースのみが表示されます。以下のセクションでは、モニタリングアカウントにサインインしていて、Amazon CloudWatch コンソールを開いていることを前提としています。トレースマップページとトレースページの両方で、右上隅にモニタリングアカウントのバッジが表示されます。
![\[モニタリングアカウントのバッジ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-monitoring-account.png)
### トレースマップ
CloudWatch コンソールで、左側のナビゲーションペインから **[X-Ray トレース]** の下の **[トレースマップ]** を選択します。デフォルトでは、トレースマップには、モニタリングアカウントにトレースを送信するすべてのソースアカウントのノードと、モニタリングアカウント自体のノードが表示されます。トレースマップの左上から **[フィルター]** を選択し、**[アカウント]** ドロップダウンを使用してトレースマップをフィルターします。アカウントフィルターが適用されると、現在のフィルターと一致しないアカウントのサービスノードはグレー表示されます。
![\[フィルタリングされたトレースマップ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png)
サービスノードを選択すると、[ノードの詳細] ペインにサービスのアカウント ID とラベルが表示されます。
![\[ノードの詳細ペイン\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png)
トレースマップの右上で、**[リストビュー]** を選択して、サービスノードのリストを表示します。サービスノードのリストには、モニタリングアカウントのサービスと、ソースアカウントに設定されているすべてのアカウントのサービスが含まれます。**[ノード]** フィルターで **[アカウントラベル]** または **[アカウント ID]** を選択して、ノードのリストをフィルタリングします。
![\[フィルターされたサービスリスト\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png)
### トレース
モニタリングアカウントから CloudWatch コンソールを開き、左側のナビゲーションペインの **[X-Ray トレース]** で **[トレース]** を選択すると、複数のアカウントにまたがるトレースについてのトレースの詳細が表示されます。このページは、X-Ray **[トレースマップ]** でノードを選択し、ノードの詳細ペインから **[トレースを表示]** を選択して開くこともできます。
**[トレース]** ページでは、アカウント ID によるクエリがサポートされています。はじめに、1 つまたは複数のアカウント ID を含む[クエリを入力](xray-console-filters.md)します。次の例では、アカウント ID *X*または *Y* を通過したトレースをクエリします。
```
service(id(account.id:"X")) OR service(id(account.id:"Y"))
```
![\[アカウントごとのトレースのクエリ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-traces-query-by-account.png)
**[アカウント]** ごとにクエリを絞り込みます。リストから 1 つ以上のアカウントを選択し、**[クエリに追加]** を選択します。
![\[アカウントごとにトレースクエリを絞り込む\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png)
### トレースの詳細
**[トレース]** ページの下部にある **[トレース]** リストからトレースを選択すると、トレースの詳細が表示されます。トレースが通過したすべてのアカウントのサービスノードを含むトレース詳細マップなど、**[トレースの詳細]** が表示されます。特定のサービスノードを選択すると、対応するアカウントが表示されます。
**[セグメントのタイムライン]** セクションには、タイムラインの各セグメントのアカウント詳細が表示されます。
![\[セグメントのタイムライン\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png)
# イベント駆動型アプリケーションのトレース
AWS X-Ray は Amazon SQS および AWS Lambda を使用したイベント駆動型アプリケーションのトレースをサポートします。CloudWatch コンソールを使用すると、各リクエストが Amazon SQS のキューに入れられ、1 つ以上の Lambda 関数によって処理される過程を各リクエストの接続されたビューで確認できます。アップストリームメッセージプロデューサーからのトレースは、ダウンストリーム Lambda コンシューマーノードからのトレースに自動的にリンクされるため、アプリケーションのエンドツーエンドのビューが作成されます。
**注記**
各トレースセグメントは最大 20 のトレースにリンクできます。また、1 つのトレースには最大 100 のリンクを含めることができます。シナリオによっては、追加のトレースをリンクすると[トレースドキュメントの最大サイズ](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)を超え、トレースが不完全になる可能性があります。例えば、トレーシングが有効になっている Lambda 関数が 1 回の呼び出しで多数の SQS メッセージをキューに送信した場合に発生することがあります。この問題が発生した場合は、X-Ray SDK を使用する緩和策があります。詳細については、[Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation)、[Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation)、[Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation)、[Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation)、または [.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) 用の X-Ray SDK を参照してください。
## リンクされたトレースをトレースマップに表示
[CloudWatch コンソール](https://console.aws.amazon.com/cloudwatch/)の **[トレースマップ]** ページを使用して、Lambda コンシューマーからのトレースにリンクされたメッセージプロデューサーからのトレースを含むサービスマップを表示します。これらのリンクは、Amazon SQS ノードとダウンストリーム Lambda コンシューマーノードを接続する破線のエッジで表示されます。
![\[Amazon SQS ノードと Lambda ノードの間のエッジ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)
破線のエッジを選択すると、*[受け取ったイベントが発生してから経過した時間]*ヒストグラムが表示されます。これは、コンシューマーが受け取ったイベントの経過時間の分布をマッピングしたものです。経過時間は、イベントを受信するたびに計算されます。
![\[受け取ったイベントが発生してから経過した時間ヒストグラムを含むエッジ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png)
## リンクされたトレースの詳細の表示
**メッセージプロデューサー、Amazon SQS キュー、または Lambda コンシューマーから送信されたトレースの詳細を表示します。**
1. **[トレースマップ]** を使用して、メッセージプロデューサー、Amazon SQS、または Lambda コンシューマーノードを選択します。
1. ノードの詳細ペインから **[トレースを表示]** を選択すると、トレースのリストが表示されます。CloudWatch コンソール内の **[トレース]** ページに直接移動することもできます。
1. リストから特定のトレースを選択し、トレースの詳細ページを開きます。選択したトレースが、リンクされたトレースセットの一部である場合、トレースの詳細ページにメッセージが表示されます。
![\[リンクされたトレースの詳細\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-tracedetails-header.png)
トレース詳細マップには、現在のトレースと、アップストリームとダウンストリームにリンクされたトレースが表示されます。各トレースは、トレースごとの境界を示すボックスに含まれています。現在選択されているトレースがアップストリームまたはダウンストリームの複数のトレースにリンクされている場合、アップストリームまたはダウンストリームにリンクされているトレース内のノードは積み重ねられ、**[トレースを選択]** ボタンが表示されます。
![\[複数のリンクされたアップストリームトレース\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png)
トレース詳細マップの下には、アップストリームとダウンストリームのリンクされたトレースを含むトレースセグメントのタイムラインが表示されます。アップストリームまたはダウンストリームにリンクされたトレースが複数ある場合、それらのセグメントの詳細は表示できません。リンクされたトレースセット内の 1 つのトレースのセグメント詳細を表示するには、以下の説明に従って [1 つのトレースを選択](#xray-tracelinking-filterbatch)します。
![\[リンクされたトレースを表示するセグメントのタイムライン\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-tracedetails-timeline.png)
## リンクされたトレースのセットから 1 つのトレースを選択
**リンクされたトレースセットを 1 つのトレースにフィルタリングすると、タイムラインにセグメントの詳細が表示されます。**
1. トレース詳細マップ上のリンクされたトレースの下にある **[トレースを選択]** を選択します。トレースのリストが表示されます。
![\[リンクされたトレースリスト\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png)
1. トレース詳細マップ内に表示するには、トレースの横のラジオボタンを選択します。
1. **[トレースの選択をキャンセル]** を選択すると、リンクされたトレースのセット全体が表示されます。
![\[単一リンクトレース\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png)
# レイテンシーヒストグラムの使用
AWS X-Ray の[トレースマップ](xray-console-servicemap.md)のノードまたはエッジを選択すると、X-Ray コンソールにレイテンシーの分散ヒストグラムが表示されます。
## レイテンシー
レイテンシーは、リクエストが開始してから完了するまでの時間です。ヒストグラムは、レイテンシーの分散を示します。また、期間を x 軸、各期間に一致するリクエストの割合を y 軸に示しています。
このヒストグラムでは、ほとんどのリクエストを 300 ミリ秒 (ms) 以下で完了するサービスを示します。割合が低いリクエストには最大 2 秒、異常値の場合はそれ以上かかります。
![\[レイテンシーのヒストグラムの期間 (x 軸) と各期間のリクエストの割合 (y 軸)\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-servicemap-histogram.png)
## サービスの詳細の解釈
サービス ヒストグラムおよびエッジヒストグラムは、レイテンシーをサービスまたはリクエスト元の視点からビジュアルに表現したものです。
+ 円をクリックして、*[service node]* ( サービス ノード)を選択します。X-Ray は、サービスによる依頼者のヒストグラムを示します。このレイテンシーは、サービスによって記録されたものであり、サービスと依頼者の間のネットワークレイテンシーは含まれません。
+ 2 つのサービスの間のエッジの線、または矢の先をクリックして、*[edge]* (エッジ) を選択します。X-Rayは、ダウンストリームサービスによって行われる依頼者のリクエストのヒストグラムを示します。このレイテンシーは、依頼者によって記録されたものであり、2 つのサービスの間のネットワーク接続のレイテンシーは含まれません。
[**サービスの詳細**] パネルヒストグラムを解釈するには、ヒストグラムの値の大部分と異なる値を探します。このような *異常値* は、ヒストグラムのピークまたは急増としてみなすことができるため、特定のエリアのトレースを表示して、現在の状況を調査することができます。
レイテンシーでフィルタリングされたトレースを表示するには、ヒストグラムの範囲を選択します。選択の開始位置をクリックし、左から右にドラッグして、トレースフィルタに含むレイテンシーの範囲をハイライト表示します。
![\[開始位置をクリックし、トレースフィルタの範囲を作成するために左から右にドラッグしてトレースの表示範囲を選択する\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png)
範囲を選択したら、[**Zoom**] を選択してヒストグラムの部分のみを表示し、選択範囲を絞り込みます。
![\[ズームを選択してヒストグラムの選択範囲を表示する\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png)
表示するエリアを絞って設定したら、[**View traces**] を選択します。
# X-Ray インサイトの使用
AWS X-Ray は、アカウント内のトレースデータを継続的に分析して、アプリケーションにおける緊急の問題を特定します。故障率が想定範囲を超えた場合、その問題を記録し、解決されるまで影響を追跡する*インサイト*を作成します。インサイトを使用すると、次のことが可能になります。
+ アプリケーションで問題が発生している場所、問題の根本原因、および関連する影響を特定します。 インサイトによって提供される影響分析により、問題の重要度と優先度を導き出すことができます。
+ 時間の経過とともに課題が変化すると、通知を受信します。 Amazon EventBridge を使用して、インサイト通知をモニタリングおよびアラートソリューションと統合することができます。 この統合により、問題の重要度に基づいて自動メールまたはアラートを送信できます。
X-Ray コンソールは、トレースマップで進行中のインシデントがあるノードを特定します。インサイトの概要を確認するには、影響を受けるノードを選択します。左側のナビゲーションペインから**[Insights]** (インサイト)を選択すると、インサイトを確認およびフィルタリングすることもできます。
![\[インサイトの要約を含むトレースマップノード。 \]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-servicemap.png)
X-Ray は、サービスマップの 1 つ以上のノードで*[anomaly]* (異常)を検出すると、インサイトを作成します。このサービスは、統計モデリングを使用して、アプリケーション内のサービスの予想故障率を予測します。前術の例では、異常は、AWS Elastic Beanstalk からの故障の増加です。Elastic Beanstalk サーバーで複数の API コール タイムアウトが発生し、ダウンストリームノードで異常が発生しました。
## X-Ray コンソールでインサイトの有効にします
インサイト機能を使用する場合は、グループごとに、インサイトを有効にする必要があります。インサイトを有効にするには、**[Groups]** (グループ)ページから行います。
1. [[X-Ray console]](https://console.aws.amazon.com/xray/home#) (X-Ray コンソール)を開きます。
1. 既存のグループを選択するか、**[Create group]** (グループの作成)を選択して新しいグループを作成し、**[Enable Insights]** (インサイトを有効にする)を選択します。X-Ray コンソールでのグループの構成の詳細については、[グループの設定](xray-console-groups.md) を参照してください。
1. 左側のナビゲーションペインで、**[Insights] ** (インサイト)を選択し、表示するインサイトを選択します。
![\[X-Ray コンソールでのインサイトのリスト。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights.png)
**注記**
X-rayはGetInsightSummaries、GetInsight、GetInsightEvents、GetInsightImpactGraph API オペレーションを使用して、インサイトからデータを取得できます。
詳細については、「[AWS X-Ray が IAM と連携する方法](security_iam_service-with-iam.md)」を参照してください。
## インサイトの通知を有効にします。
インサイト通知を使用すると、インサイトが作成されたとき、大幅な変更、クローズされたときなど、インサイトイベントごとに通知が作成されます。 お客様は Amazon EventBridge イベントを通じてこれらの通知を受け取り、条件付きルールを使用して SNS 通知、Lambda 呼び出し、SQS キューへのメッセージの投稿、または EventBridge がサポートする任意のターゲットなどのアクションを実行できます。 インサイト 通知がベストで出され -ベストエフォートですが、保証されていません。ターゲットの詳細については、[Amazon EventBridge Targets](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html) を参照してください。
インサイトが有効なグループに対してのインサイト通知は、**[Groups]** (グループ)ページから有効にすることができます。
**X-Ray グループの通知を有効にするには **
1. [[X-Ray console]](https://console.aws.amazon.com/xray/home#).(X-Ray コンソール)を開きます。
1. 既存のグループを選択するか、**[Create group]** グループの作成)を選択して新しいグループを作成し、**[Enable Insights]** (インサイトを有効にする)が選択されていることを確認し、**[Enable Notifications]** (通知を有効にする)を選択します。X-Ray コンソールでのグループの設定の詳細については、[グループの設定](xray-console-groups.md) を参照してください。
**Amazon EventBridge 条件付きルールを設定するには**
1. [[Amazon EventBridge console]](https://console.aws.amazon.com/events/home) (Amazon EventBridge コンソール) を開きます。
1. 左側のナビゲーションバーで、**[Rules]** (ルール) に移動し**[Create rule]** (ルールの作成) を選択します。
1. ルールの名前と説明を入力します。
1. **[Event pattern]** (イベントパターン)を選択してから、**[Custom pattern]** (カスタムパターン)を選択します。`"source": [ "aws.xray" ]` とならびに `"detail-type": [ "AWS X-Ray Insight Update" ]` を含むパターンを指定します。考えられるパターンとしては、以下のようなものがあります。
+ X-Ray インサイト からのすべての受信イベントを照合するイベントパターン:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ]
}
```
+ 指定した **state** ならびに **category** に一致するイベントパターン:
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ],
"detail": {
"State": [ "ACTIVE" ],
"Category": [ "FAULT" ]
}
}
```
1. イベントがこのルールに一致したときに呼び出すターゲットを選択して設定します。
1. （オプション）このルールをより簡単に識別して選択するためのタグを指定します。
1. **[Create]** を選択します。
**注記**
X-Ray インサイト通知は Amazon EventBridge にイベントを送信しますが、Amazon EventBridge は現在カスタマー管理キーをサポートしていません。詳細については、「[でのデータ保護AWS X-Ray](xray-console-encryption.md)」を参照してください。
## インサイト 概要
インサイト 試行tの概要ページでは、三つの重要な質問に答えます。
+ 根本的な問題は何ですか？
+ 根本原因は何ですか？
+ その影響は何ですか？
**[Anomalous services]** (異常サービス)セクションには、インシデント中の故障率の変化を示す各サービスのタイムラインが表示されます。タイムラインには、記録されたトラフィック量に基づいて予想される障害数を示すソリッドバンドに障害が発生したトレース数を重ねて表示されます。インサイトの期間は、*[Incident window]* (インシデント ウインドウ)で表示されます。インシデントウィンドウは、X-Ray がメトリックの異常を観測したときに始まり、インサイトがアクティブである間、継続します。
次の例は、インシデントの原因となった障害の増加を示しています。
![\[X-Ray インサイトの概要ページ。 \]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-overview.png)
**[根本原因]** セクションは、根本原因のサービスと影響を受けるパスに焦点を当てたトレースマップを示しています。根本原因マップの右上にある目のアイコンを選択すると、影響を受けないノードを非表示にすることができます。 根本原因サービスは、X-Ray が異常を特定した最も遠いダウンストリームノードです。 これは、インストルメントしたサービス、またはサービスがインストルメントクライアントで呼び出した外部サービスを表すことができます。 たとえば、インストルメントされた AWS SDK クライアントで Amazon DynamoDB を呼び出す場合、DynamoDB からの障害の増加により、根本原因として DynamoDB を使用したインサイトが得られます。
根本原因をさらに調査するには、根本原因グラフの **[View root cause details]** (根本原因の詳細を表示)を選択します。**[Analytics]** (分析)ページを使用して、根本原因と関連メッセージを調査することができます。詳細については、「[Analytics コンソールとのやり取り](xray-console-analytics.md)」を参照してください。
![\[X-Ray インサイトの概要ページ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-root-cause.png)
マップ内で続くアップストリームの障害は、複数のノードに影響し、複数の異常を引き起こす可能性があります。リクエストを行ったユーザーに障害を引き渡された場合、結果は*[client fault]* (クライアント障害)となります。これは、トレースマップのルートノードに発生した障害です。**[Impact]** (影響) グラフは、グループ全体のクライアント体験のタイムラインを表したものです。この経験は、次の状態のパーセンテージに基づいて計算されます。**Fault**, **Error**, **Throttle**, および **Okay**。
![\[X-Ray インシデントに対する影響グラフ。 \]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-impact.png)
この例では、インシデントの発生時にルートノードで障害が発生したトレースの増加を示します。 ダウンストリームサービスのインシデントは、クライアントエラーの増加に必ずしも対応しているとは限りません。
**[Analyze insight]** (インサイトを分析)を選択すると X-Ray Analytics コンソールがウィンドウで開き、インサイトの原因となる一連のトレースを深く掘り下げることができます。詳細については、「[Analytics コンソールとのやり取り](xray-console-analytics.md)」を参照してください。
**Understanding impact] (影響の把握**
AWS X-Ray インサイトと通知を生成する一環として、進行中の問題による影響を測定します。影響は、次の 2 つの方法で測定されます。
+ X-Ray [[group]](xray-console-groups.md) (グループ)への影響
+ 根本原因サービスへの影響
この影響は、一定の期間内に失敗またはエラーを引き起こしているリクエストの割合によって決まります。この影響分析では、特定のシナリオに基づいて、問題の重要度と優先度を導き出すことができます。この影響は、インサイト通知に加えて、コンソール体験の一部として利用できます。
**Deduplication] (重複排除**
AWS X-Ray インサイト は、複数のマイクロサービスにわたる問題の重複排除を実現します。異常検出により、問題の根本原因であるサービスを特定し、他の関連サービスが同じ根本原因で異常な動作を示しているかどうかを判断し、結果を単一のインサイトとして記録します。
## インサイトの進捗状況を確認します
X-Ray は、インサイトが解決されるまで定期的に再評価し、注目すべき中間変化をそれぞれ Amazon EventBridge イベントとして送信できる [通知](#xray-console-insight-notifications) として記録します。これにより、プロセスとワークフローを構築して、問題が時間の経過とともにどのように変化したかを判断し、EventBridge を使用して電子メールの送信やアラートシステムとの統合などの適切なアクションを実行できます。
インシデントイベントは、**[Inspect] (検査)** ページの **[Impact Timeline]** (影響タイムライン) で確認することができます。デフォルトでは、別のサービスを選択するまで、タイムラインには最も影響のあるサービスが表示されます。
![\[影響タイムラインでページを検査します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-inspect.png)
イベントのトレースマップとグラフを表示するには、影響タイムラインから選択します。 トレースマップには、インシデントの影響を受けるアプリケーションのサービスが表示されます。**[Impact analysis]** (影響分析)では、選択したノードおよびグループ内のクライアントの障害タイムラインがグラフで表示されます。
![\[X-Ray インサイトの影響分析グラフ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/console-insights-inspect-analysis.png)
インシデントに関連するトレースを詳しく調べるには、**[Inspect]** (検査) ページで **[Analyze event]** (イベントの分析) を選択します。**[Analytics]** (分析) ページで、トレースのリストを絞り込み、影響を受けるユーザーを特定することができます。詳細については、「[Analytics コンソールとのやり取り](xray-console-analytics.md)」を参照してください。
# Analytics コンソールとのやり取り
AWS X-Ray Analytics コンソールは、トレースデータを解釈してアプリケーションやその基盤となるサービスのパフォーマンスをすばやく理解するためのインタラクティブなツールです。このコンソールを使用すると、インタラクティブな応答時間グラフと時系列グラフを使用して、トレースを調査、分析、および視覚化できます。
Analytics コンソールで選択すると、コンソールは選択したすべてのトレースのサブセットを反映するようにフィルタを作成します。現在のトレースセットに関連付けられているグラフとメトリクスおよびフィールドのパネルをクリックして、アクティブなデータセットをきめ細かく絞り込むことができます。
**Topics**
+ [コンソールの機能](#xray-console-analytics-features)
+ [応答時間ディストリビューション](#xray-console-analytics-response)
+ [時系列アクティビティ](#xray-console-analytics-time)
+ [ワークフローの例](#xray-console-analytics-workflows)
+ [サービスグラフの障害を確認する](#xray-console-analytics-observe-faults)
+ [ピーク応答時間を特定する](#xray-console-analytics-response-peaks)
+ [ステータスコードでマークされているすべてのトレースを表示する](#xray-console-analytics-response-peaks)
+ [サブグループ内のすべての項目と、ユーザーに関連付けられているすべての項目を表示する](#xray-console-analytics-subgroups)
+ [異なる条件のあるトレースのセット 2 つを比較する](#xray-console-analytics-compare)
+ [目的のトレースを特定して、詳細を表示する](#xray-console-analytics-identify)
## コンソールの機能
X-Ray Analytics コンソールでは、以下の主要な機能を使用して、トレースデータをグループ化、フィルタリング、比較、定量化します。
### 機能
| 機能 | 説明 |
| --- | --- |
| **グループ** | 最初に選択されるグループは、`Default` です。取得されたグループを変更するには、メインフィルタ式検索バーの右側にあるメニューから別のグループを選択します。グループの詳細については、「[グループでフィルタ式を使用する](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups)」を参照してください。 |
| **Retrieved traces (取得されたトレース** | デフォルトでは、Analytics コンソールは選択したグループのすべてのトレースに基づいてグラフを生成します。取得されたトレースは、作業セットのすべてのトレースを表します。このタイルにトレースカウントがあります。メイン検索バーに適用したフィルタ式は、取得されたトレースを絞り込んで更新します。 |
| **Show in charts/Hide from charts (グラフに表示/グラフに非表示** | アクティブなグループを切り替え、取得されたトレースと比較します。グループに関連するデータをアクティブなフィルタと比較するには、[**Show in charts (グラフに表示)**]を選択します。グラフからこのビューを削除するには、[**Hide from charts (グラフに非表示)**] を選択します。 |
| **Filtered trace set A] (フィルタリングされたトレースセット A** | グラフやテーブルとの対話を通じて、フィルターを適用して**[Filtered trace set A ]** (フィルタリングされたトレースセット A )の基準を作成します。フィルターが適用されると、適用可能なトレースの数と取得された合計に対するトレースの割合がこのタイル内で計算されます。フィルタは [**Filtered trace set A**] タイル内のタグとして入力され、タイルから削除することもできます。 |
| **Refine (絞り込み** | この関数は、トレースセット A に適用されたフィルタに基づいて、取得したトレースのセットを更新します。取得されたトレースセットを絞り込むと、トレースセット A のフィルタに基づいて取得したすべてのトレースの処理中のセットが更新されます。取得されたトレースのワーキングセットは、グループ内のすべてのトレースをサンプリングしたサブセットです。 |
| **Filtered trace set B (フィルタリングされたトレースセット B** | 作成した場合、**[フィルタリングされたトレースセット B]** は、**[フィルタリングされたトレースセット A]** の写しです。2 つのトレースセットを比較するには、トレースセット A を固定したままトレースセット B に適用する新しいフィルターを選択します。フィルタが適用されると、適用可能なトレースの数と取得された合計からのトレースの割合がこのタイル内で計算されます。フィルタは、[**Filtered trace set B**] タイル内にタグとして入力され、タイルから削除することもできます。 |
| **Response time root cause entity paths (応答時間根本原因エンティティパス** | 記録されたエンティティパスのテーブル。X-Rayは、トレース内のどのパスが応答時間の最大の原因であるかを判別します。この形式は、検出されたエンティティの階層を示し、最後に応答時間の根本原因を示します。これらの行を使用して、定期的な応答時間障害をフィルタリングします。根本原因フィルタのカスタマイズと API 経由のデータ取得に関する詳細については、「[根本原因分析の取得と絞り込み](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics)」を参照してください。 |
| **Delta (**�**) (デルタ)** | トレースセット A とトレースセット B の両方がアクティブなときにメトリクステーブルに追加される列。Deltaデルタ列は、トレースセット A とトレースセット B の間のトレースの割合の差を計算します。 |
## 応答時間ディストリビューション
X-Ray Analytics コンソールは、トレースの視覚化に役立つ、**[Response Time Distribution ]** (応答時間ディストリビューション) および **[Time Series Activity]** (時系列アクティビティ) の 2 つの主要なグラフが生成されます。このセクションと続く部分ではそれぞれの例をあげて、グラフを読み取る方法の基本について説明します。
応答時系列グラフに関連する色は次のとおりです (時系列グラフは同じカラースキームを使用します)。
+ **[All traces in the group]** (グループのすべてのトレース) - グレー
+ **[Retrieved traces]** (取得されたトレース) - オレンジ
+ **[Filtered trace set A]** (フィルタリングされたトレースセット A) - 緑
+ **[Filtered trace set B]** (フィルタリングされたトレースセット B) - 青
**Example - 応答時間ディストリビューション**
応答時間ディストリビューションは、指定された応答時間でのトレース数を示すグラフです。クリックしてドラッグし、応答時間ディストリビューションで選択を行います。これは、特定の応答時間内のすべてのトレースに対して、`responseTime` という名前の作業トレースセットにフィルターを選択して作成します。
![\[トレースの応答時間の分布を示すグラフ。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/analytics-responseTime.png)
## 時系列アクティビティ
時系列アクティビティグラフには、指定された期間のトレースの数が表示されます。カラーインジケータは、応答時間ディストリビューションの折れ線グラフの色を反映しています。アクティビティシリーズのカラーブロックが濃く、密になるほど、より多くのトレースが指定された期間に表示されます。
**Example - 時系列アクティビティ**
クリックしてドラッグし、時系列アクティビティグラフ内で選択を行います。これは、特定の時間範囲内のすべてのトレースに対して、作業トレースセットに指定されている `timerange` という名前のフィルタを選択して作成します。
![\[選択してフィルタを作成する\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/analytics-timeSeries.png)
## ワークフローの例
以下の例では、X-Ray Analytics コンソールの一般的なユースケースを示します。各例では、コンソールエクスペリエンスの主要な機能を示します。グループとして、例では基本的なトラブルシューティングワークフローに従います。このステップでは、最初に異常なノードを特定し、次に Analytics コンソールを操作して比較クエリを自動的に生成する方法を示します。クエリによってスコープを絞り込んだら、最終的に関心のあるトレースの詳細を調べて、サービスの健全性を損なう原因を特定します。
## サービスグラフの障害を確認する
このトレースマップは、各ノードの状態をエラーと障害に対する正常な呼び出しの比率に基づいて色分けしたものです。赤色の割合が表示されたら、そのシグナルノードに障害が発生しています。X-Ray Analytics コンソールを使用して、調査を実施します。
トレースマップを読み取る方法の詳細については、「[トレースマップの表示](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)」を参照してください。
![\[障害の確認\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png)
## ピーク応答時間を特定する
応答時間ディストリビューションを使用して、応答時間のピークを確認できます。応答時間のthe ピークを選択すると、グラフの下のテーブルが更新され、ステータスコードなど、関連付けられているすべてのメトリクスが表示されます。
クリックしてドラッグすると、X-Rayによってフィルターが選択され、作成されます。これは、グラフ化された線の上にグレーの影で表示されます。影をディストリビューションに沿って左右にドラッグして選択内容とフィルタを更新できるようになりました。
![\[選択してフィルタを作成する\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/analytics-showFilterf.png)
## ステータスコードでマークされているすべてのトレースを表示する
グラフの下にあるメトリクステーブルを使用して、選択したピーク内のトレースを詳しく調べることができます。[**HTTP STATUS CODE**] テーブルの行をクリックすると、作業データセットにフィルタが自動的に作成されます。たとえば、ステータスコード 500 のトレースをすべて表示することができます。これにより `http.status` という名前のトレースセットタイルにフィルタタグが作成されます。
## サブグループ内のすべての項目と、ユーザーに関連付けられているすべての項目を表示する
ユーザー、URL、応答時間の根本原因、またはその他の事前定義された属性に基づいてエラーセットを詳しく調べます。たとえば、500 ステータスコードでトレースのセットをさらにフィルタリングするには、[**USERS**] テーブルから行を選択します。これにより、トレースセットタイルに以前に指定された `http.status`、および `user` の 2 つのフィルタタグが作成されます。
## 異なる条件のあるトレースのセット 2 つを比較する
さまざまなユーザーとその POST リクエストを比較して、他の不一致や相関関係を見つけます。最初のフィルタのセットを適用します。これらは応答時間ディストリビューションの青い線で定義されます。次に、[**Compare (比較)**] を選択します。最初に、これによりトレースセット A にフィルタのコピーが作成されます。
続行するには、トレースセット B に適用する新しいフィルタセットを定義します。この 2 番目のセットは緑色の線で表されます。次の例は、青と緑のカラースキームに従って異なる線を示しています。
![\[折れ線グラフの比較\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/analytics-compareLines.png)
## 目的のトレースを特定して、詳細を表示する
コンソールフィルタを使用してスコープを絞り込むと、メトリクステーブルの下のトレースリストがより有益になります。トレースリストテーブルは、[**URL**]、[**USER**]、および [**STATUS CODE**] に関する情報を 1 つのビューにまとめたものです。詳細については、このテーブルから行を選択して、トレースの詳細ページを開き、タイムライン、raw データを表示します。
# グループの設定
グループは、フィルタ式で定義されるトレースのコレクションです。グループを使用して、追加のサービスグラフを生成し、Amazon CloudWatch メトリクスを指定できます。AWS X-Ray コンソールまたは X-Ray APIを使って、サービスのグループを作成および管理することができます。このトピックでは、X-Ray コンソールを使用してグループを作成および管理する方法について説明します。X-Ray API を使用してグループを管理する方法については、[グループ](xray-api-configuration.md#xray-api-configuration-groups) を参照してください。
トレースマップ、トレース、または分析のトレースのグループを作成できます。グループを作成すると、グループが 3 つのページ **[トレースマップ]**、**[トレース]**、**[分析]** すべてのグループドロップダウンメニューでフィルターとして使用できるようになります。
![\[グループ メニュー\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-menu.png)
グループは名前または Amazon リソースネーム (ARN) で識別され、フィルタ式を含みます。サービスは着信トレースを式と比較し、それに応じてそれらを保管します。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。
グループのフィルタ式を更新しても、すでに記録されているデータは変わりません。更新は後続のトレースにのみ適用されます。これにより、新しい式と古い式がマージされたグラフが表示される場合があります。これを回避するには、現在のグループを削除し、新しいグループを作成します。
**注記**
グループは、フィルタ式と一致する取得済みのトレースの数で請求されます。詳細については、「[AWS X-Ray 料金表](https://aws.amazon.com/xray/pricing/)」を参照してください。
**Topics**
+ [グループを作成する](#xray-console-group-create-console)
+ [グループを適用します ](#xray-console-group-apply)
+ [グループを編集します](#xray-console-group-edit)
+ [グループのクローンを作成します](#xray-console-group-clone)
+ [グループの削除](#xray-console-group-delete)
+ [Amazon CloudWatchでグループメトリクスを表示します](#xray-console-group-cloudwatch)
## グループを作成する
**注記**
Amazon CloudWatch コンソール内から X-Ray グループを設定できるようになりました。X-Ray コンソールを引き続き使用することもできます。
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインの **[設定]** を選択します。
1. **[X-Ray トレース]** セクションの **[グループ]** の下にある **[設定の表示]** を選択します。
1. グループのリストの上にある **[グループを作成]** を選択します。
1. **[Create group]** (グループの作成) ページで、グループの名前を入力します。グループ名は最大 32 文字で、英数字とダッシュを使用できます。グループ名では大文字と小文字が区別されます。
1. フィルター式を入力します。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、グループによってサービス`api.example.com` からの障害トレースと応答時間が 5 秒以上であったサービスへのリクエストがフィルタリングされます。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. **[Insights]** ( インサイト )で、グループのインサイトアクセスを有効または無効にします。インサイトの詳細については、「[X-Ray インサイトの使用](xray-console-insights.md)」を参照してください。
![\[グループ ページの インサイト チェックボックス\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-insights-cw.png)
1. **[タグ]** で **[新しいタグを追加]** を選択してタグキーを入力し、オプションでタグ値を入力します。必要に応じて、続けてタグを追加します。タグ キーは一意である必要があります。タグを削除するには、タグの下にある **[削除]** を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
![\[グループ ページにあるタグフィールド\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-tags-cw.png)
1. **[グループの作成]** を選択してください。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)のX-Ray コンソールを開きます。
1. 左側のナビゲーションペインにある **[グループ]** ページ、または次のいずれかのページ、**[トレースマップ]**、**[トレース]**、**[分析]** いずれかのページのグループメニューから**[グループの作成]** ページを開きます。
1. **[Create group]** (グループの作成) ページで、グループの名前を入力します。グループ名は最大 32 文字で、英数字とダッシュを使用できます。グループ名では大文字と小文字が区別されます。
1. フィルター式を入力します。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、グループによってサービス`api.example.com` からの障害トレースと応答時間が 5 秒以上であったサービスへのリクエストがフィルタリングされます。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. **[Insights]** ( インサイト )で、グループのインサイトアクセスを有効または無効にします。インサイトの詳細については、「[X-Ray インサイトの使用](xray-console-insights.md)」を参照してください。
![\[グループ ページの インサイト チェックボックス\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-insights.png)
1. **[Tags]** ( タグ ) で、タグ キー、および必要に応じてタグ値を入力します。タグを追加すると、別のタグを入力するための新しい行が表示されます。タグ キーは一意である必要があります。タグを削除するには、タグの行の最後にある**X** を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
![\[グループ ページにあるタグフィールド\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-tags.png)
1. **[グループの作成]** を選択してください。
------
## グループを適用します
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. **X-Ray トレース**の下のナビゲーションペインで、次のいずれかのページを開きます:
+ **トレースマップ**
+ **トレース**:
1. **[X-Ray グループでフィルタリング]** フィルターにグループ名を入力します。ページに表示されるデータは、グループに設定されているフィルター式と一致するように変更されます。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) で X-Ray コンソールを開きます。
1. ナビゲーションペイン から次のいずれかのページを開きます:
+ **トレースマップ**
+ **トレース**:
+ **分析**
1. グループ メニューで、[グループを作成する](#xray-console-group-create-console)で作成したグループを選択します。ページに表示されるデータは、グループに設定されているフィルター式と一致するように変更されます。
------
## グループを編集します
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインの **[設定]** を選択します。
1. **[X-Ray トレース]** セクションの **[グループ]** の下にある **[設定を表示]** を選択します。
1. **[グループ]** セクションからグループを選択し、**[編集]** を選択します。
1. グループの名前を変更することはできませんが、フィルター式を更新することはできます。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、リクエストのURLアドレスに`example/game` が含まれ、リクエストの応答時間が5秒以上であるサービス `api.example.com` からの障害トレース を、グループでフィルタリングしています。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. **[Insights]** ( インサイト )で、グループのインサイトアクセスを有効または無効にします。インサイトの詳細については、「[X-Ray インサイトの使用](xray-console-insights.md)」を参照してください。
![\[グループ ページの インサイト チェックボックス\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-insights-cw.png)
1. **[タグ]** で **[新しいタグを追加]** を選択してタグキーを入力し、オプションでタグ値を入力します。必要に応じて、続けてタグを追加します。タグ キーは一意である必要があります。タグを削除するには、タグの下にある **[削除]** を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
![\[グループ ページにあるタグフィールド\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-tags-cw.png)
1. グループの更新が完了したら、**[グループの更新]** を選択します。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) で X-Ray コンソールを開きます。
1. 次のいずれかを実行して **[Edit group]** (グループの編集ページ) を開きます。
1. **[Groups]** (グループ) ページで、グループ名を選択して編集します。
1. 次のいずれかのページの グループ メニューで、グループを挙げて、**[Edit]** (編集) を選びます。
+ **トレースマップ**
+ **トレース**:
+ **分析**
1. グループの名前を変更することはできませんが、フィルター式を更新することはできます。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、リクエストのURLアドレスに`example/game` が含まれ、リクエストの応答時間が5秒以上であるサービス `api.example.com` からの障害トレース を、グループでフィルタリングしています。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. **Insights** ( インサイト )では、グループのインサイトおよびインサイト通知を有効または無効にします。インサイトの詳細については、「[X-Ray インサイトの使用](xray-console-insights.md)」を参照してください。
![\[グループ ページの インサイト チェックボックス\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-insights.png)
1. **[Tags]** (タグ) で、タグキーと値を編集します。タグキーは一意である必要があります。タグ値は任意であり、 必要であれば値 を削除できます。タグを削除するには、タグの行の最後にある**X**を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
![\[グループ ページにあるタグフィールド\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/group-tags.png)
1. グループの更新が完了したら、**[グループの更新]** を選択します。
------
## グループのクローンを作成します
グループを複製すると、既存のグループのフィルター式とタグを持つ新しいグループが作成されます。グループのクローンを作成すると、新しいグループの名前はクローンの元のグループの名前に`-clone` 付加された名前になります。
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインの **[設定]** を選択します。
1. **[X-Ray トレース]** セクションの **[グループ]** の下にある **[設定を表示]** を選択します。
1. **[グループ]** セクションからグループを選択し、**[クローン]** を選択します。
1. **[Create group]** (グループを作成する)ページで、グループの名前は*[group-name]* (グループ名) `-clone`。必要に応じて、グループの新しい名前を入力します。グループ名は最大 32 文字で、英数字とダッシュを使用できます。グループ名では大文字と小文字が区別されます。
1. フィルター式を既存のグループから保持するか、オプションで新しいフィルター式を入力できます。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、グループによってサービス `api.example.com` からの障害トレースと応答時間が 5 秒以上であったサービスへのリクエストがフィルタリングされます。
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. **[Tags]** (タグ) で、必要に応じてタグのキーと値を編集します。タグキーは一意である必要があります。タグ値は任意であり、必要に応じて値を削除できます。タグを削除するには、タグの行の最後にある**[X]** を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
1. **[グループの作成]** を選択してください。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)のX-Ray コンソールを開きます。
1. 左側のナビゲーションペインから **[グループ]** ページを開き、クローンを作成するグループの名前を選択します。
1. **[アクション]** メニューから、**[グループのクローン作成]** を選択します。
1. **[Create group]** (グループを作成する)ページで、グループの名前は*[group-name]* (グループ名) `-clone`。必要に応じて、グループの新しい名前を入力します。グループ名は最大 32 文字で、英数字とダッシュを使用できます。グループ名では大文字と小文字が区別されます。
1. フィルター式を既存のグループから保持するか、オプションで新しいフィルター式を入力できます。フィルター式の作成方法の詳細については、[フィルター式の使用](xray-console-filters.md) を参照してください。次の例では、グループによってサービス `api.example.com` からの障害トレースと応答時間が 5 秒以上であったサービスへのリクエストがフィルタリングされます。
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. **[Tags]** (タグ) で、必要に応じてタグのキーと値を編集します。タグキーは一意である必要があります。タグ値は任意であり、必要に応じて値を削除できます。タグを削除するには、タグの行の最後にある**[X]** を選択します。タグの詳細については、[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)を参照してください。
1. **[グループの作成]** を選択してください。
------
## グループの削除
グループを削除するには、このセクションの手順に従います。**[Default]** (デフォルト) グループを削除することはできません。
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインの **[設定]** を選択します。
1. **[X-Ray トレース]** セクションの **[グループ]** の下にある **[設定を表示]** を選択します。
1. **[グループ]** セクションからグループを選択し、**[削除]** を選択します。
1. 確認を求められたら **[Delete]** を選択します。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)のX-Ray コンソールを開きます。
1. 左側のナビゲーションペインから **[グループ]** ページを開き、削除するグループの名前を選択します。
1. **[Actions]** メニューで、**[Delete]** を選択します。
1. 確認を求められたら **[Delete]** を選択します。
------
## Amazon CloudWatchでグループメトリクスを表示します
グループの作成後、着信トレースは、X-Ray サービスに格納されるときにグループのフィルター式と照合されます。各基準に一致するトレースの数を確認するメトリクスがAmazon CloudWatchに断続的に公開されます。**[Edit group]** (グループの編集) ページで **[View metric]** (メトリクスを表示)を選択すると、CloudWatch コンソールに **[Metric]** (メトリクス) ページが表示されます。CloudWatch メトリクスを使用する方法の詳細については、[[Amazon CloudWatch User Guide]](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) (Amazon CloudWatch ユーザーガイド) の*[Using Amazon CloudWatch Metrics]* (Amazon CloudWatch メトリクスの使用) を参照してください。
------
#### [ CloudWatch console ]
1. AWS マネジメントコンソール にサインインして、CloudWatch コンソール ([https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)) を開きます。
1. 左側のナビゲーションペインの **[設定]** を選択します。
1. **[X-Ray トレース]** セクションの **[グループ]** の下にある **[設定を表示]** を選択します。
1. **[グループ]** セクションからグループを選択し、**[編集]** を選択します。
1. **[Edit group]** (グループ編集) ページで、**[View metric]** (メトリック表示) を選択します。
CloudWatch コンソール **[Metrics]** (メトリクス) ページを新しいタブで開きます。
------
#### [ X-Ray console ]
1. AWS マネジメントコンソール にサインインし、[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)のX-Ray コンソールを開きます。
1. 左側のナビゲーションペインから **[グループ]** ページを開き、メトリクスを表示するグループの名前を選択します。
1. **[Edit group]** (グループ編集) ページで、**[View metric]** (メトリック表示) を選択します。
CloudWatch コンソール **[Metrics]** (メトリクス) ページを新しいタブで開きます。
------
# サンプリングルールの設定
AWS X-Ray コンソールを使用して、 サービスのサンプリングルールを設定できます。サンプリング設定による[アクティブトレース](xray-services.md)をサポートする AWS Distro for OpenTelemetry、X-Ray SDK、および AWS のサービス は、サンプリングルールを使用して記録するリクエストを決定します。
**Topics**
+ [サンプリングルールの設定](#xray-console-config)
+ [サンプリングルールのカスタマイズ](#xray-console-custom)
+ [サンプリングルールオプション](#xray-console-sampling-options)
+ [サンプリングルールの例](#xray-console-sampling-examples)
+ [サンプリングルールを使用するようにサービスを設定する](#xray-console-sampling-service)
+ [サンプリング結果の表示](#xray-console-sampling-results)
+ [次の手順](#xray-console-sampling-nextsteps)
## サンプリングルールの設定
以下のユースケースのサンプリングを設定できます。
+ **API Gateway Entrypoint** — API Gateway は、サンプリングとアクティブトレースをサポートします。API ステージでアクティブトレースを有効にする方法については、「[Amazon API GatewayのアクティブトレーシングサポートAWS X-Ray](xray-services-apigateway.md)」を参照してください。
+ **AWS AppSync** – サンプリングとアクティブトレース AWS AppSync をサポートします。リクエストで AWS AppSync アクティブなトレースを有効にするには、[AWS 「X-Ray を使用したトレース](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html)」を参照してください。
+ **AWS Step Functions** – サンプリングとアクティブトレース AWS Step Functions をサポートします。ステートマシンで AWS Step Functions アクティブトレースを有効にするには、[「Step Functions」の「X-Ray トレース](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)」を参照してください。
+ **コンピューティングプラットフォームでの OpenTelemetry 用 Instrument AWS Distro** – Amazon EC2、Amazon ECS、 などのコンピューティングプラットフォームを使用する場合 AWS Elastic Beanstalk、アプリケーションが最新の AWS Distro for OpenTelemetry または X-Ray SDK で計測されている場合、サンプリングがサポートされます。
## サンプリングルールのカスタマイズ
サンプリングルールをカスタマイズすることで、記録するデータの量を制御できます。また、コードを変更したり再デプロイしたりすることなく、サンプリング動作を変更することもできます。 サンプリングルールは、一連の基準に対して記録するリクエストの数を AWS Distro for OpenTelemetry (ADOT) または X-Ray SDK に指示します。デフォルトでは、SDK は 1 秒ごとに最初のリクエストを記録し、追加のリクエストの 5% を記録します。1 秒あたり 1 つのリクエストが*リザーバ*です。これにより、サービスがリクエストを処理している限り、毎秒少なくとも 1 つのトレースが記録されます。5% は、リザーバサイズを超えて追加リクエストがサンプリングされる*レート*です。
X-Ray SDK を設定して、使用するコードに含める JSON ドキュメントからサンプリングルールを読み取ることができます。ただし、サービスで複数のインスタンスを実行するときに、各インスタンスは個別にサンプリングを実行します。これによりサンプリングされたリクエストの全体的な割合 (パーセント) が増加します。すべてのインスタンスのリザーバが実質的に結合されるからです。さらに、ローカルサンプリングルールを更新するために、コードを再デプロイする必要があります。
X-Ray コンソールでサンプリングルールを定義し、[[configuring the SDK]](#xray-console-sampling-service) (SDK を設定)して、X-Ray サービスからルールを読み取ることで、これら両方の問題を回避できます。このサービスでは、各ルールのリザーバを管理し、実行されているインスタンスの数に基づいて、リザーバを均等に分散させるため、使用するサービスの各インスタンスにクォータを割り当てます。リザーバの制限は、設定したルールに従って計算されます。サービスでルールが設定されているので、追加のデプロイを行わずにルールを管理できます。
**注記**
サンプリングルールを設定するときは、X-Ray サンプリングが「親ベース」であることを理解することが重要です。つまり、サンプリングの決定は、通常、リクエストを処理する最初の X-Ray-enabledサービス (「ルート」サービス) によって 1 回だけ行われます。
ダウンストリームサービスがアップストリーム親から既にサンプリング決定があるリクエストを受信した場合、独自の一致するサンプリングルールに関係なく、その決定を尊重します。
ルールが適用される場合: カスタムサンプリングルールは、サンプリング決定がまだ行われていないサービスでのみ有効になります。これは通常、以下に適用されます。
アプリケーションのエントリポイント (API Gateway、Load Balancer、最初の計測済みマイクロサービスなど）。
まったく新しいトレースを開始する非同期プロセスまたはワーカー。
一般的な落とし穴: 「サービス B」の厳密なサンプリングルールを作成するが、「サービス B」は常に「サービス A」によって呼び出される場合、サービス B のルールは、単にサービス A によって渡された決定に従っているため、適用されない可能性があります。このワークフローのトレースのサンプリングを変更するには、サンプリングルールをルートサービス (サービス A) に設定する必要があります。
**注記**
X-Ray では、ベストエフォート型の方法でサンプリングルールを適用しているため、場合によっては、有効なサンプリングレートが、設定されたサンプリングルールと完全に一致しないことがあります。しかし、時間の経過とともに、サンプリングされるリクエスト数が設定したパーセンテージに近づくはずです。
Amazon CloudWatch コンソール内から X-Ray サンプリングルールを設定できるようになりました。
**CloudWatch コンソールでサンプリングルールを設定するには**
1. にサインイン AWS マネジメントコンソール し、[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) で CloudWatch コンソールを開きます。
1. **セットアップ**の下の左側のナビゲーションペインで**設定**を選択します。
1. **[X-Ray トレース]** セクションの **[サンプリングルール]** の下にある **[設定を表示]** を選択します。
1. ルールを作成するには、**[サンプリングルールの作成]** を選択します。
ルールを編集するには、ルールを選択してから **[編集]** を選択します。
ルールを削除するには、ルールを選択してから **[削除]** を選択します。
## サンプリングルールオプション
次のオプションが各ルールで利用できます。文字列値では、ワイルドカードを使用して、1 つの文字列 (`?`) またはゼロ以上の文字 (`*`) に一致させることができます。
**サンプリングルールオプション**
+ **[Rule name]** (ルール名) (文字列) - ルールの一意の名前。
+ **[Priority]** (優先度) (1～9999 の整数) - サンプリングルールの優先度。サービスでは、優先度の昇順でルールが評価され、一致する最初のルールを使用してサンプリングの決定が行われます。
+ **[Reservoir]** (リザーバ) (負ではない整数) - 固定レートを適用する前に、1 秒あたりに計測する、一致するリクエストの固定数。リザーバはサービスで直接使用されませんが、ルールを一括して使用するすべてのサービスに適用されます。
+ **[レート]** (0～100) - リザーバの上限に達した後に機器と一致するリクエストのパーセンテージ。コンソールでサンプリングルールを設定するときは、0 から 100 までのパーセンテージを選択します。JSON ドキュメントを使用してクライアント SDK でサンプリングルールを設定する場合は、0 から 1 までのパーセンテージ値を指定します。
+ **[サービス名]** (文字列) - トレースマップに表示される、計測されたサービスの名前です。
+ X-Ray SDK - レコーダーで設定したサービス名。
+ Amazon API Gateway - `api-name/stage`。
+ **[サービスタイプ]** (文字列) - トレースマップに表示される、サービスタイプ。X-Ray SDK の場合、適切なプラグインを適用することで、サービスタイプを設定します。
+ `AWS::ElasticBeanstalk::Environment` – AWS Elastic Beanstalk 環境 (プラグイン）。
+ `AWS::EC2::Instance` — Amazon EC2 インスタンス (プラグイン)。
+ `AWS::ECS::Container` — Amazon ECS コンテナ (プラグイン)。
+ `AWS::EKS::Container` – Amazon EKS コンテナ (プラグイン）。
+ `AWS::APIGateway::Stage` - Amazon API Gateway ステージ。
+ `AWS::AppSync::GraphQLAPI ` – AWS AppSync API リクエスト。
+ `AWS::StepFunctions::StateMachine` – AWS Step Functions ステートマシン。
+ **[Host ]** (ホスト) (文字列) - HTTP ホスト ヘッダーからの ホスト名。
+ **[HTTP method]** (HTTP メソッド) (文字列) - HTTP リクエストのメソッド。
+ **[URL path]** (URL パス) (文字列) - リクエストの URL パス。
+ X-Ray SDK - HTTP リクエスト URL のパス部分。
+ **リソース ARN** (文字列) — サービスを実行している AWS リソースの ARN。
+ X-Ray SDK — サポートされていません。SDK では [**リソース ARN**] に `*` が設定されているルールのみを使用できます。
+ Amazon API Gateway — ステージ ARN。
+ (オプション) **[Attributes]** (属性) (キーと値) - サンプリングデシジョンが行われたときに認識されるセグメント属性。
+ X-Ray SDK — サポートされていません。SDK は属性を指定するルールを無視します。
+ Amazon API Gateway — 元の HTTP リクエストからのヘッダー。
+ (オプション) **SamplingRateBoost** (オブジェクト) – 異常駆動型サンプリングブーストの動作を制御します。
+ MaxRate (0～100 の整数) — 最大サンプリングレート (0.0～1.0) 異常時に X-Ray が に増加する可能性があります。
+ CooldownWindowMinutes (0 より大きい整数) – 1 つのブーストのみをトリガーできる時間枠 (分)。継続的なブーストを防止します。
## サンプリングルールの例
**Example - リザーバなし、低レートのデフォルトルール**
デフォルトルールのリザーバとレートを変更することができます。他のルールに一致しないリクエストにデフォルトのルールが適用されます。
+ **[Reservoir]** (リザーバ): **0**
+ **レート**: **5** (**0.05** JSON ドキュメントを使用して設定した場合)
**Example - 問題のあるルートのすべてのリクエストをトレースするデバッグルール**
デバッグ用に一時的に適用される、高優先度のルールです。
+ **[Rule name]** (ルール名): **DEBUG – history updates**
+ **[Priority]** (優先度): **1**
+ **[Reservoir]** (リザーバ): **1**
+ **レート**: **100** (**1** JSON ドキュメントを使用して設定した場合)
+ **[Service name]** (サービス名): **Scorekeep**
+ **[Service type]** (サービスタイプ): **\$1**
+ **[Host]** (ホスト): **\$1**
+ **[HTTP method]** (HTTP メソッド): **PUT**
+ **[URL path]** (URL パス): **/history/\$1**
+ **[Resource ARN]** (リソース ARN): **\$1**
**Example - POST 用の最小レートが高い**
+ **[Rule name]** (ルール名): **POST minimum**
+ **[Priority]** (優先度): **100**
+ **[Reservoir]** (リザーバ): **10**
+ **レート**: **10** (**.1** JSON ドキュメントを使用して設定した場合)
+ **[Service name]** (サービス名): **\$1**
+ **[Service type]** (サービスタイプ): **\$1**
+ **[Host]** (ホスト): **\$1**
+ **[HTTP method]** (HTTP メソッド): **POST**
+ **[URL path]** (URL パス): **\$1**
+ **[Resource ARN]** (リソース ARN): **\$1**
**Example 異常駆動型ブーストを有効にする**
10 分間のクールダウンで、異常時にサンプリングブーストを最大 50% トリガーするルールを設定します。
+ **[Rule name]** (ルール名): **MyAdaptiveRule**
+ **[Priority]** (優先度): **100**
+ **[Reservoir]** (リザーバ): **1**
+ **FixedRate**: **0.0510**
+ **[Service name]** (サービス名): **\$1**
+ **[Service type]** (サービスタイプ): **\$1**
+ **[Host]** (ホスト): **\$1**
+ **[HTTP method]** (HTTP メソッド): **POST**
+ **[URL path]** (URL パス): **\$1**
+ **maxRate**: **0.5**
+ **cooldownWindowMinutes**: **10**
## サンプリングルールを使用するようにサービスを設定する
AWS Distro for OpenTelemetry (ADOT) と X-Ray SDK では、コンソールで設定したサンプリングルールを使用するには、追加の設定が必要です。サンプリング戦略を設定する方法の詳細については、使用言語の「設定」トピックを参照してください。
+ Java: ADOT Java での [X-Ray リモートサンプリング](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling)の使用
+ Go: ADOT Go を使用した[サンプリングの設定](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling)
+ Node.js: ADOT JavaScript での [X-Ray リモートサンプリング](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling)の使用
+ Python: ADOT Python での [X-Ray リモートサンプリング](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling)の使用
+ Ruby: [サンプリングルール](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling)
+ .NET: ADOT .NET での [X-Ray リモートサンプリングの使用](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling)
API Gatewayについては、[Amazon API GatewayのアクティブトレーシングサポートAWS X-Ray](xray-services-apigateway.md) を参照してください。
## サンプリング結果の表示
X-Ray コンソールの **[Sampling]** (サンプリング) ページには、サービスでの各サンプリングルールの使用方法に関する詳細情報が表示されます。
[**Trend (トレンド)**] 列には、直近の数分でルールがどのように使用されたのかを表示します。各列に、10 秒ウィンドウの統計が表示されます。
**サンプリング統計**
+ **[Total matched rule]** (ルールに一致した総数): 対象ルールに一致するリクエストの数。この数には、対象ルールに一致する可能性があるすべてのリクエストが含まれるわけではありません。優先度の高いルールに最初に一致したリクエストのみが含まれます。
+ **[Total sampled]** (サンプリングされた総数): 記録されたリクエスト数。
+ **[Sampled with fixed rate]** (サンプリングの固定レート): ルールの固定レートを適用してサンプリングされたリクエスト数。
+ **[Sampled with reservoir limit]** (サンプリングのリザーバ制限):X-Rayによって割り当てられたクォータを使用してサンプリングされたリクエスト数。
+ **[Borrowed from reservoir]** (リザーバから借用): リザーバからの借用によって、サンプリングされたリクエスト数。サービスで初めてリクエストがルールに一致するとき、X-Rayによりクォータがまだ割り当てられていません。ただし、リザーバが少なくとも 1 である場合、X-Rayがクォータを割り当てるまで、サービスは 1 秒あたり 1 つのトレースを借用します。
サンプリングの統計およびサービスがサンプリングルールを使用する方法の詳細については、「[X-Ray API でのサンプリングルールの使用](xray-api-sampling.md)」を参照してください。
## 次の手順
X-Ray API を使用して、サンプリングルールを管理できます。API では、スケジュールに従って、またはアラームや通知に応答して、プログラムでルールを作成および更新することができます。手順と追加のルールの例については、[AWS X-Ray API を使用したサンプリング、グループ、暗号化設定の構成](xray-api-configuration.md) を参照してください。
AWS Distro for OpenTelemetry、X-Ray SDK、 AWS のサービス も X-Ray API を使用して、サンプリングルールの読み取り、サンプリング結果のレポート、サンプリングターゲットの取得を行います。X-Ray がサービスにクォータを割り当てていないルールにリクエストが一致するとき、サービスは、各ルールの適用、優先度に基づくルールの評価、およびリザーバからの借用に関する頻度を追跡する必要があります。サービスがサンプリングに API を使用する方法の詳細については、「[X-Ray API でのサンプリングルールの使用](xray-api-sampling.md)」を参照してください。
AWS Distro for OpenTelemetry または X-Ray SDK コールサンプリング APIs の場合、プロキシとして CloudWatch エージェントを使用します。TCP ポート 2000 を既に使用している場合は、別のポートでプロキシを実行するようにエージェントを設定できます。詳細については、[CloudWatch エージェントのインストールガイド](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)を参照してください。
# アダプティブサンプリングの設定
異常スパイク中に重要なトレースが見つからないと、根本原因の分析が困難になる可能性があります。ただし、高いサンプリングレートを維持するにはコストがかかります。X-Ray アダプティブサンプリングは、異常を完全に可視化し、通常のオペレーション中のコストを制御します。アダプティブサンプリングでは、最大サンプリングレートを設定すると、X-Ray はその制限内で自動的に調整します。X-Ray は、エラートレースをキャプチャするために必要な最小ブーストを計算します。ベースラインレートが十分なデータをキャプチャしている場合、ブーストは発生しません。追加のサンプリングについては、必要な場合にのみお支払いいただきます。
アダプティブサンプリングを使用する利点:
+ インシデントの完全な可視性 – 手動による介入なしで、インシデント中に完全なトレースを取得します。X-Ray はサンプリングレートを自動的に調整してエラートレースをキャプチャし、通常のレートに戻ります。
+ 根本原因の可視性 – 問題の原因を常に確認します。X-Ray は、完全なトレースサンプリングがトリガーされない場合でも、重大なエラーデータをキャプチャします。
+ コストの最適化 – 短いサンプリングブースト (最大 1 分) と自動クールダウン期間により、オーバーサンプリングを防止します。問題の診断に必要なデータに対してのみ料金が発生します。
**Topics**
+ [サポートされている SDK とプラットフォーム](#adaptive-sampling-supported-sdks)
+ [アダプティブサンプリングアプローチを選択する](#adaptive-sampling-features)
+ [SDK のローカル設定](#local-sdk-configuration)
## サポートされている SDK とプラットフォーム
**サポートされている SDK** – アダプティブサンプリングには、最新バージョンの ADOT SDK が必要です。
**サポートされている言語** – Java (バージョン [v2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) 以降)
アプリケーションは、サポートされている ADOT SDK で計装し、Amazon CloudWatch エージェントまたは OpenTelemetry コレクターと一緒に実行する必要があります。
例えば、Amazon EC2、Amazon ECS、Amazon EKS は、AWS Application Signals が ADOT SDK と Amazon CloudWatch エージェントを有効にするためのガイダンスを提供する一般的なプラットフォームです。
## アダプティブサンプリングアプローチを選択する
アダプティブサンプリングは、サンプリングブーストと異常スパンキャプチャの 2 つのアプローチをサポートしています。これらは個別に適用することも、組み合わせて適用することもできます。
### サンプリングブースト
アダプティブサンプリングブーストはサンプリングルールに基づいており、既存の X-Ray ヘッドベースのサンプリングモデルで動作します。ヘッドベースのサンプリングとは、サンプリングの決定がルートサービスで行われ、サンプリングフラグがコールチェーン内のすべてのダウンストリームのサービスに伝播されることを意味します。
+ **ルールベースのブースティング** – ブースティングは常に特定の X-Ray サンプリングルールに関連付けられます。各ルールは、独自の最大ブーストレートとクールダウン動作を定義できます。
+ **ヘッドベースのサンプリング** – サンプリングの決定はルートサービスで行われ、サンプリングフラグがコールチェーン内のすべてのダウンストリームのサービスに伝播されます。
+ **異常駆動型** – X-Ray は SDK を使用して異常統計を報告します。X-Ray は、エラーや高レイテンシーなどの異常を検出すると、これらの統計を使用して適切なブーストレート (設定された最大値まで) を計算します。
**異常レポート**
コールチェーン内のすべてのアプリケーションサービスは、必要な SDK を通じて異常統計を出力できます。
+ **ルートサービス** – サンプリングブーストを有効にするには、サポートされている SDK とプラットフォームで実行する必要があります。ルートサービスがサポートされていない場合、ブーストは行われません。
+ **ダウンストリームサービス** – ダウンストリームサービスは異常のみを報告します。サンプリングの決定を行うことはできません。ダウンストリームサービスがサポートされている SDK を実行している場合、検出された異常によってサンプリングブーストがトリガーされる可能性があります。ダウンストリームサービスがサポートされていない場合 (古い SDK の実行など)、そのサービスの異常はブーストをトリガーしません。これらのサービスは、標準のコンテキスト伝播 (W3C トレースコンテキストやバゲッジなど) に従うと、引き続きコンテキストをダウンストリームに伝播できます。これにより、さらにダウンストリームのサービスでサポートされている SDK が、ブーストをトリガーする異常をレポートできるようになります。
**ブーストのタイミングと範囲**
+ **トリガー遅延** – X-Ray が異常を検出してから 10 秒ほどでサンプリングブーストが開始されると予想できます。
+ **ブースト期間** – X-Ray がブーストをトリガーした後、基本サンプリングレートに戻るまで最大 1 分間続きます。
+ **ブーストクールダウン** – ブーストが発生すると、クールダウン期間が経過するまで、X-Ray は同じルールに対して別のブーストをトリガーしません。
例えば、`cooldown` を 10 分間に設定した場合、ブーストが終了すると、次の 10 分間のウィンドウまで新しいブーストをトリガーすることはできません。
特殊なケース: `cooldown` を 1 分間に設定すると、ブースト自体が最大 1 分間続く可能性があるため、異常が持続するとブーストを効果的かつ連続的にトリガーできます。
**注記**
ルートサービスでサポートされている SDK とプラットフォームを使用します。サンプリングブーストは、サポートされている SDK とプラットフォームでのみ機能します。サンプリングブーストは異常トレースをキャプチャする可能性が高いですが、すべての異常トレースをキャプチャするとは限りません。
**可視性の向上**
サンプリングルールがアダプティブサンプリングブーストで設定されている場合、X-Ray はブーストアクティビティをモニタリングできる提供されたメトリクスを自動的に出力します。
+ **メトリクス名** – `SamplingRate`
+ **ディメンション** – `RuleName` (実際のルール名に設定)
`SamplingRateBoost` が有効になっている各ルールは、ベースラインレートと一時的なブーストの両方を含む有効なサンプリングレートを発行します。これにより、次のことが可能になります。
+ ブーストがトリガーされるタイミングを追跡する
+ 各ルールの有効なサンプリングレートをモニタリングする
+ ブーストをアプリケーションの異常 (エラースパイクやレイテンシーイベントなど) と関連付ける
これらのメトリクスは、**Amazon CloudWatch メトリクスの AWS/X-Ray 名前空間で表示できます。メトリクス値は、有効なサンプリングレートを表す 0～1 の浮動小数点数です**。
**X-Ray サンプリングルールを使用してサンプリングブーストを設定する**
新しい `SamplingRateBoost` フィールドを追加することで、既存の X-Ray サンプリングルールでアダプティブサンプリングを直接有効にできます。詳細については、「[Customizing sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom)」を参照してください。これにより、アプリケーションコードを変更したり、アプリケーションのデプロイを適用したりすることなく、アダプティブサンプリングを一元的に有効にできます。アダプティブサンプリングを有効にすると、X-Ray は、設定された最大値内にサンプリングレートを維持しながら、エラースパイクやレイテンシーの外れ値などの異常時にサンプリングを自動的に増やします。`SamplingRateBoost` は、`Default` サンプリングルールを除く任意のカスタムサンプリングルールに適用できます。
`SamplingRateBoost` フィールドは、異常駆動型サンプリングの上限と動作を定義します。
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
```
`MaxRate` は、X-Ray が異常を検出したときに適用する最大サンプリングレートを定義します。値の範囲は `0.0`～`1.0` です。例えば、`"MaxRate": 0.25` では、サンプリングにより、異常ウィンドウ中にリクエストの 25% まで増やすことができます。X-Ray は、異常アクティビティに応じて、ベースラインと最大値の間の適切なレートを決定します。
`CooldownWindowMinutes` は、1 つのサンプリングレートブーストのみをトリガーできる時間枠 (分単位) を定義します。ブーストが発生すると、次のウィンドウまでそれ以上ブーストは許可されません。値タイプは*整数 (分)* です。
**アダプティブサンプリングを使用したルールの例**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
この例では、ベースラインサンプリングは 5% (`FixedRate: 0.05`) です。異常が起きている間、X-Ray はサンプリングを最大 25% (`MaxRate: 0.25`) まで増やすことができます。ブーストは 10 分に 1 回のみ行われます。
**異常条件の設定**
異常条件設定が指定されていない場合、ADOT SDK はデフォルトの異常条件として **HTTP 5xx エラーコード**を使用してサンプリングブーストをトリガーします。
環境変数を使用して、サポートされている ADOT SDK で異常条件をローカルでファインチューニングすることもできます。詳細については、「[SDK のローカル設定](#local-sdk-configuration)」を参照してください。
### 異常スパンのキャプチャ
異常スパンのキャプチャにより、完全なトレースがサンプリングされていない場合でも、異常を表す重要なスパンが常に記録されます。この機能は、将来のトレースのサンプリングを増やすのではなく、異常自体のキャプチャに焦点を当てることで、サンプリングブーストを補完します。
ADOT SDK が異常を検知すると、サンプリングの決定に関係なく、そのスパンがすぐに出力されます。SDK は異常に関連するスパンのみを出力するため、これらのトレースは完全なエンドツーエンドのトランザクションではなく部分的なトレースです。
ADOT SDK は、異常スパンを検出すると、同じトレースからできるだけ多くのスパンを出力しようとします。この機能で出力されるすべてのスパンには、`aws.trace.flag.sampled = 0` 属性がタグ付けされます。これにより、トランザクションの検索と分析で部分トレース (異常キャプチャ) と完全なトレース (通常のサンプリング) を簡単に区別できます。
部分トレースを表示およびクエリするには、[トランザクション検索](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html)をオンボーディングすることをお勧めします。次の例は、[Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) コンソールのサービスページを示しています。ServiceC は異常スパンのキャプチャで設定され、サンプリングブーストが適用されるコールチェーンの一部です。この設定では、完全なトレースと部分的なトレースの両方が生成されます。`aws.trace.flag.sampled` 属性を使用して、トレースタイプを区別できます。
![\[異常スパンのキャプチャ\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/adaptive-sampling.png)
異常スパンのキャプチャは、[SDK のローカル設定](#local-sdk-configuration) を介してのみ有効化またはカスタマイズできます。
## SDK のローカル設定
環境変数を介して YAML 設定を指定することで、ADOT SDK でアダプティブサンプリング機能を設定できます。ローカル設定では、異常条件、しきい値をきめ細かく制御できます。
これは*異常スパンのキャプチャ*に必要ですが、*サンプリングブースト*条件をカスタマイズする場合は任意です。以下に示しているのは、設定の例です。
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
フィールド定義は次のとおりです。
+ `version` – 設定ファイルのスキーマバージョン
+ `anomalyConditions` – 異常が検出される条件とその使用方法を定義
+ `errorCodeRegex` – 異常と見なされる HTTP ステータスコードを定義する正規表現
+ `operations` – 条件が適用されるオペレーションまたはエンドポイントのリスト
+ `highLatencyMs` – スパンが異常として扱われるレイテンシーしきい値 (ミリ秒単位)
+ `usage` – 条件が適用される機能を次のように定義します。
+ `both` – **サンプリングブースト**と**異常スパンのキャプチャ**に適用 (使用量が指定されていない場合はデフォルト)
+ `sampling-boost` – サンプリングブーストのトリガーにのみ使用
+ `anomaly-span-capture` – 異常スパンのキャプチャにのみ使用
+ `anomalyCaptureLimit` – 異常スパンが出力されるトレース数の制限を定義
`anomalyTracesPerSecond` – 過剰なスパンボリュームを防ぐため、1 秒あたりにキャプチャされた異常スパンを持つトレースの最大数 (anomalyCaptureLimit が存在しない場合、デフォルト値は 1)
**注記**
`AnomalyConditions` は、サンプリングブースト (HTTP 5xx) のデフォルトの異常条件を**上書き**します。ローカル設定の使用中にデフォルト条件を保持する場合は、`AnomalyConditions` の任意の項目に明示的に含める必要があります。
各 `anomalyConditions` 項目について:
`operations` フィールドを**省略**すると、条件は**すべてのオペレーション** (サービスレベル) に適用されます。
`operations` フィールドが存在するものの、**空のリスト**に設定されている場合、条件は**オペレーションに適用されず**、その項目はオペレーションなしになります。
`errorCodeRegex` と `highLatencyMs` の両方を省略すると、条件には評価すべき異常基準がなく、その項目はオペレーションなしになります。
論理関係:
`anomalyConditions` の項目間の関係は **OR** です。
1 つの項目内では、複数のフィールド (`errorCodeRegex` や `highLatencyMs` など) が **AND** と結合されます。
例:
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
この条件は、**ステータスコードが 429 または 5xx に一致し、レイテンシーが ≥ 300 ミリ秒**であることを意味します。
### ローカル設定を ADOT SDK に適用する
環境変数 `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG` を設定することで、ADOT SDK にローカル設定を適用できます。値は有効な YAML ドキュメント (インラインまたはネスト) である必要があります。
例えば、Amazon EC2 と Amazon ECS では、環境変数を直接設定します。
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
Amazon EKS の場合、ポッド仕様内の環境変数をネストされた YAML として定義します。
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```
# コンソールのディープリンク
ルートとクエリを使用して、特定のトレース、またはトレースのフィルタリングされたビュー、およびトレースマップにディープリンクできます。
**コンソールページ**
+ ようこそページ - [[xray/home\$1/welcom]](https://console.aws.amazon.com/xray/home#/welcome) (xray/ホーム\$1/ようこそ)
+ はじめに - [[xray/home\$1/getting-starte]](https://console.aws.amazon.com/xray/home#/getting-started) (xray/ホーム\$1/はじめに)
+ トレースマップ - [[xray/home\$1/service-ma]](https://console.aws.amazon.com/xray/home#/service-map) (xray/ホーム\$1/サービスマップ)
+ トレース - [[xray/home\$1/trace]](https://console.aws.amazon.com/xray/home#/traces) (xray/ホーム\$1/トレース)
## トレース
個別のトレースのタイムライン、raw、マップビューのリンクを生成できます。
**[Trace timeline]** (トレースのタイムライン) - `xray/home#/traces/trace-id`
**[Raw trace data]** (未加工のトレースデータ) - `xray/home#/traces/trace-id/raw`
**Example - 未加工のトレースデータ**
```
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
```
## フィルタ式
フィルタリングされたトレースリストへのリンク
**[Filtered traces view]** (フィルタリングされたトレースビュー) - `xray/home#/traces?filter=filter-expression`
**Example - フィルター表現**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
```
**Example - フィルター表現 (URL エンコード)**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
```
フィルタ式の詳細については、「」を参照してください[フィルター式の使用](xray-console-filters.md)
## [時間範囲]
期間または開始時刻と終了時刻を ISO8601 形式で指定します。時間範囲は UTC で、最大で6時間にすることができます。
**[Length of time]** (期間) - `xray/home#/page?timeRange=range-in-minutes`
**Example - 過去 1 時間のトレースマップ**
```
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
```
**[Start and end time]** (開始と終了の時刻) - `xray/home#/page?timeRange=start~end`
**Example - 秒単位の正確な時間範囲**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00
```
**Example - 分単位の正確な時間範囲**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00
```
## リージョン
リージョンのページにリンクする AWS リージョン を指定します。リージョンを指定しない場合、コンソールは最後に利用したリージョンにリダイレクトされます。
**[Region]** (リージョン) - `xray/home?region=region#/page`
**Example - 米国西部 (オレゴン) (us-west-2) のトレースマップ**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
```
その他のクエリパラメーターを使用してリージョンを含めると、リージョンクエリは、ハッシュ前、X-Ray 固有のクエリはページ名の後に指定されます。
**Example - 米国西部 (オレゴン) (us-west-2)の直近 1 時間のトレースマップ**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
```
## 結合
**Example - 期間フィルターを含む最近のトレース**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
```
**Output**
+ ページ - トレース
+ 時間範囲 - 最後の 15 分
+ フィルター - 期間 >= 5 および 期間 <= 8
# X-Ray API を使用する
X-Ray SDK がご使用のプログラミング言語をサポートしていない場合は、X-Ray API を直接使用、または AWS Command Line Interface (AWS CLI) を使用して X-Ray API コマンドを呼び出せます。次のガイダンスを使用して、API の操作方法を選択します。
+ 事前フォーマットされたコマンドを使用した、またはリクエスト内のオプションを使用した、単純な構文の AWS CLI を使用します。
+ X-Ray API を直接使用して、X-Ray に対するリクエストの柔軟性とカスタマイズを最大限活用します。
AWS CLI の代わりに [X-Ray API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) を直接使用する場合は、リクエストを正しいデータ形式でパラメータ化する必要があり、認証およびエラー処理を設定する必要もある場合があります。
次の図は、X-Ray API の操作方法の選択のためのガイダンスを示しています。
![\[X-Ray は、アプリケーションリクエストに関する詳細情報を表示します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/api-vs-cli.png)
X-Ray API を使用してトレースデータを X-Ray に直接送信します。X-Ray API は、以下の一般的なアクションを含む、X-Ray SDK で使用可能なすべての関数をサポートしています。
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) - セグメントのドキュメントを X-Ray にアップロードします。
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) - トレース ID のリスト内のトレースのリストを取得します。取得した各トレースは、単一のリクエストからのセグメントドキュメントのコレクションです。
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) - トレースの ID と注釈を取得します。`FilterExpression` を指定するとトレース概要のサブセットを取得できます。
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html) - 特定のトレース ID のサービスグラフを取得します。
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) - 受信リクエストを処理してダウンストリームリクエストを呼び出すサービスを説明する、JSON 形式のドキュメントを取得します。
アプリケーションコード内の AWS Command Line Interface (AWS CLI) を使用して、プログラムで X-Ray を操作することもできます。AWS CLI は、他の AWS のサービス 用の関数を含む、X-Ray SDK で使用できるすべての関数をサポートします。次の関数は以前にリストされた API オペレーションのバージョンで、より単純な形式になっています。
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html) - セグメントのドキュメントを X-Ray にアップロードします。
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html) - トレース ID のリスト内のトレースのリストを取得します。取得した各トレースは、単一のリクエストからのセグメントドキュメントのコレクションです。
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html) - トレースの ID と注釈を取得します。`FilterExpression` を指定するとトレース概要のサブセットを取得できます。
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html) - 特定のトレース ID のサービスグラフを取得します。
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html) - 受信リクエストを処理してダウンストリームリクエストを呼び出すサービスを説明する、`JSON` 形式のドキュメントを取得します。
使用するには、オペレーティングシステムに [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) をインストールする必要があります。AWS は Linux、macOS、Windows の各オペレーティングシステムをサポートしています。X-Ray コマンドのリストの詳細については、「[X-Ray の AWS CLI コマンドリファレンスガイド](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html)」を参照してください。
**Topics**
+ [AWS X-Ray CLI を利用して AWS API 使用する](xray-api-tutorial.md)
+ [トレースデータを に送信する AWS X-Ray](xray-api-sendingdata.md)
+ [AWS X-Ray からのデータの取得](xray-api-gettingdata.md)
+ [AWS X-Ray API を使用したサンプリング、グループ、暗号化設定の構成](xray-api-configuration.md)
+ [X-Ray API でのサンプリングルールの使用](xray-api-sampling.md)
+ [AWS X-Ray セグメントドキュメント](xray-api-segmentdocuments.md)
# AWS X-Ray CLI を利用して AWS API 使用する
AWS CLI では、X-Ray サービスに直接アクセスできます。また、X-Ray コンソールで使用されているものと同じ API を使用して、サービスグラフや未加工のトレースデータを取得できます。サンプルアプリケーションには、AWS CLI でこれらの API を使用する方法を示すスクリプトが含まれています。
## 前提条件
このチュートリアルでは、Scorekeep サンプルアプリケーションと、それに含まれるトレーシングデータとサービスマップを生成するスクリプトを使用します。[入門チュートリアル](xray-gettingstarted.md)の指示に従って、アプリケーションを起動します。
このチュートリアルでは、AWS CLI を使用して、X-Ray API の基本的な使用方法を説明します。AWS CLI は [Windows、Linux、および OS-X で利用でき](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)、コマンドラインですべての AWS のサービス のパブリック API にアクセスすることが可能です。
**注記**
AWS CLI が、Scorekeep サンプルアプリケーションが作成されたのと同じリージョンに設定されていることを確認する必要があります。
サンプルアプリケーションに含まれるテスト用のスクリプトは、`cURL` を使用してトラフィックを API および `jq` に送信し、出力を解析します。`jq` 実行可能ファイルは [stedolan.github.io](https://stedolan.github.io/jq/) から、`curl` 実行可能ファイルは [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html) からダウンロードできます。ほとんどの Linux および OS X インストールには cURL が含まれています。
## トレースデータの生成
ゲームの進行中、ウェブアプリケーションは数秒ごとに API にトラフィックを生成し続けますが、生成されるリクエストのタイプは 1 つだけです。`test-api.sh` スクリプトを使用して、エンドツーエンドのシナリオを実行し、API のテスト中により多様なトレースデータを生成します。
**`test-api.sh` スクリプトを使用するには**
1. [Elastic Beanstalk コンソール](https://console.aws.amazon.com/elasticbeanstalk)を開きます。
1. 環境に対応する[マネジメントコンソール](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)に移動します。
1. 環境 [**URL**] をページヘッダーからコピーします。
1. `bin/test-api.sh` を開いて API の値を環境の URL に置き換えます。
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. スクリプトを実行して API へのトラフィックを生成します。
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## X-Ray API を使用する
AWS CLI では、X-Ray が提供するすべての API アクション ([https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) および [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)) のコマンドが提供されます。サポートされているすべてのアクションおよびそこで使用するデータ型の詳細については、「[AWS X-Ray API リファレンス](https://docs.aws.amazon.com/xray/latest/api/Welcome.html)」を参照してください。
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
このスクリプトは直近 10 分のサービスグラフを取得します。
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
このスクリプトは 1 分前から 2 分前の間に生成されたトレースの URL を取得します。
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
このスクリプトは 1 分前から 2 分前の間に生成されたトレース全体を取得します。
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## クリーンアップ
Elastic Beanstalk 環境を終了し、Amazon EC2 インスタンス、DynamoDB テーブル、およびその他のリソースをシャットダウンします。
**Elastic Beanstalk 環境を終了するには**
1. [Elastic Beanstalk コンソール](https://console.aws.amazon.com/elasticbeanstalk)を開きます。
1. 環境に対応する[マネジメントコンソール](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)に移動します。
1. **[アクション]** を選択します。
1. [**Terminate Environment**] を選択します。
1. **[Terminate]** (終了) を選択します。
30 日後、トレースデータは自動的に X-Ray から削除されます。
# トレースデータを に送信する AWS X-Ray
トレースデータは、セグメントドキュメントの形式で X-Ray に送信できます。セグメントドキュメントは、アプリケーションがリクエストのサービスで行う作業に関する情報を含む JSON 形式の文字列です。セグメント内で行われる作業、またはサブセグメントのダウンストリームサービスおよびリソースを使用する作業に関するデータはアプリケーションに記録できます。
セグメントは、アプリケーションで行われる作業に関する情報を記録します。セグメントには、少なくとも、タスク、名前、2 つの ID で使用される時間が記録されます。トレース ID は、サービス間でやり取りされるリクエストを追跡します。セグメント ID は、単一のサービスのリクエストで行われる作業を追跡します。
**Example 最小完了セグメント**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
リクエストを受信したら完了するまで、プレースホルダーとして進行中のセグメントを送信できます。
**Example 進行中セグメント**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
セグメントは、「[`PutTraceSegments`](#xray-api-segments)」、または「[X-Ray デーモンを通じて](#xray-api-daemon)」直接 X-Ray に送信できます。
ほとんどのアプリケーションは、 AWS SDK を使用して他の サービスを呼び出したり、リソースにアクセスしたりします。*サブセグメント*のダウンストリーム呼び出しに関する情報を記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。
サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズ (64 kB) を超えないようにしたりできます。
**Example サブセグメント**
サブセグメントには `subsegment` の `type` および親セグメントを識別する `parent_id` があります。
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
セグメントとサブセグメントに含めることができるフィールドと値の詳細については、「[AWS X-Ray セグメントドキュメント](xray-api-segmentdocuments.md)」を参照してください。
**Topics**
+ [トレース ID を生成する](#xray-api-traceids)
+ [PutTraceSegments を使用する](#xray-api-segments)
+ [セグメントドキュメントを X-Ray デーモンに送信する](#xray-api-daemon)
## トレース ID を生成する
X-Ray にデータを送信するには、リクエストごとに一意のトレース ID を生成する必要があります。
**X-Ray のトレース ID 形式**
X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます：
+ バージョン番号、すなわち、`1`。
+ 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。
例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。
+ グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。
**注記**
X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。
テスト用の X-Ray トレース ID を生成するためのスクリプトを記述することができます。これらはその 2 つの例です。
**Python**
```
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```
**Bash**
```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```
トレース ID を作成し、X-Ray デーモンにセグメントを送信するスクリプトについては、Scorekeep サンプルアプリケーションを参照してください。
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## PutTraceSegments を使用する
セグメントドキュメントは、[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API を使用してアップロードできます。API には、単一のパラメーター (`TraceSegmentDocuments`) があり、これを実行すると、JSON セグメントドキュメントのリストが取得されます。
AWS CLI では、`aws xray put-trace-segments` コマンドを使用してセグメントドキュメントを直接 X-Ray に送信します。
```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
```
**注記**
Windows コマンドプロセッサおよび Windows PowerShell では、JSON 文字列に引用符の使用やエスケープに関する要件が異なります。詳細については、[ ユーザーガイドの「](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)文字列の引用 AWS CLI 」を参照してください。
この出力には、処理に失敗したセグメントが表示されます。たとえば、トレース ID の日付が遠い過去の場合は、次のようなエラーが表示されます。
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
複数のセグメントドキュメントは、スペースで区切って同時に渡すことができます。
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## セグメントドキュメントを X-Ray デーモンに送信する
セグメントドキュメントを X-Ray API に送信する代わりに、セグメントおよびサブセグメントを X-Ray デーモンに送信できます。これにより、バッファされた後、バッチで X-Ray API にアップロードされます。X-Ray SDK は、セグメントドキュメントをデーモンに送信して、 AWS が直接呼び出されないようにします。
**注記**
デーモンを実行する方法については、「[ローカルで X-Ray; デーモンを実行する](xray-daemon-local.md)」を参照してください。
UDP ポート 2000 経由で JSON でセグメントを送信します。先頭にはデーモンのヘッダー `{"format": "json", "version": 1}\n` を追加します。
```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```
Linux では、セグメントドキュメントを Bash ターミナルからデーモンに送信できます。ヘッダーおよびセグメントドキュメントをテキストファイルに保存し、`cat` を使用して `/dev/udp` にパイプします。
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
[デーモンのログ](xray-daemon.md#xray-daemon-logging)を確認し、セグメントが X-Ray に送信されていることを確認します。
```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```
# AWS X-Ray からのデータの取得
AWS X-Ray では、JSON のトレース全体、トレースサマリ、サービスグラフを生成するために送信するトレースデータを処理します。生成されたデータは、AWS CLI を使用して API から直接取得することができます。
**Topics**
+ [サービスグラフの取得](#xray-api-servicegraph)
+ [グループ別サービスグラフの取得](#xray-api-servicegraphgroup)
+ [トレースの取得](#xray-api-traces)
+ [根本原因分析の取得と絞り込み](#xray-api-analytics)
## サービスグラフの取得
JSON サービスグラフを取得するには、[https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) API を使用することができます。この API には、開始時間と終了時間を設定する必要があります。これらは `date` コマンドを使用して Linux 端末から計算することができます。
```
$ date +%s
1499394617
```
`date +%s` は、日付を秒単位で出力します。この数字を終了時間として使用し、日付から差し引いて、開始時間を取得します。
**Example 最後の 10 分間のサービスグラフを取得するスクリプト。**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
次の例では、4 つのノードを持つサービスグラフを示します。これには、クライアントノード、EC2 インスタンス、DynamoDB テーブル、および Amazon SNS トピックが含まれます。
**Example GetServiceGraph 出力**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## グループ別サービスグラフの取得
グループの内容に基づきサービスグラフを呼び出すには、`groupName` または `groupARN` を含めます。以下の例では、Example1 という名前のグループへのサービスグラフの呼び出しを示します。
**Example グループ Example1 の名前別サービスグラフを取得するスクリプト**
```
aws xray get-service-graph --group-name "Example1"
```
## トレースの取得
[https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を使用して、トレースサマリのリストを取得します。トレースサマリには、ダウンロードするトレース全体 (注釈、リクエストと応答に関する情報、ID) などを識別するのに使用できる情報が含まれます。
`TimeRangeType` を呼び出すときに、2 つの `aws xray get-trace-summaries` フラグを使用できます。
+ **TraceId** – デフォルト `GetTraceSummaries` の検索は TraceID 時間を使用し、計算された `[start_time, end_time)` の範囲内で開始されたトレースを返します。このタイムスタンプの範囲は、TraceId 内のタイムスタンプのエンコードに基づいて計算されるか、手動で定義できます。
+ **イベント時間 **– AWS X-Ray では、経時的に発生するイベントを検索するために、イベントのタイムスタンプを使用してトレースを検索できます。イベント時間では、トレースの開始時間に関係なく、`[start_time, end_time)` の範囲内でアクティブなトレースが返されます。
`aws xray get-trace-summaries` コマンドを使用して、トレースサマリのリストを取得します。以下のコマンドは、デフォルトの TraceId 時間を使用して、過去 1 〜 2 分間のトレースサマリーのリストを取得します。
**Example トレースサマリを取得するスクリプト**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries 出力**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
出力のトレース ID を使用して、[https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API でトレース全体を取得します。
**Example BatchGetTraces コマンド**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces 出力**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
トレース全体には、同一のトレース ID を使用して取得されるすべてのセグメントドキュメントからコンパイルされた、各セグメントのドキュメントが含まれます。これらのドキュメントは、アプリケーションによって X-Ray に送信されたデータを表していません。その代わりに、X-Ray サービスによって生成された処理済みドキュメントを表します。X-Ray はアプリケーションによって送信されたセグメントドキュメントをコンパイルして、完全なトレースドキュメントを作成し、[セグメントドキュメントスキーマ](xray-api-segmentdocuments.md)に準拠しないデータを削除します。
X-Ray は、セグメント自体を送信しないサービスへのダウンストリーム呼び出しの*推測セグメント*を作成します。たとえば、計測されたクライアントを使用して DynamoDB を呼び出したときに、X-Ray SDK の視点からの呼び出しに関する詳細をサブセグメントに記録します。ただし、DynamoDB は対応するセグメントを送信しません。X-Ray は、サブセグメントにある情報を使用して、トレースマップで DynamoDB リソースを表す推測セグメントを作成し、トレースドキュメントに追加します。
API から複数のトレースを取得するには、`get-trace-summaries` の出力から [AWS CLI クエリ](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter)を使用して抽出できるトレース ID のリストが必要です。リストから `batch-get-traces` の入力にリダイレクトし、特定の時間のトレース全体を取得します。
**Example 1 分間のトレース全体を取得するスクリプト。**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## 根本原因分析の取得と絞り込み
[GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) を使用して、トレースサマリを生成すると、根本原因に基づいて絞り込まれたフィルタ式を作成するために、部分的なトレースサマリを JSON 形式で再利用できます。絞り込みのステップのウォークスルーについては、以下の例を参照してください。
**Example 例 GetTraceSummaries 出力 - 応答時間の根本原因セクション**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
上記の出力を編集して省略することで、この JSON は一致した根本原因のエンティティのフィルタになる可能性があります。JSON に存在するすべてのフィールドについて、候補は完全に一致する必要があります。そうしないと、トレースが返されません。削除されたフィールドはワイルドカード値になります。これは、フィルタ式クエリ構造と互換性のある形式です。
**Example 再フォーマットされた応答時間の根本原因**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
この JSON は、`rootcause.json = #[{}]` への呼び出しを通じてフィルタ式の一部として使用されます。フィルタ式を使用するクエリの詳細については、「[フィルタ式](xray-console-filters.md)」の章を参照してください。
**Example JSON フィルタの例**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# AWS X-Ray API を使用したサンプリング、グループ、暗号化設定の構成
AWS X-Ray にはAPIs が用意されています。 [サンプリングルールの設定](xray-console-sampling.md) [でのデータ保護AWS X-Ray](xray-console-encryption.md)
**Topics**
+ [暗号化設定](#xray-api-configuration-encryption)
+ [サンプリングルール](#xray-api-configuration-sampling)
+ [グループ](#xray-api-configuration-groups)
## 暗号化設定
[https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html) を使用して、暗号化に使用する AWS Key Management Service (AWS KMS) キーを指定します。
**注記**
X-Ray は非対称 KMS キーをサポートしていません。
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
キー ID には、(例に示すような) エイリアス、キー ID、または Amazon リソースネーム (ARN) を使用できます。
[https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html)を使用して現在の設定を取得します。X-Ray が設定の適用を終了すると、ステータスが [`UPDATING`] から [`ACTIVE`] に変わります。
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
KMS の使用を停止し、デフォルトの暗号化を使用するには、暗号化タイプを `NONE` に設定します。
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## サンプリングルール
X-Ray API を使用して、アカウントの[サンプリングルール](xray-console-sampling.md)を管理できます。タグの追加と管理の詳細については、「[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)」を参照してください。
[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)ですべてのサンプリングルールを取得します。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
別のルールに一致しないすべてのリクエストにデフォルトのルールが適用されます。このルールは最も優先度が低く、削除することはできません。ただし、[https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)を使用してレートとリザーバのサイズを変更できます。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
次の例では、以前のファイルを入力として使用し、デフォルトのルールをリザーバなしの 1% に変更します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。サンプリングルールから既存のタグを削除するための、[UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)の使用
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
[https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html)を使用して追加のサンプリングルールを作成します。ルールを作成するときは、ルールフィールドの大部分を指定する必要があります。次の例では 2 つのルールを作成します。この最初のルールでは、Scorekeep サンプルアプリケーションの基本レートを設定します。これは、より優先度の高いルールに一致しない API からのすべてのリクエストに一致します。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
2 つ目のルールも Scorekeep に適用されますが、このルールはより優先度が高く具体的です。このルールは、ポーリングリクエストに関して非常に低いサンプリングレートを設定します。これらは、ゲームの状態の変更を確認するためにクライアントによって数秒ごとに行われる GET リクエストです。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
サンプリングルールを削除するには、[https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html)を使用します。
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## グループ
X-Ray API を使用して、アカウントのグループを管理することができます。グループは、フィルタ式で定義されるトレースのコレクションです。グループを使用して、追加のサービスグラフを生成し、Amazon CloudWatch メトリクスを指定できます。X-Ray API を使用したサービスグラフとメトリクスの操作の詳細については、「[AWS X-Ray からのデータの取得](xray-api-gettingdata.md)」を参照してください。グループの詳細については、「[グループの設定](xray-console-groups.md)」を参照してください。タグの追加と管理の詳細については、「[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)」を参照してください。
`CreateGroup` を使用してグループを作成します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
`GetGroups` を使用して既存のグループをすべて取得します。
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
`UpdateGroup` を使用してグループを更新します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。グループから既存のタグを削除するには、[UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)を使用します。
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
`DeleteGroup` を使用してグループを削除します。
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# X-Ray API でのサンプリングルールの使用
AWS X-Ray SDK は、X-Ray API を使用してサンプリングルールの取得、サンプリング結果の報告、およびクォータの取得を行います。これらの API を使用すれば、サンプリングルールの仕組みを理解したり、X-Ray SDK でサポートされていない言語でサンプリングを実行したりできます。
まず、[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)を使用してすべてのサンプリングルールを取得します。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
出力には、デフォルトルールとカスタムルールが含まれています。まだサンプリングルールを作成していない場合は、「[サンプリングルール](xray-api-configuration.md#xray-api-configuration-sampling)」を参照してください。
優先度の昇順で受信リクエストのルールを評価します。ルールが一致したら、固定レートとリザーバのサイズを使用してサンプリングデシジョンを作成します。サンプリングされたリクエストを記録し、(トレースを目的とする) サンプリングされていないリクエストは無視します。サンプリングデシジョンが作成されたら、ルールの評価を停止します。
ルールのリザーバのサイズは、固定レートを適用する前に記録する 1 秒あたりのトレースの目標数です。リザーバはすべてのサービスに累積的に適用されるため、直接使用することはできません。ただし、0 以外の場合は、X-Ray がクォータを割り当てるまでリザーバから 1 秒に 1 個トレースを借りることが可能です。クォータを受信する前に、1 秒ごとに最初のリクエストを記録し、追加のリクエストに固定レートを適用します。固定レートは、0～1.00 (100%) の 10 進数です。
次の例は、過去 10 秒間に作成されたサンプリングデシジョンの詳細を含む[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html)の呼び出しを示したものです。
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
X-Ray からのレスポンスには、リザーバから借りる代わりに使用するクォータが含まれています。この例では、サービスがリザーバから 10 秒間に 10 個のトレースを借り、他の 100 個のリクエストに 10% の固定レートを適用した結果、サンプリングされたリクエストの合計数が 20 個になりました。クォータは (有効期限で示される) 5 分間、または新しいクォータが割り当てられるまで有効です。X-Ray では、ここで割り当てられなかったとしても、デフォルトより長いレポート間隔を割り当てる場合があります。
**注記**
最初の呼び出しのときには、X-Ray からのレスポンスにクォータが含まれていない可能性があります。その場合は、クォータが割り当てられるまで、リザーバからクォータを借り続けてください。
レスポンスの他の 2 つのフィールドは、入力の問題を示している可能性があるため、前回呼び出した[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)の `LastRuleModification` を確認します。より新しい場合は、そのルールの新しいコピーを取得します。`UnprocessedStatistics` には、ルールが削除されたこと、入力の統計ドキュメントが古すぎること、またはアクセス許可のエラーが発生していることを示すエラーが含まれている可能性があります。
# AWS X-Ray セグメントドキュメント
**トレースセグメント**は、アプリケーションが対応するリクエストの JSON 表現です。トレースセグメントは、元のリクエストに関する情報、アプリケーションがローカルで実行する作業に関する情報、およびアプリケーションが ** リソース、HTTP API、SQL データベースに対して行うダウンストリーム呼び出しに関する情報の**サブセグメントAWSを記録します。
**セグメントドキュメント**は、セグメントに関する情報を X-Ray に伝えます。セグメントドキュメントは最大で 64 kB とし、サブセグメントを含むセグメント全体、リクエストが進行中であることを示すセグメントのフラグメント、または別個に送信される単一のサブセグメントを含むことができます。セグメントドキュメントは、[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API を使用して直接 X-Ray に送信できます。
X-Ray はセグメントドキュメントをコンパイルおよび処理し、それぞれ [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) および [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API を使用してアクセスできる、クエリ可能な**トレースサマリー**および**トレース全体**を生成します。このサービスは、X-Ray に送信するセグメントとサブセグメントに加えて、サブセグメントの情報を使用して**推測セグメント**を生成し、トレース全体に追加します。推定セグメントは、トレースマップのダウンストリームサービスとリソースを表します。
X-Ray は、セグメントドキュメントの **JSON スキーマ**を提供します。スキーマは、「[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)」からダウンロードできます。スキーマに示されたフィールドとオブジェクトについては、以下のセクションで詳しく説明します。
セグメントフィールドのサブセットは、フィルタ式で使用するために X-Ray によってインデックスが作成されます。たとえば、セグメントの `user` フィールドを一意の ID に設定した場合、X-Ray コンソールで、または `GetTraceSummaries` API を使用して、特定のユーザーに関連付けられたセグメントを検索できます。詳細については、「[フィルター式の使用](xray-console-filters.md)」を参照してください。
X-Ray SDK でアプリケーションを計測すると、SDK によりセグメントドキュメントが生成されます。セグメントドキュメントを直接 X-Ray に送信する代わりに、SDK がそれらのドキュメントをローカル UDP ポート経由で [X-Ray デーモン](xray-daemon.md)に送信します。詳細については、「[セグメントドキュメントを X-Ray デーモンに送信する](xray-api-sendingdata.md#xray-api-daemon)」を参照してください。
**Topics**
+ [セグメントフィールド](#api-segmentdocuments-fields)
+ [サブセグメント](#api-segmentdocuments-subsegments)
+ [HTTP リクエストデータ](#api-segmentdocuments-http)
+ [注釈](#api-segmentdocuments-annotations)
+ [メタデータ](#api-segmentdocuments-metadata)
+ [AWS リソースデータ](#api-segmentdocuments-aws)
+ [エラーと例外](#api-segmentdocuments-errors)
+ [SQL クエリ](#api-segmentdocuments-sql)
## セグメントフィールド
セグメントは、アプリケーションが対応するリクエストに関する追跡情報を記録します。セグメントは、少なくともリクエストの名前、ID、開始時間、トレース ID、および終了時間を記録します。
**Example 最小完了セグメント**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
次のフィールドは、セグメントで必須、または条件付きで必須です。
**注記**
特に明記されていない限り、値は文字列である必要があります (最大 250 文字)。
**必須のセグメントフィールド**
+ `name` – リクエストを処理したサービスの論理名 (最大 **200 文字**)。たとえば、アプリケーション名やドメイン名です。名前には、Unicode 文字、数字、空白、および次の記号を含めることができます:`_` ､`.`､`:`､`/`､`%`､`&`､`#`､`=`､`+`､`\`､`-`､`@`
+ `id` – セグメントの 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。
+ `trace_id` – 1 つのクライアントリクエストから送信されるすべてのセグメントとサブセグメントに接続する一意の識別子です。
**X-Ray のトレース ID 形式**
X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます：
+ バージョン番号、すなわち、`1`。
+ 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。
例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。
+ グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。
**注記**
X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。
**トレース ID セキュリティ**
トレース ID は[レスポンスヘッダー](xray-concepts.md#xray-concepts-tracingheader)に表示されます。攻撃者が将来のトレース ID を計算できないように安全なランダムのアルゴリズムを使用してトレース ID を生成し、その ID を使用してアプリケーションにリクエストを送信します。
+ `start_time` – セグメントが作成された時間の**数値** (エポック時間の浮動小数点で表した秒数)。例えば、`1480615200.010`、`1.480615200010E9` です。必要なだけ桁数を使用します。利用できる場合は、マイクロ秒の精度をお勧めします。
+ `end_time` – セグメントが切断された時間を表す**数値**。例えば、`1480615200.090`、`1.480615200090E9` です。`end_time` または `in_progress` のいずれかを指定します。
+ `in_progress` – ** ではなく ** を設定して、開始されたが完了していないセグメントを記録する`true`ブール値`end_time`。アプリケーションが処理に時間がかかるリクエストを受信したときに、進行中のセグメントを送信して、リクエストの受信を追跡します。レスポンスが送信されると、完了したセグメントが送信され進行中のセグメントを上書きします。リクエストごとに、1 つの完全なセグメントと、1 つまたは 0 個の進行中のセグメントのみを送信します。
**サービス名**
セグメントの `name` は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。権限を持つアプリケーション[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)は、任意の名前でセグメントを送信できます。
次のフィールドは、セグメントではオプションです。
**オプションのセグメントフィールド**
+ `service` – アプリケーションに関する情報を含むオブジェクト。
+ `version` – リクエストに対応したアプリケーションのバージョンを識別する文字列。
+ `user` – リクエストを送信したユーザーを識別する文字列。
+ `origin` – アプリケーションを実行している AWS リソースのタイプ。
**サポートされる値**
+ `AWS::EC2::Instance` – Amazon EC2 インスタンス。
+ `AWS::ECS::Container` – Amazon ECS コンテナ。
+ `AWS::ElasticBeanstalk::Environment` – Elastic Beanstalk 環境
複数の値をアプリケーションに適用する場合は、最も具体的な値を使用します。たとえば、複数コンテナの Docker Elastic Beanstalk の環境では、Amazon ECS コンテナでアプリケーションが実行され、そのコンテナは Amazon EC2 インスタンスで実行されます。この場合、環境は他の 2 つのリソースの親として、オリジンを `AWS::ElasticBeanstalk::Environment` に設定します。
+ `parent_id` – 計測したアプリケーションからリクエストが発信された場合に指定するサブセグメント ID。X-Ray SDK は親サブセグメント ID をダウンストリーム HTTP 呼び出しの[トレースヘッダー](xray-concepts.md#xray-concepts-tracingheader)に追加します。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。
+ `http` – 元の HTTP リクエストに関する情報を含む [`http`](#api-segmentdocuments-http) オブジェクト。
+ `aws` – アプリケーションがリクエストに対応した[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。
+ `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。
+ `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。
+ `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。
+ `subsegments` – **オブジェクトの**配列[`subsegment`](#api-segmentdocuments-subsegments)。
## サブセグメント
サブセグメントを作成して、AWS のサービス と AWS SDK で作成するリソースへの呼び出し、内部または外部 HTTP ウェブ API への呼び出し、あるいは SQL データベースクエリの呼び出しを記録することができます。また、サブセグメントを作成してアプリケーションでコードブロックをデバッグしたり、注釈を付けたりできます。サブセグメントには他のサブセグメントを含めることができるため、内部関数呼び出しに関するメタデータを記録するカスタムサブセグメントには、他のカスタムサブセグメントおよびダウンストリーム呼び出し用のサブセグメントを含めることができます。
サブセグメントは、ダウンストリーム呼び出しを、それを呼び出したサービスの視点から記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。
サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズを超えないようにしたりできます。
**Example 埋め込みサブセグメントを含むセグメント**
独立したサブセグメントには、親セグメントを識別する `type` の `subsegment`、および `parent_id` があります。
```
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}
```
長期間実行されるリクエストについては、進行中のセグメントを送信してリクエストが受信されたことを X-Ray に通知し、セグメントを個別に送信して追跡してから、元のリクエストを完了することができます。
**Example 進行中セグメント**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 独立したサブセグメント**
独立したサブセグメントには、親セグメントを識別する `type` の `subsegment`、`trace_id`、および `parent_id` があります。
```
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
```
リクエストが完了したら、`end_time` とともに再送信してセグメントを閉じます。完了セグメントは進行中のセグメントを上書きします。
非同期ワークフローをトリガーした、完了したリクエストに対してサブセグメントを個別に送信することもできます。たとえば、ウェブ API は、ユーザーがリクエストした作業を開始する直前に `OK 200` 応答を返す場合があります。応答が送信されたらすぐに、完全なセグメントを X-Ray に送信し、それに続いて後で完了する作業のサブセグメントを送信できます。セグメントと同様に、サブセグメントフラグメントを送信して、サブセグメントが開始されたことを記録した後で、ダウンストリーム呼び出しが完了したら完全なサブセグメントでそれを上書きできます。
次のフィールドは、サブセグメントで必須、または条件付きで必須です。
**注記**
特に明記されていない限り、値は文字列です (最大 250 文字)。
**必須のサブセグメントフィールド**
+ `id` – サブセグメントの 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。
+ `name` – サブセグメントの論理名。ダウンストリーム呼び出しの場合は、リソースまたはサービスを呼び出した後のサブセグメントの名前。カスタムサブセグメントの場合は、計測するコードの後にサブセグメントの名前を付けます (関数名など)。
+ `start_time` – サブセグメントが作成された時間を表す**数値**で、エポック時間を浮動小数点で表した秒 (ミリ秒)。例えば、`1480615200.010`、`1.480615200010E9` です。
+ `end_time` – サブセグメントが切断された時間を表す**数値**。例えば、`1480615200.090`、`1.480615200090E9` です。`end_time` または `in_progress` を指定します。
+ `in_progress` – ** ではなく ** を設定して、開始されたが完了していないサブセグメントを記録する`true`ブール値`end_time`。ダウンストリームリクエストごとに、1 つの完全なサブセグメントと、1 つまたは 0 個の進行中のサブセグメントのみを送信します。
+ `trace_id` – サブセグメントの親セグメントのトレース ID。サブセグメントを個別に送信する場合にのみ必要です。
**X-Ray のトレース ID 形式**
X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます：
+ バージョン番号、すなわち、`1`。
+ 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。
例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。
+ グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。
**注記**
X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。
+ `parent_id` – サブセグメントの親セグメントのセグメント ID。サブセグメントを個別に送信する場合にのみ必要です。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。
+ `type` – `subsegment`。サブセグメントを個別に送信する場合にのみ必要です。
次のフィールドは、サブセグメントではオプションです。
**オプションのサブセグメントフィールド**
+ `namespace` – AWS SDK 呼び出しの場合は `aws`、他のダウンストリーム呼び出しの場合は `remote`。
+ `http` – 送信 HTTP 呼び出しに関する情報を含む [`http`](#api-segmentdocuments-http) オブジェクト。
+ `aws` – アプリケーションが呼び出したダウンストリーム[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。
+ `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。
+ `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。
+ `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments)オブジェクトの**配列**。
+ `precursor_ids` – このサブセグメントの前に完了した同じ親を持つサブセグメントを識別するサブセグメント ID の**配列**。
## HTTP リクエストデータ
HTTP ブロックを使用して、(セグメントで) アプリケーションが対応した HTTP リクエスト、または (サブセグメントで) アプリケーションがダウンストリーム HTTP API に対して行ったリクエストの詳細を記録します。このオブジェクトのほとんどのフィールドは、HTTP リクエストと応答で見つかった情報にマッピングされます。
**`http`**
すべてのフィールドはオプションです。
+ `request` – リクエストに関する情報。
+ `method` – リクエストメソッド。例えば、`GET`。
+ `url` – リクエストのプロトコル、ホスト名、およびパスからコンパイルされた、リクエストの完全な URL。
+ `user_agent` – リクエスタのクライアントからのユーザーエージェント文字列。
+ `client_ip` – リクエスタの IP アドレス。IP パケットの `Source Address` から、または転送リクエストの場合は `X-Forwarded-For` ヘッダーから取得できます。
+ `x_forwarded_for` – (セグメントのみ) ** が ** ヘッダーから読み取られ、偽造されている可能性があるため信頼できないことを示す`client_ip`ブール値`X-Forwarded-For`。
+ `traced` – (サブセグメントのみ) ダウンストリーム呼び出しが別の追跡されたサービスであることを示す**ブール値**。このフィールドが `true` に設定されている場合、このブロックを含むサブセグメントの `parent_id` に一致する `id` を含むセグメントをダウンストリームサービスがアップロードするまで、X-Ray はトレースが壊れていると見なします。
+ `response` – レスポンスに関する情報。
+ `status` – レスポンスの HTTP ステータスを示す**整数**。
+ `content_length` – レスポンス本文の長さをバイト単位で示す**整数**。
ダウンストリームウェブ API に対する呼び出しを計測するときは、HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。
**Example Amazon EC2 で実行しているアプリケーションにより提供される HTTP 呼び出し用のセグメント**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example ダウンストリーム HTTP 呼び出しのサブセグメント**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example ダウンストリーム HTTP 呼び出しの推定セグメント**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## 注釈
セグメントとサブセグメントは、X-Ray がフィルタ式で使用するためにインデックスを作成する 1 つ以上のフィールドが含まれた `annotations` オブジェクトを含むことができます。フィールドは、文字列、数値、またはブール値を持つことができます (オブジェクトや配列を含むことはできません)。X-Ray は、トレースごとに 50 の注釈までインデックスを付けます。
**Example 注釈を使用した HTTP 呼び出しのセグメント**
```
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
キーはフィルタで動作するために英数字である必要があります。アンダースコアは使用できます。その他の記号や空白は使用できません。
## メタデータ
セグメントとサブセグメントは、オブジェクトと配列を含めて、任意の型の値を持つ 1 つ以上のフィールドが含まれた `metadata` オブジェクトを含むことができます。X-Ray はメタデータのインデックスを作成せず、セグメントドキュメントが最大サイズ (64 kB) を超えない限り、任意のサイズにすることができます。[https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API によって返された完全なセグメントドキュメントで、メタデータを表示できます。`debug` で始まるフィールドキー (次の例の `AWS.`) は、AWS が提供する SDK およびクライアントでの使用のために予約されています。
**Example カスタムサブセグメントとメタデータ**
```
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}
```
## AWS リソースデータ
セグメントの場合、`aws` オブジェクトはアプリケーションが実行されているリソースに関する情報を含みます。複数のフィールドを単一のリソースに適用できます。たとえば、Elastic Beanstalk の複数コンテナの Docker 環境で実行されているアプリケーションは、Amazon EC2 インスタンス、インスタンス上で実行されている Amazon ECS コンテナ、および Elastic Beanstalk 環境自体に関する情報を持つことができます。
**`aws` (セグメント)**
すべてのフィールドはオプションです。
+ `account_id` – アプリケーションが別の AWS アカウント にセグメントを送信する場合、アプリケーションを実行しているアカウントの ID を記録します。
+ `cloudwatch_logs` – 単一の CloudWatch ロググループを記述するオブジェクトの配列。
+ `log_group` – CloudWatch のロググループ名。
+ `arn` – CloudWatch のロググループ ARN。
+ `ec2` – Amazon EC2 インスタンスに関する情報。
+ `instance_id` – EC2 インスタンスのインスタンス ID。
+ `instance_size` – EC2 インスタンスのタイプ。
+ `ami_id` – Amazon マシンイメージ ID。
+ `availability_zone` – インスタンスが実行されているアベイラビリティーゾーン。
+ `ecs` – Amazon ECS コンテナに関する詳細。
+ `container` – コンテナのホスト名。
+ `container_id` – コンテナの完全なコンテナ ID。
+ `container_arn` – コンテナインスタンスの ARN。
+ `eks` – Amazon EKS クラスターに関する情報。
+ `pod` – EKS ポッドのホスト名。
+ `cluster_name` – EKS クラスター名。
+ `container_id` – コンテナの完全なコンテナ ID。
+ `elastic_beanstalk` – Elastic Beanstalk 環境に関する情報。この情報は、最新の Elastic Beanstalk プラットフォームの `/var/elasticbeanstalk/xray/environment.conf` という名前のファイルにあります。
+ `environment_name` – 環境の名前。
+ `version_label` – リクエストに対応したインスタンスに現在デプロイされているアプリケーションバージョンの名前。
+ `deployment_id` – リクエストに対応したインスタンスに対して最後に成功したデプロイの ID を示す**数値**。
+ `xray` – 使用した計測のタイプとバージョンに関するメタデータ。
+ `auto_instrumentation` – 自動計測が使用されたかどうかを示すブール値 (例えば、Java Agent)。
+ `sdk_version` – 使用中の SDK またはエージェントのバージョン。
+ `sdk` – SDK のタイプ。
**Example AWSプラグインを使用した ブロック**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
サブセグメントの場合、アプリケーションがアクセスする AWS のサービス およびリソースに関する情報を記録します。X-Ray はこの情報を使用して、サービスマップのダウンストリームサービスを表す推定セグメントを作成します。
**`aws` (サブセグメント)**
すべてのフィールドはオプションです。
+ `operation` – AWS のサービス またはリソースに対して呼び出された API アクションの名前。
+ `account_id` – アプリケーションが別のアカウントのリソースにアクセスするか、別のアカウントにセグメントを送信する場合は、アプリケーションがアクセスした AWS リソースを所有しているアカウントの ID を記録します。
+ `region` – リソースがアプリケーションとは異なるリージョンにある場合は、そのリージョンを記録します。例えば、`us-west-2`。
+ `request_id` – リクエストの一意の識別子。
+ `queue_url` – Amazon SQS キューのオペレーションの場合は、キューの URL。
+ `table_name` – 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",
}
}
```
## エラーと例外
エラーが発生した場合は、エラーと生成された例外に関する詳細を記録できます。アプリケーションがユーザーにエラーを返す場合はセグメントにエラーを記録し、ダウンストリーム呼び出しがエラーを返す場合はサブセグメントにエラーを記録します。
**エラーのタイプ**
次の 1 つ以上のフィールドを `true` に設定して、エラーが発生したことを示します。複合エラーの場合は、複数のタイプを適用できます。たとえば、ダウンストリーム呼び出しからの `429 Too Many Requests` エラーにより、アプリケーションは `500 Internal Server Error` を返すことがあり、その場合は 3 つすべてのタイプが適用されます。
+ `error` – クライアントエラーが発生したことを示す**ブール値** (レスポンスステータスコードは 4XX Client Error でした)。
+ `throttle` – リクエストが調整されたことを示す**ブール値** (レスポンスステータスコードは *429 Too Many Requests* でした)。
+ `fault` – サーバーエラーが発生したことを示す**ブール値** (レスポンスステータスコードは 5XX Server Error でした)。
セグメントまたはサブセグメントに **cause** オブジェクトを含めてエラーの原因を示します。
**`cause`**
原因は、**16 文字**の例外 ID、または次のフィールドを含むオブジェクトとすることができます。
+ `working_directory` – 例外が発生したときの作業ディレクトリのフルパス。
+ `paths` – 例外が発生したときに使用されているライブラリまたはモジュールへのパスの**配列**。
+ `exceptions` – **例外**オブジェクトの**配列**。
1 つまたは複数の**例外**オブジェクトのエラーに関する詳細情報を含めます。
**`exception`**
すべてのフィールドはオプションです。
+ `id` – 例外の 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。
+ `message` – 例外メッセージ。
+ `type` – 例外のタイプ。
+ `remote` – ダウンストリームサービスによって返されたエラーが原因で例外が発生したことを示す**ブール値**。
+ `truncated` – ** から省略されたスタックフレームの数を示す**整数`stack`。
+ `skipped` – この例外とその子の間でスキップされた例外 (発生した例外) の数を示す**整数**。
+ `cause` – 例外の親 (この例外を発生させた例外) の例外 ID。
+ `stack` – **stackFrame** オブジェクトの**配列**。
使用可能な場合、コールスタックに関する情報を **stackFrame** オブジェクトに記録します。
**`stackFrame`**
すべてのフィールドはオプションです。
+ `path` – ファイルの相対パス。
+ `line` – ファイルの行。
+ `label` – 関数またはメソッド名。
## SQL クエリ
アプリケーションが SQL データベースに対して実行するクエリのサブセグメントを作成できます。
**`sql`**
すべてのフィールドはオプションです。
+ `connection_string` – SQL Server または URL 接続文字列を使用しないその他のデータベース接続の場合は、パスワードを除く接続文字列を記録します。
+ `url` – URL 接続文字列を使用するデータベース接続の場合は、パスワードを除く URL を記録します。
+ `sanitized_query` – データベースクエリと、プレースホルダーによって削除または置換されたユーザー指定の値。
+ `database_type` – データベースエンジンの名前。
+ `database_version` – データベースエンジンのバージョン番号。
+ `driver_version` – アプリケーションが使用するデータベースエンジンドライバーの名前とバージョン番号。
+ `user` – データベースユーザー名。
+ `preparation` – クエリで `call` を使用した場合は `PreparedCall`、クエリで `statement` を使用した場合は `PreparedStatement`。
**Example サブセグメントと SQL クエリ**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```