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

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

次のスクリーンショットは、トレースデータの表示方法を示しています。

トレースデータの表示例。

スパンの集計分析を実行するクエリを実行するには、[Observability Analytics] ページまたは BigQuery を使用します。どちらのインターフェースも、SQL を使用したスパンデータのクエリをサポートしています。[Observability Analytics] ページを使用すると、クエリ結果を表またはグラフとして表示できます。SQL を使用してトレースデータをクエリする方法については、 トレースをクエリして分析するをご覧ください。

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

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

トレースデータの傾向とパターンを特定できるように、レイテンシ データが集計されてグラフに表示されます。ヒートマップでは、セルのスパンの数が色で表されます。スパンの多いセルは、スパンの少ないセルよりも色が濃くなります。各セルのツールチップには、レイテンシなどの情報が表示されます。 レイテンシのパーセンタイルとスパン率の情報も表示できます。

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

  • 表示されるスパンを制限するには、フィルタを適用します。たとえば、サービス、アプリケーション、エラー状態などのプロパティでフィルタできます。

  • 特定のトレースを表示するには、ツールバーの [ トレースを検索] オプションを使用します。

外れ値を特定して個々のスパンの詳細を表示するには、表形式のセクションを使用します。

  • [スパン] タブと [グループ化] タブの行は、期間の見出しで並べ替えることができます。

  • さまざまなサービスで生成されるスパンの数を確認するには、[グループ化] タブを使用します。各行はサービス名とスパン名に対応し、エントリごとにレイテンシの統計情報が表示されます。

スパンまたはグループの詳細を調べるには、表形式のセクションの行からエントリを選択します。フライアウトが開き、トレースのコンテキストでスパンが表示されます。このビューから、スパンとその属性を調べたり、イベントとログデータを表示したりできます。トレース内のスパンと属性をキーワードで検索することもできます 。

[Trace エクスプローラ] ページに表示されるトレースデータは、次の要素によって異なります。

  • [スコープ] 設定。トレースデータの検索対象となるビューを決定します。ページが開くと、[スコープ] 要素がデフォルトの トレース スコープに設定され、システムは そのスコープにリストされているビューに対してトレースデータをクエリします。

    新しいプロジェクトでは、デフォルトのトレース スコープにプロジェクトの _AllSpans が一覧表示されます。このビューでは、プロジェクトに保存されているすべてのトレースデータへの読み取りアクセスが提供されます。

  • 検索対象のビューに対する Identity and Access Management（IAM）権限。 プロジェクトのトレースデータを表示する権限がない場合、 コンソールに警告メッセージが表示され、その プロジェクトのデータは表示されません。 Google Cloud

  • 期間の設定。

  • 適用するフィルタ。

このページの残りの部分では、トレースデータを検索して調査する方法について説明します。

始める前に

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

この事前定義ロールには、コンソールを使用してトレースデータを表示するために必要な権限が含まれています。 Google Cloud 必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

コンソールを使用してトレースデータを表示するために必要な権限は次のとおりです。 Google Cloud

  • トレース スコープを選択する: cloudtrace.traceScopes.[get, list]
  • デフォルトのトレース スコープを読み取る: observability.scopes.get

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

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

集計されたトレースデータを表示する

