トレースを検索して調査する

個々のトレースを詳細に検索して調査するには、[Trace エクスプローラ] ページを使用します。このページには、Google Cloud プロジェクトに少なくとも 1 つのスパンが保存されているトレースが表示されます。表示されたトレースとスパンごとに表示されるデータには、レイテンシやコマンドタイプなどの要約情報と詳細情報が含まれます。詳細情報には、ログ、イベント、その他の情報が含まれます。

[Trace エクスプローラ] ページには、最大 1,000 件のトレースが表示されます。

始める前に

Google Cloud コンソールを使用してトレースデータを表示するために必要な権限を取得するには、プロジェクトに対するCloud Trace ユーザー（roles/cloudtrace.user）IAM ロールを付与するよう管理者に依頼してください。ロールの付与の詳細については、アクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ロールの詳細については、Identity and Access Management を使用してアクセスを制御するをご覧ください。

最近のトレースを表示する

最新のトレースを表示するには、次の操作を行います。

Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
[Trace エクスプローラ] に移動

このページは、検索バーを使用して見つけることもできます。

Trace を初めて使用する場合は、トレースが表示されるまでに数分かかることがあります。次のスクリーンショットは、[Trace エクスプローラ] ページの例を示しています。

散布図には、選択した期間内のリクエストがそれぞれドットで表示されます。
- リクエストの（x、y）(x,y)座標は、リクエストの時間とレイテンシに対応しています。
- エラー情報はドットの色でエンコードされます。青は成功、赤は失敗を示します。上のスクリーンショットでは、ほとんどのコマンドが正常に完了しています。
- ドットの上にポインタを置くと有効化されるツールチップには、日付、時間、URI、レイテンシが表示されます。
省略可: 表示されるトレースとスパンにフィルタを適用するには、次のいずれかを行います。
- 時間でフィルタします。デフォルトでは、直近 1 時間のデータが表示されます。カスタムの期間を表示する方法は次のとおりです。
  1. カスタムの期間より長いプリセットオプションを選択します。
  2. 期間の一方の端に [Select a trace] プロットのポインタを置き、期間のもう一方の端までポインタを水平にドラッグします。
  グラフをプリセットの期間に戻すには、[リセット] をクリックします。
- レイテンシでフィルタします。デフォルトでは、選択した期間内のすべてのトレースが表示されます。レイテンシが一定間隔内のトレースに表示を限定するには、レイテンシ値の一方の端にポインタを置き、もう一方の端までポインタを垂直にドラッグします。
  
  グラフをプリセットの期間に戻すには、[リセット] をクリックします。
- [トレースフィルタを追加] をクリックし、フィルタオプションを選択して、フィルタ値を選択または入力します。複数のフィルタを追加すると、すべてのフィルタを満たすトレースのみが表示されます。たとえば、HTTP GET コマンドが含まれているレイテンシが 2 秒以上のトレースをすべて表示するには、Method: GET と MinLatency: 2000 のフィルタを追加します。
  
  以下のフィルタオプションは常に利用可能です。
  - RootSpan: ルートスパン名を照合します。
  - SpanName: スパン名を照合します。
  - Method: ルートスパンに /http/method ラベルが付けられ、ラベルの値がフィルタ値と一致するトレースを表示します。
  - ステータス: ルートスパンに /http/status_code ラベルが付けられ、ラベルの値がフィルタ値と一致するトレースを表示します。フィルタ値には、301 などの特定のステータスコードや、3xx などのステータス値の範囲を含めることができます。
  - MinLatency: レイテンシがフィルタ値と同じかそれ以上のトレースを表示します。フィルタ値はミリ秒単位にする必要があります。
  - HasLabel: フィルタ値で指定されたラベルが 1 つ以上のスパンに表示されるトレースを表示します。
  - Service: サービス名がフィルタ値と一致するスパンが少なくとも 1 つ含まれているトレースを表示します。
    
    OpenTelemetry 属性 service.name が設定されると、スパンのサービス名がその属性から抽出されます。この属性が設定されておらず、サービスが App Engine で実行されている場合は、App Engine サービス名が表示されます。それ以外の場合は、サービスは指定されません。
  - Version: （App Engine のみ）アプリケーションのバージョンがフィルタ値と一致するスパンが少なくとも 1 つ含まれているトレースを表示します。
  URL や HTTP ラベルなどのフィルタオプションが表示される場合があります。事前定義されたフィルタと一致するユーザー定義のラベルがある場合、この 2 つのラベルを区別できるようにユーザー定義のラベルの先頭には LABEL が付きます。たとえば、Service ラベルを作成すると、フィルタメニューに [Service] と [LABEL: Service] の両方が表示されます。
  
  注: 完全一致を行うには、フィルタ値の前にプラス記号（+）を付けます。プラス記号を省略した場合は、フィルタ値の接頭辞テストを実行すると一致が判別されます。フィルタオプションの詳細については、トレースフィルタをご覧ください。

