このページは Cloud Translation API によって翻訳されました。

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

トレースデータの集計表現を表示したり、特定のラベルを含む個々のトレースやトレースを検索して調査したりするには、[Trace エクスプローラ] ページを使用します。

この機能は Google Cloud プロジェクトでのみサポートされています。App Hub 構成の場合は、App Hub ホストプロジェクトまたは管理プロジェクトを選択します。

[Trace エクスプローラ] ページについて

トレースデータの傾向とパターンを特定できるように、レイテンシデータが集計され、グラフに表示されます。ヒートマップ（デフォルトの可視化）では、色を使用してセルのスパンの数を表します。スパンが多いセルは、スパンが少ないセルよりも濃い色で表示されます。セルを選択するか、セルのツールチップを有効にすると、詳細情報を確認できます。他の可視化では、レイテンシをパーセンタイルとして表示し、スパン率情報を確認できます。すべてのビジュアリゼーションで、ポインタを使用して X 軸を拡大できます。折れ線グラフでは、X 軸と Y 軸を拡大できます。

問題を調査する際に、特定のトレースや特定のプロパティを持つスパンのみを表示することがあります。

トレースの ID がわかっている場合は、ツールバーで トレースを検索 をクリックし、ダイアログにトレース ID を入力します。次に、トレース内のスパンと属性をキーワードで検索できます。
集計データを表示するときに、フィルタを適用して特定のスパンを検索できます。たとえば、特定のサービスのスパンのみを表示するようにデータをフィルタできます。次に、エラーを報告する特定のサービスの範囲に表示を制限する 2 つ目のフィルタを追加します。

表形式のデータを使用すると、個々のスパンの詳細を表示して、外れ値を特定できます。たとえば、レイテンシ値が最も高いスパンを見つけるには、[スパン] タブを選択し、レイテンシでデータを並べ替えます。エラーを生成しているサービスを見つけるには、スパンステータスでデータをフィルタし、[グループ化] タブを選択します。このタブには、スパンとサービス名で集計されたデータが表示されます。テーブルの各行には、詳細情報へのリンクが含まれています。

[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 エクスプローラ] ページに移動します。
[Trace エクスプローラ] に移動

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

最初のトレースデータが Google Cloud プロジェクトに書き込まれてから、そのデータを表示できるようになるまでに数分かかることがあります。数分待ってもトレースデータが表示されない場合は、プロジェクトに表示するデータがないか、構成に問題がある可能性があります。これらの問題を解決する方法については、トラブルシューティング: トレースインターフェースにデータがないをご覧ください。
Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホストプロジェクトまたは管理プロジェクトを選択します。
省略可: Scope 要素を使用して、トレースデータが検索されるプロジェクトを構成します。
- プロジェクトに保存されているトレースデータを表示するには、[Scope] 要素の最初のメニューを [Project] または [_Default] に設定します。この 2 つの設定は同等です。
- 複数のプロジェクトに保存されているトレースデータを表示するには、[スコープ] 要素の最初のメニューを開き、[トレーススコープ] を選択して、これらのプロジェクトが一覧表示されているトレーススコープを選択します。選択すると、[スコープ] メニューにトレーススコープアイコンと、選択したトレーススコープの名前が表示されます。
返されるデータは、検索対象のプロジェクトに対する IAM ロールによって異なります。たとえば、検索されたプロジェクトにアクセス権のない Google Cloud プロジェクトが含まれている場合、そのプロジェクトのトレースデータは返されません。

詳細については、トレーススコープの作成と管理をご覧ください。
省略可: 期間セレクタを使用するか、ポインタを使用して x 軸の範囲をハイライト表示して、期間を更新します。

たとえば、レイテンシデータに傾向があるかどうかを確認する場合は、このセレクタを [過去 2 週間] に設定します。
ツールバーに移動し、期間セレクタを 2 週間以上に設定します。スパンデータは 30 日間保存されます。
トレースデータのパターンと傾向を示すグラフを確認します。
- スパンレイテンシデータに関する情報を取得するには、[グラフビュー] メニューを [スパン期間（ヒートマップ）] に設定します。色の強度はスパンの数に比例します。セルに関する情報を表示するには、ポインタを使用します。ツールチップには、スパンの数、日時、セルの時間間隔が表示されます。
  
  注: ヒートマップでセルを選択すると、個々のスパンまたはスパンのグループを一覧表示するテーブルが更新されます。
- レイテンシの傾向を表示するには、[グラフビュー] メニューを [スパン期間（パーセンタイル）] に設定します。期間グラフには、50 パーセンタイル、90 パーセンタイル、95 パーセンタイル、99 パーセンタイルが表示されます。
- レスポンスステータスを時間の関数として表示するには、[グラフビュー] メニューを [スパン率] に設定します。グラフには、プロジェクトに送信されるスパンのレートが表示されます。
[スパン] タブに個々のスパンが一覧表示され、[グループ化] タブにサービスと名前でグループ化されたスパンが表示される表形式のデータを調べます。