トレースデータの集計情報を表示する手順は次のとおりです。

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

    [Trace エクスプローラ] に移動

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

    最初のトレースデータが プロジェクトに書き込まれてから、そのデータを表示できるようになるまで数分かかることがあります。 Google Cloud 数分待ってもトレースデータが表示されない場合は、プロジェクトに表示するデータがないか、構成に問題がある可能性があります。この問題を解決する方法については、 トラブルシューティング: Trace インターフェースにデータが表示されないをご覧ください。

  2. [Trace エクスプローラ] ページを構成します。

    1. コンソールのツールバーで、プロジェクトを選択します。 Google Cloud Google Cloud App Hub の構成には、App Hub ホスト プロジェクトまたは管理プロジェクトを選択します。

    2. 省略可: [スコープ] 要素を使用して、トレースデータの検索対象となるビューを構成します。

      • プロジェクトに保存されているトレースデータを表示するには、[スコープ] 要素の最初のメニューを [プロジェクト] または [_Default] に設定します。どちらの設定でも結果は同じです。

      • 複数のプロジェクトに保存されているトレースデータを表示するには、[スコープ] 要素の最初のメニューを開き、[トレース スコープ] を選択して、それらのプロジェクトの _AllSpans ビューを一覧表示するトレース スコープを選択します。選択すると、[スコープ] メニューに トレース スコープ アイコン（）と、 選択したトレース スコープの名前が表示されます。

      システムに表示されるデータは、検索対象のビューに対する IAM ロールによって異なります。たとえば、ビュー内のデータを表示するために必要な権限がない場合、そのデータは表示されません。

      詳細については、 トレース スコープの作成と管理をご覧ください。

    3. 省略可: 期間セレクタを使用するか、ポインタを使用して x 軸の範囲をハイライト表示して、期間を更新します。

      たとえば、レイテンシ データに傾向があるかどうかを確認する場合は、このセレクタを [過去 2 週間] に設定します。 スパンデータは 30 日間保存されます。

  3. ヒートマップを調べます。

    • 色を使用して、傾向と外れ値を特定します。スパンの多いセルは、スパンの少ないセルよりも色が 濃くなります。

    • セルのツールチップを使用して、セルの詳細を表示します。ツールチップには、 スパンの数、日付と時刻、セルの時間間隔が表示されます。

  4. レイテンシのパーセンタイルとエラー率を調べます。

    • レイテンシの傾向を表示するには、[グラフビュー] メニューを [スパンの期間（パーセンタイル）] に設定します。 期間グラフには、50、90、95、99 パーセンタイルが表示されます。

    • レスポンス ステータスを時間の関数として表示するには、[グラフビュー] メニューを [スパン率] に設定します。グラフには、プロジェクトに送信されるスパンの割合が表示されます。

  5. [スパン] テーブルと [グループ化] テーブルを使用して、外れ値を特定したり、統計情報を表示したりします。[スパン] テーブルには、個々のスパンが一覧表示されます。[グループ化] テーブルでは、スパンが名前とサービス名またはワークロード名でグループ化されます。

    • 外れ値を表示したり、スパン名を検索したりするには、テーブルを並べ替えます。任意の列見出しで並べ替えることができます。

      たとえば、[スパン] テーブルを期間で並べ替えると、レイテンシの高いスパンを見つけることができます。

    • 平均レイテンシなどの統計情報を表示するには、[グループ化] テーブルを使用します。

    • App Hub に登録されているサービスとワークロードを検索するには、 [サービス/ワークロード] 列で、 サービス アイコン（）または ワークロード アイコン（）を含むエントリを検索します。 App Hub に登録されているサービスまたはワークロードに提供されているリンクをクリックすると、対応する Application Monitoring ダッシュボードが開きます。

    特定のグループの詳細を表示するには、行のスパン名を選択します。フライアウトが開き、トレースのコンテキストでスパンが表示されます。スパンとトレースを調べることができます。

  6. 表示されるスパンを制限するには、フィルタを追加します。 トレースデータのフィルタリングの詳細については、次のセクションをご覧ください。

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

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

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

ID でトレースをフィルタする

インシデントや障害のトラブルシューティングを行う際に、トレース ID がわかっている場合があります。そのトレースを調べるには、ツールバーに移動して、 [] [Search for trace]をクリックし、 トレース 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 が生成されます。 フィルタが任意の値と一致するようにするには、[任意の値] を選択します。

アプリケーションでフィルタする

App Hub に登録されているサービスと ワークロードで生成されたスパンを検索または表示するには、スパンに次のリソース属性が含まれている必要があります。

  • gcp.apphub.application.{container,id,location}
  • gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

上記のリソース属性は、 アプリケーションに追加したインストゥルメンテーションによって生成されます。 トレースデータは、任意のリソース属性でフィルタできます。 ただし、次のスパンフィルタ は、アプリケーション、サービス、ワークロード ID でフィルタします。

  • App Hub アプリケーション
  • App Hub サービス
  • App Hub ワークロード

App Hub に登録されているサービスとワークロードの Application Monitoring ダッシュボードを開く手順は次のとおりです。

  1. [スパン] テーブルまたは [グループ化] テーブルに移動して、サービスまたはワークロードを見つけます。サービス アイコン（）またはワークロード アイコン（）を探すか、テーブルをフィルタします。

  2. [サービス/ワークロード] 列のリンクを選択します。

トレースを調査する

このセクションでは、トレースのコンテキストでスパンを調べる方法について説明します。

  1. [Trace エクスプローラ] ページを開いて構成します。手順については、集計されたトレースデータを表示するをご覧ください。

  2. スパンまたはトレースの詳細を表示するには、次のいずれかの操作を行います。

    • [Trace エクスプローラ] ページのテーブル セクションに移動し、表形式のセクションからエントリを選択します。テーブルの行は、任意のテーブルの見出しで並べ替えることができます。フィルタを適用して、テーブルに表示されるスパンを 制限できます。

    • [**Trace エクスプローラ**] ページのツールバーに移動し、 [ **トレースを検索**] をクリックして、トレース ID を入力します。

    [詳細] フライアウトが開き、トレースとそのスパンが表示されます。

    トレース フライアウトの例。

    選択したスパンまたはトレースの詳細が表示されます。

    • [名前] 列には呼び出し階層が表示され、最初のエントリにはトレース ID が含まれます。この列には、生成 AI イベントまたはログデータが利用可能かどうかを示すアノテーションが含まれる場合もあります。
    • [サービス/ワークロード] 列には、サービス名またはワークロード名が表示されます。 OpenTelemetry 属性 service.name が設定されると、サービス名はその属性から抽出されます。 この属性が設定されておらず、サービスが App Engine で実行されている場合は、App Engine サービス名が表示されます。それ以外の場合は、サービスは指定されません。
    • レイテンシバーの長さは、レイテンシ値を表します。
    • レイテンシバーの色はステータスを示します。青色のレイテンシバーは正常に完了したことを示し、赤色のレイテンシバーはエラーが発生したことを示します。
    • レイテンシバーの円は、ログエントリまたはイベントがスパンに関連付けられていることを示します。この動作を変更するには、[ログとイベント] メニューを使用します。

  3. トレースを調べる手順は次のとおりです。

    • ポインタを使用して、別のスパンを選択します。スパンを選択すると、 ページ上のタブが更新され、スパンの 属性、ログエントリ、イベントが表示されます。

    • トレース内のスパンをキーワードで検索するには、[Trace で検索] フィールドを使用します。

      検索は、スパン名、サービス名またはワークロード名、属性フィールドにのみ適用されます。 検索できるのはプレーン テキストのみで、ログ、イベント、メタデータを検索することはできません。

      たとえば、GET と入力すると、[**名前**]、 [**サービス/ワークロード**]、[**属性**] ペインに表示される GET（ 大文字と小文字は区別されません）がハイライト表示されます。