ID でトレースを検索する

インシデントや障害をトラブルシューティングするときに、トレース ID がわかっている場合があります。そのトレースを調べるには、次の手順を行います。

Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
[Trace エクスプローラ] に移動

このページは、検索バーを使用して見つけることもできます。
トレースデータを表示する Google Cloud プロジェクトを選択します。

プロジェクトが組織の一部でない限り、トレースデータを保存する Google Cloud プロジェクトを選択する必要があります。プロジェクトが組織の一部である場合、プロジェクト間のトレースを構成できます。これにより、組織内の任意のプロジェクトからトレースデータを表示できます。詳細については、複数のプロジェクトにわたるトレースの表示をご覧ください。
[トレース ID] フィールドに ID を入力します。

有効な ID を入力すると、[トレースの詳細] ペインにトレースとそのスパンに関する情報が入力されます。そのペインのオプションを使用して、トレースを調査できます。

トレースを調査する

トレースを調査するには、散布図のドットをクリックします。散布図のドットをクリックすると、[Trace エクスプローラ] ページに次の変更が行われます。

散布図が更新され、選択したドットが円で囲まれてハイライト表示されます。他のすべてのトレースを表すドットはグレー表示されます。
[トレースの詳細] ペインには、次の情報が表示されます。
- トレース ID。このトレースのグローバル固有識別子は、32 バイトの 16 進数文字列で表される 128 ビットの整数です。詳細については、Resource: Trace をご覧ください:
- 開始時刻、期間、スパン数を一覧表示するサマリー行。
- [ログとイベント] メニュー。メニューの選択は、ログとイベントの表示方法を制御します。デフォルトでは、ログまたはイベントが存在する場合、トレーススパンに円が追加されます。重複する円は、スパンに複数のログまたはイベントがあることを示します。各ログまたはイベントをテーブルの行として表示するには、 [ログとイベント] を展開し、[展開して表示] を選択します。
- テーブル。表の最初の行はトレース用です。トレースのスパンごとに 1 行が追加されます。
  
  スパンについては、テーブルにスパンの名前とスパンに関連付けられているサービスが表示されます。OpenTelemetry 属性 service.name が設定されると、サービス名はその属性から抽出されます。この属性が設定されておらず、サービスが App Engine で実行されている場合は、App Engine サービス名が表示されます。それ以外の場合は、サービスは指定されません。
  
  [レイテンシ] 列には、レイテンシ、ステータス、イベントのアノテーション（存在する場合）が視覚的に表示されます。青色のレイテンシバーは正常に完了したことを示し、赤色のレイテンシバーはエラーが発生したことを示します。スペース内の各イベントアノテーションは、レイテンシバー上の円で表現されます。

以下は、[トレースの詳細] ペインの例を示しています。

Cloud Trace の詳細ペインの例。

トレース内のスパンを検索する