テーブルの各行には、スパンまたはグループ化と、詳細情報へのリンク、いくつかの指標が表示されます。たとえば、[グループ化] タブの指標には、エラー率とグループ内のスパンの数が含まれます。

外れ値を検出するには、列見出しを選択してテーブルを並べ替えます。
フィルタを追加して、表示されるスパンを制限します。トレースデータのフィルタリングの詳細については、次のセクションをご覧ください。

トレースデータをフィルタする

関心のある情報のみを表示するには、フィルタを適用します。フィルタは、表示されるデータを制限します。たとえば、サービス名とステータスでフィルタできます。また、アプリケーションを App Hub にデプロイしている場合は、アプリケーションのトレースデータのみ、またはアプリケーションの一部である特定のサービスやワークロードのトレースデータのみを表示することが必要になることがあります。

フィルタを追加または削除すると、[Trace エクスプローラ] ページに表示されるデータが更新され、適用されたすべてのフィルタに一致するスパンのみが表示されます。

フィルタの設定を変更するには、[スパンフィルタ] ペインまたは [フィルタ] バーを使用します。

スパンフィルタを適用する

[スパンフィルタ] ペインには、最も一般的なフィルタが一覧表示されます。任意のサブカテゴリから複数のエントリを選択できます。フィルタを追加または削除すると、[フィルタ] バーも更新されます。

すべてのメニューの値はトレースデータから取得されます。メニューにテキストのないオプションが含まれている場合、そのオプションは対応する属性を含まないスパンを指します。

通常、次のスパンフィルタを使用できます。

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 アプリケーションのフィルタを追加します。

アプリケーション ID（gcp.apphub.application.id）でフィルタするには、[App Hub アプリケーション] メニューを使用します。
アプリケーションのサービス（gcp.apphub.service.id）でフィルタするには、[App Hub サービス] メニューを使用します。
アプリケーションのワークロード（gcp.apphub.workload.id）でフィルタするには、[App Hub ワークロード] メニューを使用します。

トレーススパンにアプリケーション固有の属性が含まれるようにアプリケーションを計測する方法については、アプリケーションモニタリング用に計測するをご覧ください。

ID でトレースを検索する

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

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

このページは、検索バーを使用して見つけることもできます。
Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホストプロジェクトまたは管理プロジェクトを選択します。
ツールバーに移動し、[] [トレースを検索] をクリックして、トレース ID を入力します。

有効な ID を入力すると、[詳細] フライアウトが開き、トレースとそのスパンに関する情報が表示されます。このペインのオプションを使用して、トレースを調べることができます。たとえば、スパンをキーワードで検索できます。

注: 見つからないトレース ID を入力した場合、トレースデータが Trace エクスプローラ ページで検索されないプロジェクトに保存されているか、トレースデータを表示できる IAM ロールがない可能性があります。これらのエラーを解決するには、トレースデータを保存するプロジェクトを特定します。各プロジェクトで、IAM ロールでトレースデータを表示できることを確認し、Scope 要素がトレースデータを保存するすべてのプロジェクトを検索するように構成されていることを確認します。詳細については、トレースデータが検索されるプロジェクトのリストを更新するをご覧ください。

トレースを調査する

トレースまたはスパンを表示する手順は次のとおりです。

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

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

最初のトレースデータが Google Cloud プロジェクトに書き込まれてから、そのデータを表示できるようになるまでに数分かかることがあります。数分待ってもトレースデータが表示されない場合は、プロジェクトに表示するデータがないか、構成に問題がある可能性があります。これらの問題を解決する方法については、トラブルシューティング: トレースインターフェースにデータがないをご覧ください。
Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホストプロジェクトまたは管理プロジェクトを選択します。
次のいずれかを行います。
- [トレースエクスプローラ] ページのテーブルセクションに移動し、スパンを一覧表示するテーブル、またはサービスとスパン名でデータをグループ化した後に概要情報を一覧表示するテーブルからエントリを選択します。
- [Trace エクスプローラ] ページのツールバーに移動し、 [トレースを検索] をクリックして、トレース ID を入力します。
[詳細] フライアウトが開き、トレースとそのスパンが表示されます。
- [名前] 列に呼び出し階層が表示され、最初のエントリにはトレース ID が含まれます。
- サービス列は、OpenTelemetry 属性 service.name が設定されている場合に、その属性から抽出されます。この属性が設定されておらず、サービスが App Engine で実行されている場合は、App Engine サービス名が表示されます。それ以外の場合は、サービスは指定されません。
- レイテンシバーの長さは、レイテンシ値を表します。
- レイテンシバーの色はステータスを示します。青色のレイテンシバーは正常に完了したことを示し、赤色のレイテンシバーはエラーが発生したことを示します。
- レイテンシバーの円は、ログエントリまたはイベントがスパンに関連付けられていることを示します。この動作を変更するには、[ログとイベント] メニューを使用します。
省略可: [トレースで検索] フィールドを使用して、トレース内のスパン名、サービス名、属性を検索します。

