AWS X-Rayのトレース検索でよく利用するフィルター式まとめ
こんにちは。システム開発部スペシャリストのkiwiです。
AWS X-RayはAWSから提供されている分散アプリケーション分析とデバッグのためのツールです。SDKと計測設定を追加することにより、特にマイクロサービスアーキテクチャのパフォーマンス計測・改善に役立てることができます。
当社ではサーバーレスAPIのほか、Spring bootで構築したアプリケーションのパフォーマンス分析のためにX-Rayを導入しています。アプリケーションの計測を実装するためのX-Ray SDKは各言語で公開されていますが、Springアプリケーションの場合はSpring AOPを活用することで効率よく計測を開始することができます（ドキュメント）。
このページでは、X-Rayを使ってトレースを検索する際に利用するクエリをご紹介します。目的のトレースを見つけ、パフォーマンス改善にお役立てください。
なお、この後ご紹介するスクリーンショットは、Cloud Watchと統合された新しいコンソール画面を利用しています。
トレース検索・一覧画面
トレース検索・一覧画面へは、CloudWatch > X-Rayトレース > トレースからアクセスします。
上部にトレースの検索範囲となる時間を選択するフォームがあり、中段にクエリボックスとクエリリファイナー（後述）、そして検索結果のトレース一覧が表示されています。クエリボックスにフィルター式を入力し、「クエリの実行」をクリックするとクエリが検索され、トレース一覧に反映されます。
検索範囲の時間はデフォルトの選択肢で6時間までで、「カスタム」からより広い期間で検索することもできますが、トレースのスキャンに対して課金が発生するため（料金ページ参照）、むやみに長い期間を指定して検索することはおすすめしません。
トレース一覧は各カラムでソートすることができます。デフォルトではタイムスタンプ順ですが、応答時間でソートすることで、レスポンスに時間がかかったトレースを確認できます。
右サイドバーでは、フィルターに利用できるキーワードや、よくある検索のクエリが見れるようになっており、直接クエリボックスに反映することも可能です。このページで紹介している内容と合わせてご活用ください。
クエリリファイナー
クエリリファイナーは、GUIからトレースの検索条件を組み立てることができるツールです。単純なクエリであればこのツールからも検索条件が作成できます。絞り込みたい項目を選択し、「クエリに追加」をクリックするとクエリボックスに内容が反映されるので、「クエリを実行」します。
クエリリファイナーの下部には、応答時間分布・所要時間分布のグラフも表示されます。グラフ上で時間の範囲を選択でき、その範囲がそのままクエリボックスに挿入されます。
基本的な構文
トレースの検索クエリはフィルター式（filter expressions）で記述します。ここからの説明は公式ドキュメント（Using filter expressions）を参考にしています。
フィルター式の構文は以下の通りです。
keyword operator value例えば、応答時間が5秒以上のトレースを検索する場合は以下のようになります。
responsetime > 5複数の条件を組み合わせる場合は AND と OR を使います。
絞り込みに使える主な項目と利用例
絞り込みに利用できる主要な項目を、検索例とともにご紹介します。これらの検索を組み合わせて、目的のトレースを検索していきます。
ノード
service() キーワードを使って、トレースに特定のノードが含まれるものを検索します。例えば、以下のような指定をすると、API api.example.com の呼び出しを含むトレースを検索します。
service("api.example.com")この後ろに条件をつなげることもできます。例えば、このAPIが500番台のエラーレスポンスを返したトレースに絞り込むクエリは以下のようになります。fault は、レスポンスコードが500番台である場合にtrueとなるboolean型のキーワードです。
service("api.example.com") { fault }X-Ray Java SDKを利用してアプリケーションのトレースを行う場合、検索に利用する「サービス名」は環境変数やコード内で指定します。例えばSpringアプリケーションで以下のように tracingFilter() メソッドが実装されている場合、サービス名は SampleApplication となります。
@Bean
fun tracingFilter(): Filter {
return AWSXRayServletFilter("SampleApplication")
}クエリリファイナーを使った指定では、サービスをより厳密に指定したクエリが挿入されます。
service(id(name: "SampleApplication" , type: "AWS::ECS::Container" )なお、ここで指定するサービス名は、サンプリングルールを設定する際にも使用します。
リクエストURL
http.url キーワードを使うと、リクエストURLを使ってフィルタリングできます。比較演算子として、完全一致 = != のほかに、部分一致 CONTAINS や、最初/最後の一致 BEGINSWITH ENDSWITH が使用できます。
例えば、URLに /api/game/ を含むトレースを検索する場合は以下の通りです。
http.url CONTAINS "/api/game/"ドメインで絞り込む場合は BEGINSWITH を使用します。アプリケーションのトレースのうち、ELBからのヘルスチェック（IPアドレスがホストになっているもの）を除外する場合などに利用できます。
http.url BEGINSWITH "https://www.example.com"リクエストの情報としてはほかに以下のような内容で検索が可能です。
- メソッド
http.method - ユーザーエージェント
http.useragent - クライアントIPアドレス
http.clientip
HTTP ステータスコード
http.status キーワードを使うと、ステータスコードで検索ができます。例えば、200以外のステータスコードを返却したトレースは以下のように検索します。
http.status != 200また、ステータスコードについてはよく使われる条件がboolean型のキーワードとして用意されています。
- 200番台
ok - 400番台
error - 429（Too many requests）
throttle - 500番台
fault
特定のAPIでスロットルが発生したトレースの検索は以下のようになります。
service("api.example.com") { throttle }レスポンス時間・所要時間
レスポンスまでにかかった時間（responsetime）や、処理全体の所要時間（duration）を使って絞り込むことができます。クエリリファイナーの時間分布で範囲を選択した際に、こちらのキーワードが使われます。
例えば、レスポンスに5秒以上かかったトレースは以下のように絞り込みます。
responsetime >= 5エントリーポイント
root キーワードを使うと、トレースの起点となるサービスを指定できます。
service("SampleApplication") { root }エラーメッセージ
発生した例外（Root cause）をエラーメッセージで絞り込みたい場合は、exceptionのうちmessageを指定します。例えば、Connection reset by peerというmessageの例外を検索する例が以下の通りです。
rootcause.fault.exception { message = "Connection reset by peer" }一度 fault などで絞り込んだ後、クエリリファイナーの「障害の根本原因メッセージ」を選択すると、メッセージごとの件数の概要を見ることができるので、原因調査に活用することができます。
注釈
アプリケーションで任意の情報を注釈としてセグメントに対して記録することで、注釈の有無や内容によってトレースを絞り込むことができます。annotation[key] キーワードを使います。
以下の例ではそれぞれ、request.id という注釈が付与されたトレース、request.id に 917DL6VO という値がセットされたトレースに絞り込んでいます。
annotation[request.id]
annotation[request.id] = "917DL6VO"Javaアプリケーションでセグメントに注釈を付与する例は、「X-Ray SDK for Java を使用してセグメントに注釈とメタデータを追加する」に記載されています。検索に利用できない付加情報としてメタデータを付与することもできます。
グループ
あらかじめ作成したフィルター式に名前をつけて、グループとして定義することができます。作成したグループは group.name というキーワードでクエリに利用できるほか、クエリ左側のドロップダウンから特定のグループを選択してクエリに反映させることも可能です。
グループに関する詳細はドキュメント「グループの設定」をご覧ください。
さいごに
今回の例ではWebアプリケーションのパフォーマンス分析で主に使用する項目とクエリをご紹介しました。当社ではこれらのクエリを活用して、レスポンスが特に悪化しているリクエストについてボトルネックを調査し、パフォーマンスの改善に活用しています。
クエリリファイナーでは完全一致でのフィルターが多いのですが、URLの部分一致など便利な検索方法もありますので、ぜひ活用してください。また、分散アプリケーションのトレース検索で主に使用する検索方法などはご紹介しきれていないため、公式ドキュメントも参考にしてください。
掲載内容は、記事執筆時点の情報をもとにしています。