トレース内のスパンや属性をキーワードで検索できます。たとえば、前のスクリーンショットでは、一部のスパンと属性キーがハイライト表示されています。これらのフィールドは、検索キーワード（net.sock.peer.port）と一致するためハイライト表示されています。

トレース内のスパンを検索するには、[トレースの詳細] ペインのツールバーで、[Trace で検索] フィールドに検索キーワードを入力し、Enter キーを押します。

Trace では、表示されたトレース内で各スパンの選択したフィールドを検索します。大文字と小文字が区別されず、検索フィールドに検索キーワードが含まれている場合に一致します。次のフィールドが検索されます。

スパン名。
サービス名。
属性のキーと値。

検索が完了すると、[トレースの詳細] ペインが更新され、一致するフィールドがハイライト表示されます。

たとえば、用語 get を入力すると、キーが /http/method で、値が GET の属性を持つスパンがハイライト表示されます。また、CurrencyService/GetSupportedCurrencies などの名前を持つスパンもハイライト表示されます。

正規表現を使用して検索することはできません。また、ログ、イベント、メタデータを検索することもできません。

スパンの詳細を表示する

トレースまたは特定のスパンに関する詳細情報を表示するには、[トレースの詳細] ペインで、エントリのレイテンシバーをクリックします。レイテンシバーを選択すると、[トレースの詳細] ペインが再表示され、エントリに関する追加情報を提供するタブ付きテーブルが表示されます。

テーブルの最初の行で Trace ID という名前の行のレイテンシバーを選択すると、テーブルには [概要] と [ログ] という 2 つのタブが表示されます。[概要] タブには、トレースに関する一般的な情報が表示されます。たとえば、HTTP コマンドの場合、このタブには、トレース内の各スパンの HTTP コマンドのタイプ、サービス、レイテンシ情報が表示されます。

テーブル内の他の行のレイテンシバー、つまりスパンの行を選択すると、テーブルには [属性]、[ログとイベント]、[スタックトレース]、[メタデータ] という 4 つのタブが表示されます。

スパンに添付されたラベルを見つけるには、[属性] タブを表示します。ラベルの詳細については、Trace のラベルをご覧ください。次のスクリーンショットはこのタブを示しています。

特定のラベルまたはラベルのグループを検索するには、フィルタを追加します。たとえば、フィルタ Key: g.co を追加すると、ラベルキーに g.co が含まれるすべてのラベルがテーブルに表示されます。
関連するログエントリとイベント（存在する場合）に関する情報を表示するには、[ログとイベント] タブを表示します。イベントアノテーションについて詳しくは、トレーススパンへのアノテーション付けをご覧ください。次のスクリーンショットはこのタブを示しています。

ログデータが利用可能な場合、ログエントリの詳細を表示するには、 [さらに表示] をクリックします。
利用可能なスタックトレースの数とキャプチャされたスタックトレースに関する詳細情報を検索するには、[スタックトレース] タブを使用します。
スパンに関する一般的な情報と、他のスパンへのリンクの表を確認するには、[メタデータとリンク] タブを表示します。詳細情報には次の情報が含まれます。
- スパン ID
  
  スパン ID は 0 以外の 64 ビット整数です。詳細については、TraceSpan をご覧ください:
- 親スパン ID
- プロジェクト ID
- 開始時間と終了時間
- 他のスパンへのリンクを一覧表示するテーブル
  
  Links というテーブルの各行に、現在のスパンと別のスパンの間のリンクが一覧表示されます。[属性] フィールドには、リンク先のスパンの Key-Value ペアが表示されます。[トレース] フィールドは、リンク先のスパンのトレースにリンクしています。このフィールドに現在のトレースが含まれている場合、リンク先のスパンは現在のスパンと同じトレースに含まれます。それ以外の場合、このフィールドにはトレース ID が含まれます。リンクの詳細については、Links API リファレンスページをご覧ください。
次のスクリーンショットはこのタブを示しています。