トレースとスパンにアクセスする

このドキュメントでは、Gemini Enterprise アプリによって生成されたトレースとスパンにアクセスして表示する方法について説明します。トレースとスパンは、アシスタントやエージェントの使用時など、アプリケーション内のリクエストのパフォーマンスと実行フローに関する詳細な分析情報を提供します。

トレースデータは、Trace エクスプローラを使用するか、エージェントの [トレース] タブを使用して個々のエージェント内で直接表示できます。

主なコンセプト

このセクションでは、Gemini Enterprise のオブザーバビリティに関連する主なコンセプトについて説明します。

コンセプト	説明
トレース	トレースは、さまざまなサービスとコンポーネントを通過する単一のリクエストまたはトランザクションを表すスパンのコレクションです。 たとえば、トレースはリクエストのライフサイクル全体を表します。これには、ユーザーが Gemini Enterprise アシスタントに質問する、Gemini Enterprise アシスタントが回答する、回答によってトリガーされる後続のアクション（メールの送信など）が含まれます。
スパン	スパンは、トレース内の単一のタイムド単位の作業です。関数呼び出し、API リクエスト、データベース クエリなどの特定のオペレーションを表します。各スパンには、開始時刻と終了時刻、一意の ID、他のスパンとの関係などの詳細が含まれます。これらの関係をまとめてトレースと呼びます。
スパンログ	スパンログは、特定のスパンに関連付けられたタイムスタンプ付きのフリーフォーム メッセージまたはイベントです。スパンの実行に関する詳細なコンテキスト情報が提供されるため、ユーザーは問題をデバッグし、リクエストのフローを把握できます。

始める前に

以下のものが揃っていることを確認してください。

• Gemini Enterprise 管理者ロールまたは Google Cloud コンソールの Gemini Enterprise ユーザーロール。

• 既存の Gemini Enterprise ウェブアプリ。新しいアプリの作成については、アプリを作成するをご覧ください。

• トレースにアクセスするには、Cloud Trace ユーザーロール（roles/cloudtrace.user）が必要です。

• [OpenTelemetry のトレースとログの計測を有効にする] オブザーバビリティ設定を有効にします。エージェントの種類に応じて、アプリレベルの構成（Core Assistant エージェントの場合）またはエージェントの [構成] タブ（Agent Designer の従業員作成エージェントと Deep Research エージェントの場合）で有効にします。詳細については、オブザーバビリティ設定を管理するをご覧ください。

データの保持

Gemini Enterprise app によって生成されたトレースとスパンは、 Google Cloud プロジェクトの Cloud Trace に保存され、その保持は Cloud Trace に則って管理されます。デフォルトでは、Cloud Trace はスパンデータを 30 日間保持します。保持期間を超えたデータは自動的に削除されます。信頼できる最新の保持値については、Cloud Trace の割り当てと上限のドキュメントの Cloud Trace の保持期間をご覧ください。

Trace エクスプローラでトレースにアクセスする

トレース エクスプローラを使用してトレースとスパンにアクセスする手順は次のとおりです。

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

   Trace エクスプローラに移動

2. Gemini Enterprise app が作成された Google Cloud プロジェクトを選択します。プロジェクトのすべてのスパンが表示されます。

3. テーブルで [スパン ID] をクリックして、スパンの所要時間やその他の属性などのトレースの詳細を表示します。

   注: Trace エクスプローラの使用方法の詳細については、トレースを検索して調査するをご覧ください。

   

エージェントのトレースにアクセスする

エージェントの [トレース] タブで、個々のエージェントのトレース スパンを直接表示することもできます。このタブには、スパン トレース レコードと親子実行構造の詳細な時系列の概要が表示されます。

注: [トレース] タブは、コア アシスタント エージェント、エージェント デザイナーの従業員作成エージェント、ディープ リサーチ エージェントで使用できます。

エージェントのトレースにアクセスするには:

1. Google Cloud コンソールでアプリに移動し、[エージェント] をクリックします。
2. 検査するエージェントを選択し、[トレース] タブをクリックします。

トレースの概要テーブル

[トレース] タブのメインテーブルには、各トレース スパンに関する次の情報が表示されます。

• ステータス: トレースの現在のステータス（現在は [未設定] と表示されます）。
• トレース スパン ID: トレース スパンの固有識別子。スパン ID のリンクをクリックして、詳細をドリルダウンします。
• スパン名: スパンが実行している作業の簡単な説明。
• スパンタイプ: スパンのタイプ。次のオプションがあります。
  • Agent to Tool: エージェントから外部ツールへの呼び出し。
  • Invoke Agent: エージェントの呼び出し。
  • Agent to Model: エージェントから大規模言語モデルへのリクエスト。
• Duration: トレース スパンの完了にかかった時間（分単位）。
• 入力: スパンに送信された入力データまたはメッセージ（ある場合）。
• 出力: スパンから返された出力結果（存在する場合）。
• 開始時刻: スパンの実行が開始された正確なタイムスタンプ。

詳細なトレースビュー

トレース スパン ID をクリックすると、次の詳細ページが開きます。

1. 概要: 開始時間、期間、合計スパン数などのベースライン メタデータを表示します。[Cloud Trace で表示] をクリックするか、[グラフ] ビューと [タイムライン] ビューのボタンを切り替えることができます。
2. 可視化: すべてのトレース スパンの親子関係を示すグラフ階層またはタイムライン ビューを切り替えます。
3. 選択したスパンの詳細: 単一のスパンを選択して、詳細セクションを表示します。このセクションには次のものが含まれます。
   • 概要: スパンの名前、ターゲット サービス、このアクションを含むスパンの合計数、合計時間（秒単位）が表示されます。
   • ログ: 構成されている場合は、関連するイベントの詳細を表示します。[ログを表示] をクリックして、標準ログに直接移動します。
   • 評価: 構成されている場合は、評価結果が表示されます。
   • 入出力: リクエストとレスポンスのペイロード全体。
   • ログとイベント: このスパンの実行中に発生したイベントのリスト。
   • スタック トレース: スパンの実行が失敗した場合のエラーの詳細。
   • メタデータとリンク: 関連するクラウド エクスプローラ エンティティを参照するリンク。
   • 属性: リソースタグと追加の Key-Value 可観測性パラメータ。