属性、ログエントリ、イベントを表示する

スパンの [詳細] フライアウトには、次のタブがあります。

  • 属性: このタブには、スパンに添付されているラベルが一覧表示されます。 ラベルの詳細については、トレースラベルをご覧ください。

  • ログとイベント: このタブには、trace_id フィールドと span_id フィールドが選択したスパンと一致するイベントとログエントリが表示されます。表示されるのは、表示権限のあるログエントリのみです。

    このタブのエントリを調べるには、 [ 詳細を表示] をクリックします。

    ログデータをログ エクスプローラ ページで表示する場合は、[ログを表示] をクリックします。クエリは、特定のトレース、スパン、期間でフィルタするように設定されています。

  • スタック トレース: 使用可能なスタック トレースを一覧表示します。

  • メタデータとリンク : スパンに関する一般的な情報を一覧表示します。

    • スパン ID: スパン ID は 0 以外の 64 ビット整数です。詳細については、 TraceSpan をご覧ください。
    • 親スパン ID。
    • プロジェクト ID。
    • 開始時間と終了時間。

    • 他のスパンへのリンクを一覧表示するテーブル。このテーブルには、リンクごとに次の情報が表示されます。

      • リンク先のスパンの Key-Value ペア。
      • リンク先のスパンのトレース ID。このフィールドに [**現在のトレース**]が表示されている場合、スパンは 同じトレース内の別のスパンにリンクしています。

      リンクの詳細については、 Links API リファレンス ページをご覧ください。

[詳細] には、[Inputs/Outputs] タブというラベルのタブが含まれる場合もあります。このタブには、生成 AI イベントが表示されます。

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

生成 AI エージェントに関連するイベントを表示するには、[Inputs/Outputs] タブを使用します。このタブには、 OpenTelemetry GenAI のセマンティック規約に準拠したイベントが表示されます。

サポートされている構成は次の 2 つです。

  • テキストベースのプロンプトとレスポンス。スパンに 属性として添付されます。属性は、特性やイベントを表す Key-Value ペアです。たとえば、キー gen_ai.system の値は、生成 AI 機能を提供するシステムを識別します。生成 AI 属性のキーは gen_ai で始まります。

  • Cloud Storage バケットに保存されているマルチモーダル プロンプトとレスポンス。Cloud Trace は、トレースデータとログデータを関連付けることで、これらのイベントを識別します。サポートされている 構成については、 マルチモーダル プロンプトとレスポンスを収集して表示するをご覧ください。

次のスクリーンショットは、スパンに添付されたテキストベースの生成 AI イベントが [Trace エクスプローラ] ページに表示される様子を示しています。

トレーススパンの表示。

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

リモート MCP サーバーへの呼び出しを表示する

MCP サーバーによって書き込まれたスパンを表示するには、スパン名でトレースデータをフィルタします。たとえば、一部のリモート Google Cloud MCP サーバーは、tools/call オペレーションを受信すると、トレーススパンを生成できます。これらのスパンには、次の命名規則が適用されます。

tools/call NAME

上記の式で、NAME は呼び出されたエンドポイントを表します。 たとえば、list_keys のようなものが考えられます。この命名 規則は、MCP の OpenTelemetry セマンティック規約で定義されています。

これらのスパンを見つけるには、フィルタバーを使用し、 属性フィルタを追加しますmcp.method.name。フィルタの値を tools/call に設定します。次のスクリーンショットは、tools/call オペレーションから生成されたスパンを表示する [Trace エクスプローラ] ページを示しています。

トレースと関連するスパンが表示されている詳細ウィンドウ。

トレース生成をサポートするリモート Google Cloud MCP サーバーと、これらのサーバーにスパンを生成するように指示するアプリケーションの構成方法については、Trace を使用して MCP 呼び出しを調査するをご覧ください。

次のステップ