トレースデータの集計表現を表示する、または特定のラベルを含む個々のトレースやトレースを検索して調査するには、[Trace エクスプローラ] ページを使用します。
次のスクリーンショットは、トレース データがどのように表示されるかを示しています。
この機能は Google Cloud プロジェクトでのみサポートされています。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
[Trace エクスプローラ] ページについて
トレースデータの傾向とパターンを特定できるように、レイテンシ データが集計され、グラフに表示されます。ヒートマップでは、セルのスパンの数が色で表されます。スパンの多いセルは、スパンの少ないセルよりも色が濃くなります。各セルのツールチップには、レイテンシなどの情報が表示されます。レイテンシのパーセンタイルとスパン率の情報も表示できます。
問題を調査する際に、特定のトレースや特定のプロパティを持つスパンのみを表示することがあります。
表示されるスパンを制限するには、フィルタを適用します。たとえば、サービス、アプリケーション、エラー状態などのプロパティでフィルタできます。
特定のトレースを表示するには、ツールバーの [ページビュー] [トレースを検索] オプションを使用します。
外れ値を特定し、個々のスパンの詳細を表示するには、表形式のセクションを使用します。
[スパン] タブと [グループ化] タブの行は、期間ヘッダーで並べ替えることができます。
さまざまなサービスで生成されているスパンの数を確認するには、[グループ化] タブを使用します。各行はサービスとスパン名に対応し、各エントリのレイテンシ統計情報が表示されます。
スパンまたはグループ化の詳細を確認するには、表形式のセクションの行からエントリを選択します。トレースのコンテキストでスパンを表示するフライアウトが開きます。このビューでは、スパンとその属性を調べたり、イベントとログデータを表示したりできます。トレース内のスパンや属性をキーワードで検索することもできます。
[Trace エクスプローラ] ページで使用されるトレースデータは、次の要素によって異なります。
- トレースデータの検索対象となるプロジェクト。デフォルトでは、システムはプロジェクト選択ツールで選択したプロジェクトのトレースデータのみを検索します。ただし、トレース スコープのプロジェクトのリストを検索するようにページを構成できます。
- 検索対象プロジェクトに対する Identity and Access Management（IAM）権限。プロジェクトのトレース データを表示する権限がない場合、 Google Cloud コンソールに警告メッセージが表示され、そのプロジェクトのデータは表示されません。
- 期間の設定。
- 適用するフィルタ。
このページの残りの部分では、トレースデータを検索して調査する方法について詳しく説明します。
始める前に
Google Cloud コンソールを使用してトレースデータを表示し、トレース スコープを選択するために必要な権限を取得するには、プロジェクトに対する Cloud Trace ユーザー （roles/cloudtrace.user）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。
この事前定義ロールには、 Google Cloud コンソールを使用してトレースデータを表示し、トレーススコープを選択するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。
必要な権限
Google Cloud コンソールを使用してトレースデータを表示し、トレース スコープを選択するには、次の権限が必要です。
-
トレース スコープを選択する:
cloudtrace.traceScopes.[get, list] -
デフォルトのトレース スコープを読み取る:
observability.scopes.get
カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。
ロールの詳細については、Identity and Access Management を使用してアクセスを制御するをご覧ください。
集計されたトレースデータを表示する
トレースデータに関する集計情報を表示する手順は次のとおりです。
-
Google Cloud コンソールで、[Trace エクスプローラ] ページに移動します。
このページは、検索バーを使用して見つけることもできます。
最初のトレースデータが Google Cloud プロジェクトに書き込まれてから、そのデータを表示できるようになるまで数分かかることがあります。数分待ってもトレースデータが表示されない場合は、プロジェクトに表示するデータがないか、構成に問題がある可能性があります。これらの問題を解決する方法については、トラブルシューティング: トレース インターフェースにデータがないをご覧ください。
[Trace エクスプローラ] ページを構成します。
- Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。
省略可: Scope 要素を使用して、トレースデータが検索されるプロジェクトを構成します。
プロジェクトに保存されているトレースデータを表示するには、[Scope] 要素の最初のメニューを
[Project] または 
[_Default] に設定します。この 2 つの設定は同等です。複数のプロジェクトに保存されているトレースデータを表示するには、[スコープ] 要素の最初のメニューを開き、[トレース スコープ] を選択して、これらのプロジェクトが一覧表示されているトレース スコープを選択します。選択すると、[スコープ] メニューにトレース スコープ アイコン
と、選択したトレース スコープの名前が表示されます。
返されるデータは、検索対象のプロジェクトに対する IAM ロールによって異なります。たとえば、検索されたプロジェクトにアクセス権のない Google Cloud プロジェクトが含まれている場合、そのプロジェクトのトレースデータは返されません。
詳細については、トレース スコープの作成と管理をご覧ください。
省略可: 期間セレクタを使用するか、ポインタを使用して X 軸の範囲をハイライト表示して、期間を更新します。
たとえば、レイテンシ データに傾向があるかどうかを確認する場合は、このセレクタを [過去 2 週間] に設定します。スパンデータは 30 日間保存されます。
ヒートマップを確認する:
色を使用して、傾向と外れ値を特定します。スパンが多いセルは、スパンが少ないセルよりも色が濃くなります。
セルのツールチップを使用して、セルの詳細を表示します。ツールチップには、スパンの数、日時、セルの時間間隔が表示されます。
レイテンシのパーセンタイルとエラー率を確認します。
レイテンシの傾向を表示するには、[グラフビュー] メニューを [スパン期間（パーセンタイル）] に設定します。期間グラフには、50、90、95、99 パーセンタイルが表示されます。
レスポンス ステータスを時間関数として表示するには、[グラフビュー] メニューを [スパン率] に設定します。グラフには、プロジェクトに送信されるスパンのレートが表示されます。
外れ値を検出するには、[スパン] タブを選択し、テーブルを期間で並べ替えます。
特定のスパンの詳細情報を表示するには、そのスパンを選択します。トレースのコンテキストでスパンを表示するフライアウトが開きます。その後、スパンとトレースを調べます。
各サービスで生成されたスパンの数と統計情報を確認するには、[グループ化] タブを選択します。
- 各行は、特定のサービスとスパン名に対応しています。
- 行は期間ヘッダーで並べ替えることができます。
特定のグループ化の詳細を表示するには、行の Span 名を選択します。トレースのコンテキストでスパンを表示するフライアウトが開きます。その後、スパンとトレースを探索できます。
表示されるスパンを制限するには、フィルタを追加します。トレースデータのフィルタリングの詳細については、次のセクションをご覧ください。
トレースデータをフィルタする
関心のある情報のみを表示するには、フィルタを適用します。フィルタは、表示されるデータを制限します。たとえば、サービス名とステータスでフィルタできます。また、アプリケーションを App Hub にデプロイしている場合は、アプリケーションのトレースデータのみ、またはアプリケーションの一部である特定のサービスやワークロードのトレースデータのみを表示することが必要になることがあります。
フィルタを追加または削除すると、[Trace エクスプローラ] ページに表示されるデータが更新され、適用されたすべてのフィルタに一致するスパンのみが表示されます。
ID でトレースをフィルタする
インシデントや障害のトラブルシューティングを行うときに、トレース ID がわかっている場合があります。そのトレースを調べるには、ツールバーに移動して ページビュー トレースを検索 をクリックし、トレース ID を入力します。
有効な ID を入力すると、[詳細] フライアウトが開き、トレースとそのスパンに関する情報が表示されます。このペインのオプションを使用して、トレースを調べることができます。たとえば、スパンをキーワードで検索できます。
スパン フィルタを適用する
[スパンフィルタ] ペインには、最も一般的なフィルタが一覧表示されます。任意のサブカテゴリから複数のエントリを選択できます。フィルタを追加または削除すると、[フィルタ] バーも更新されます。
すべてのメニューの値は、トレースデータから取得されます。メニューにテキストのないオプションが含まれている場合、そのオプションは対応する属性を含まないスパンを指します。
通常、次のスパンフィルタを使用できます。
- OpenTelemetry サービス:
service.name属性でフィルタします。 - スパン名: スパンの名前。
- スパンのステータス: リクエストのステータス。値については、OpenTelemetry SpanStatus のドキュメントをご覧ください。
- 期間: スパンの期間。
- スパンの種類: スパン間の関係を表します。値については、OpenTelemetry SpanKind ドキュメントをご覧ください。
- App Hub アプリケーション:
gcp.apphub.application.idリソース属性でフィルタします。 - App Hub サービス:
gcp.apphub.service.idリソース属性でフィルタします。 - App Hub ワークロード:
gcp.apphub.workload.idリソース属性でフィルタします。
[スパンフィルタ] ペインに表示されていない属性でフィルタする場合は、[フィルタ] バーを使用します。
フィルタバーを使用する
[フィルタ] バーでは、事前定義されたフィルタキーと選択した値を使用してフィルタを適用できます。また、キーと値の両方を入力することもできます。
フィルタを追加するには、[フィルタを追加] を選択して、次のいずれかの操作を行います。
- 定義済みのキー（[スパン名] など）を選択し、セカンダリ メニューから値を選択します。
[属性フィルタを追加] を選択し、カスタムキーと値を追加します。独自のフィルタキーを入力する場合は、スパンの属性のキーと同じ構文を使用します。
たとえば、ホスト ID でフィルタするには、キーを
host.idに設定します。同様に、ステータス コードでフィルタするには、キーを/http/status_codeに設定します。このシナリオでは、値を200に設定して、フィルタ/http/status_code: 200を作成できます。フィルタで任意の値と一致させるには、[任意値] を選択します。
アプリケーションでフィルタする
アプリケーションに追加した計測によって生成されたトレーススパンには、次のリソース属性が含まれる可能性があります。
gcp.apphub.application.{container,id,location}gcp.apphub.{workload,service}.{criticality_type,environment_type,id}
[Trace エクスプローラ] ページには、App Hub に登録されているアプリケーション、サービス、ワークロードがメニューに表示される次のスパンフィルタがあります。
- App Hub アプリケーション:
gcp.apphub.application.idリソース属性でフィルタします。 - App Hub サービス:
gcp.apphub.service.idリソース属性でフィルタします。 - App Hub ワークロード:
gcp.apphub.workload.idリソース属性でフィルタします。
トレース スパンにアプリケーション固有の属性を含めるようにアプリケーションを計測する方法については、アプリケーション モニタリング用に計測するをご覧ください。
トレースを調査する
このセクションでは、トレースのコンテキストでスパンを調べる方法について説明します。
[Trace エクスプローラ] ページを開いて構成します。これらの手順については、集計されたトレースデータを表示するをご覧ください。
スパンまたはトレースの詳細を表示するには、次のいずれかを行います。
[Trace エクスプローラ] ページの表セクションに移動し、表形式のセクションからエントリを選択します。表の行は、任意の表の見出しで並べ替えることができます。フィルタを適用して、テーブルに表示するスパンを制限できます。
[Trace エクスプローラ] ページのツールバーに移動し、pageview [トレースを検索] をクリックして、トレース ID を入力します。
[詳細] フライアウトが開き、トレースとそのスパンが表示されます。選択したスパンまたはトレースの詳細が表示されます。
- [名前] 列に呼び出し階層が表示され、最初のエントリにはトレース ID が含まれます。この列には、生成 AI イベントまたはログデータが利用可能かどうかを示すアノテーションが含まれることもあります。
- サービス列は、OpenTelemetry 属性
service.nameが設定されている場合に、その属性から抽出されます。この属性が設定されておらず、サービスが App Engine で実行されている場合は、App Engine サービス名が表示されます。それ以外の場合は、サービスは指定されません。 - レイテンシ バーの長さは、レイテンシ値を表します。
- レイテンシバーの色はステータスを示します。青色のレイテンシバーは正常に完了したことを示し、赤色のレイテンシバーはエラーが発生したことを示します。
- レイテンシ バーの円は、ログエントリまたはイベントがスパンに関連付けられていることを示します。この動作を変更するには、[ログとイベント] メニューを使用します。
トレースを調べる手順は次のとおりです。
ポインタを使用して、さまざまなスパンを選択します。スパンを選択すると、ページ上のタブが更新され、スパンの属性、ログエントリ、イベントが表示されます。
トレース内のスパンでキーワードを検索するには、[トレースで検索] フィールドを使用します。
検索は、スパン名、サービス名、属性フィールドにのみ適用されます。検索できるのはプレーン テキストのみで、ログ、イベント、メタデータは検索できません。
たとえば、
GETと入力すると、大文字と小文字を区別せずにGETを含むスパン名、サービス名、または [属性] ペインのテキストがハイライト表示されます。
属性、ログエントリ、イベントを表示する
スパンの [詳細] フライアウトには、次の各タブが含まれています。
属性: このタブには、スパンに添付されているラベルが一覧表示されます。ラベルの詳細については、トレースラベルをご覧ください。
ログとイベント: このタブには、選択したスパンと
trace_idフィールドとspan_idフィールドが一致するイベントとログエントリが表示されます。表示する権限のあるログエントリのみが表示されます。このタブのエントリの詳細を表示するには、keyboard_arrow_down [さらに表示] をクリックします。
ログ エクスプローラのページでログデータを表示する場合は、[ログを表示] をクリックします。クエリは、特定のトレース、スパン、時間範囲でフィルタするように設定されています。
スタック トレース: 使用可能なスタック トレースを一覧表示します。
メタデータとリンク: スパンに関する一般的な情報が一覧表示されます。
[詳細] には、[入力/出力] というラベルのタブが含まれる場合もあります。このタブには、生成 AI イベントが表示されます。
生成 AI イベントを表示する
生成 AI エージェントに関連するイベントを表示するには、[Inputs/Outputs] タブを使用します。このタブには、OpenTelemetry GenAI セマンティック規則に準拠するイベントが表示されます。
サポートされている構成は次の 2 つです。
スパンに属性として付加されるテキストベースのプロンプトとレスポンス。属性は、特性やイベントを記述する Key-Value ペアです。たとえば、キー
gen_ai.systemの値は、生成 AI 機能を提供するシステムを識別します。生成 AI 属性のキーはgen_aiで始まります。Cloud Storage バケットに保存されているマルチモーダル プロンプトとレスポンス。Cloud Trace は、トレースデータとログデータを関連付けてこれらのイベントを特定します。サポートされている構成については、マルチモーダル プロンプトとレスポンスを収集して表示するをご覧ください。
次のスクリーンショットは、[Trace エクスプローラ] ページで、スパンに添付されたテキストベースの生成 AI イベントがどのようにレンダリングされるかを示しています。
前のスクリーンショットを生成したサンプル アプリケーションについては、OpenTelemetry を使用して LangGraph ReAct エージェントを計測するをご覧ください。