たとえば、GET と入力すると、スパン名、サービス名、または [属性] ペインに GET が表示されているテキストが、大文字と小文字を区別せずにハイライト表示されます。

正規表現を使用して検索することはできません。また、ログ、イベント、メタデータを検索することもできません。
特定のスパンの詳細を表示するには、スパンを選択して、その属性とイベントを表示します。詳細については、次のセクションをご覧ください。

属性とイベントを表示する

このセクションでは、ラベル、ログ、イベントを表示する方法について説明します。

ラベルを表示する

スパンに適用されているラベルを表示するには、[属性] タブに移動します。ラベルの詳細については、トレースラベルをご覧ください。

ログとイベントを表示する

スパンに関連するログとイベントを表示するには、[ログとイベント] タブに移動します。

ログエントリを表示するには、 [さらに表示] をクリックします。

[ログを表示] ボタンを選択することもできます。このボタンをクリックすると、特定のトレース、スパン、時間範囲でフィルタするようにクエリが設定されたログエクスプローラページが開きます。このクエリはログエントリを返さない可能性があります。

生成 AI イベントを表示する

生成 AI エージェントに関連するイベントを表示するには、[GenAI] タブを使用します。このタブは、Trace に送信されたスパンが OpenTelemetry の生成 AI システムのセマンティック規則に準拠している場合に利用できます。これにより、名前が gen_ai で始まるメッセージが生成されます。

次のスクリーンショットは、[Trace エクスプローラ] ページで生成 AI イベントがレンダリングされる様子を示しています。

トレーススパンの表示。

前のスクリーンショットを生成したサンプルアプリケーションについては、OpenTelemetry を使用して LangGraph ReAct エージェントを計測するをご覧ください。

属性は、特性を記述する Key-Value ペアです。生成 AI システムの属性の例を次に示します。

gen_ai.system: 生成 AI 機能を提供するシステムを識別します。
gen_ai.request.model: リクエストが送信されるモデルを識別します。

通常、名前が「gen_ai」で始まるイベントは、生成 AI システムの個々の入力または出力を記述します。これらの入力と出力には、システムプロンプトとユーザープロンプト、ツールの入力と出力、モデルのレスポンスが含まれます。生成 AI システムからのイベントの例を次に示します。

gen_ai.system.message: 生成 AI モデルに送信されたシステムプロンプトを記録するイベント。システムプロンプトは、通常はエンドユーザーに表示されないモデルへの指示を提供し、ユーザーのプロンプトに対するモデルの解釈をガイドします。
gen_ai.user.message: モデルに送信されたユーザー指定のプロンプトを記録するイベント。
gen_ai.assistant.message: モデルの出力を記録するイベント。ツール呼び出しの記録が含まれる場合や、テキストレスポンスの出力が含まれる場合があります。メッセージには、アプリケーションで使用されない候補レスポンスが含まれている場合があります。
gen_ai.choice: アプリケーションで使用される候補出力をレポートするために使用されるイベント。

スタックトレースを表示する

スタックトレースを表示するには、[スタックトレース] タブを使用します。

一般情報やその他のメタデータを表示する

スパンに関する一般的な情報と、他のスパンへのリンクの表を確認するには、[メタデータとリンク] タブを表示します。詳細情報には次の情報が含まれます。

スパン ID: スパン ID は 0 以外の 64 ビット整数です。詳細については、TraceSpan をご覧ください。
親スパン ID
プロジェクト ID
開始時間と終了時間
他のスパンへのリンクを一覧表示するテーブル

Links というテーブルの各行に、現在のスパンと別のスパンの間のリンクが一覧表示されます。[属性] フィールドには、リンク先のスパンの Key-Value ペアが表示されます。[トレース] フィールドは、リンク先のスパンのトレースにリンクしています。このフィールドに現在のトレースが含まれている場合、リンク先のスパンは現在のスパンと同じトレースに含まれます。それ以外の場合、このフィールドにはトレース ID が含まれます。リンクの詳細については、Links API リファレンスページをご覧ください。

傾向を確認する

アプリケーションに更新をデプロイした後、更新が応答レイテンシに影響したかどうかを確認することが必要になる場合があります。アップグレード前後の両方のレイテンシデータが表示されるように期間選択ツールを設定すると、レイテンシデータの傾向を確認できます。

トレースデータの傾向を表示する手順は次のとおりです。

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

このページは、検索バーを使用して見つけることもできます。
Google Cloud コンソールのツールバーで、 Google Cloud プロジェクトを選択します。App Hub 構成の場合は、App Hub ホストプロジェクトまたは管理プロジェクトを選択します。
省略可: フィルタを追加して、表示されるスパンを構成します。
ツールバーに移動し、期間セレクタを 2 週間以上に設定します。スパンデータは 30 日間保存されます。
省略可: [グラフビュー] メニューの選択を変更します。