Agent Gateway を介したトラフィックをモニタリングする

このページでは、Agent Gateway デプロイを介してルーティングされたトラフィックのログの表示、リクエストのモニタリング、分散トレースの追跡を行う方法について説明します。

ロギング

Agent Gateway のログは、networkservices.googleapis.com/Gateway モニタリング対象リソースを使用して生成されます。

これらのログを使用して、ゲートウェイへのアクセス リクエストをモニタリングできます。これには、Agent Gateway がドライラン モードでデプロイされたときに作成されたログが含まれます。

特定のゲートウェイのログを表示する

特定のゲートウェイのログを表示するには、次の操作を行います。

コンソール クエリ

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

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

  2. [クエリを表示] をクリックします。

  3. または、クエリ フィールドに次の内容を貼り付けます。

    resource.type="networkservices.googleapis.com/Gateway"
resource.labels.location="REGION"
resource.labels.gateway_name="AGENT_GATEWAY_NAME"

    次のように置き換えます。

    • REGION: ゲートウェイのリージョン。
    • AGENT_GATEWAY_NAME: ゲートウェイの名前。

  4. [クエリを実行] をクリックします。

Agent Platform のログ名

ログ エクスプローラで特定のタイプのログエントリをクエリするには、logName フィールドを使用してログ名でクエリをフィルタします。次の表に、Agent Gateway とエージェント側のオペレーションによって生成される主なログ名を示します。

ログ名 説明
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests ゲートウェイの許可と拒否の決定に関するログ。
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access Identity-Aware Proxy（IAP）AuthorizeUser の決定の Cloud Audit Logs。
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr エージェント側の起動エラーと実行エラー（推論エンジン stderr）。
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout エージェント側の標準出力（推論エンジン stdout）。

PROJECT_ID は、実際の Google Cloud プロジェクト ID に置き換えます。

コンテンツのサニタイズに Model Armor を使用する場合、これらのログは個別に発行されます。Model Armor ログのクエリの手順については、ログ エクスプローラで未加工のコンテンツ セキュリティ ログを表示するをご覧ください。

ログの内容

Agent Gateway のログエントリには、ゲートウェイとの間のトラフィックのモニタリングとデバッグに役立つ情報が含まれています。

フィールド フィールドの形式 フィールドのタイプ: 必須または省略可 説明
severity
insertID
timestamp
receiveTimestamp
trace
traceSampled
logName		 LogEntry 必須 ログエントリで説明されている一般的なフィールド。
httpRequest HttpRequest 必須 HTTP リクエストをロギングするための共通プロトコル。
resource MonitoredResource 必須

MonitoredResource は、ログエントリに関連付けられているリソースタイプです。Agent Gateway のリソースタイプは networkservices.googleapis.com/Gateway です。
jsonPayload object（Struct 形式） 必須

JSON オブジェクトとして表されるログエントリ ペイロード。JSON オブジェクトには、次の Agent Gateway フィールドが含まれています。

  • agentGatewayInfo: Agent Gateway リクエストに関する情報が含まれます。

    • mcpInfo: リクエストの MCP メソッド（「tools/list」や「tools/call」など）と、メソッドに関連付けられた主要なパラメータ（存在する場合）に関する情報が含まれます。たとえば、「tools/call」メソッドの場合、パラメータはツール名です。
    • agentRegistryResource: リクエストと一致した MCP サーバー、エージェント、エンドポイントの Agent Registry リソース名。

  • serviceExtensionsInfo フィールドの詳細を調べて、リクエストを処理した認可拡張機能（IAP、Model Armor など）に関する情報を確認することもできます。

モニタリング

Agent Gateway は、一部の Service Extensions 指標を Cloud Monitoring にエクスポートします。認可を Service Extensions に委任する場合は、これらの指標を使用して、拡張機能との間のトラフィックをモニタリングできます。詳細については、Cloud Load Balancing のコールアウトのロギングとモニタリングをご覧ください。

オブザーバビリティ ダッシュボード

Agent Gateway には、ゲートウェイ経由でルーティングされたトラフィックのモニタリング、監査、デバッグを行うためのオブザーバビリティ ダッシュボードが用意されています。

  • スコアカード: 試行された認証の合計数、認証の失敗数、1 秒あたりのリクエスト数を追跡します。
  • グラフ: 承認失敗率（%）と 1 秒あたりのリクエスト数を時系列で可視化します。
  • Egress トラフィック ログ: 403 拒否、登録されていないエンドポイントへのトラフィック、トラフィック全体など、Egress クエリの詳細なログを確認します。

Google Cloud コンソールでゲートウェイのオブザーバビリティ ダッシュボードにアクセスする手順は次のとおりです。

  1. Google Cloud コンソールで、[エージェント ゲートウェイ] ページに移動します。

    Agent Gateway に移動

  2. モニタリングするゲートウェイの名前をクリックします。

  3. [オブザーバビリティ] タブをクリックします。

ダッシュボードのデータ要件

Agent Gateway オブザーバビリティ ダッシュボードは、オブザーバビリティ分析を使用してデータを表示します。ダッシュボードにデータが読み込まれない場合は、オブザーバビリティ分析を使用するように _Default ログバケットをアップグレードしてください。ダッシュボードは、_Default バケットの _AllLogs ビューからデータを取得します。

Cloud Trace を使用する

Agent Gateway は Cloud Trace と統合され、エージェント ワークロードのエンドツーエンドのリクエストのオブザーバビリティを提供します。Agent Gateway は AI エージェントの中心的な制御ポイントとして機能するため、トレースを有効にすると、エージェントからゲートウェイを介して複数の Google Cloud サービス、ツール、エージェント、MCP サーバーにリクエストがどのように伝播されるかを把握できます。Trace は、これらのサービス境界を越えてリクエスト フローを追跡することで、エージェント アーキテクチャの完全な分散トレースを提供します。

Trace を使用すると、次のことができます。

  • エージェントのインタラクションを正確にデバッグする: サービス境界を越えてリクエストの全行程を追跡し、レイテンシのボトルネックと失敗したバックエンド呼び出しを特定します。
  • アップストリームのサンプリング決定を尊重する: 親ベースのサンプリングを使用して、アップストリーム エージェントまたはクライアントがトレースを開始したときにエンドツーエンドのトレースの継続性を維持し、ルーチン トラフィックのベースライン サンプリング レートを上げることなく、優先度の高いリクエストを完全にキャプチャします。
  • オープン標準でオブザーバビリティを統合する: OpenTelemetry と W3C TraceContext 標準に基づいて構築されたトレースは、AI エージェント、Agent Gateway、ターゲット MCP サーバーまたはツール、サードパーティのモニタリング プラットフォーム間でコンテキストをシームレスに伝播します。
  • 根本原因分析を迅速化する: trace_id を使用してトレース スパンをゲートウェイ リクエスト ログと指標に直接関連付け、本番環境の問題を迅速にトラブルシューティングします。

Trace の詳細については、Cloud Trace の概要をご覧ください。

必要なロール

プロジェクトに次の Identity and Access Management（IAM）ロールが必要です。

  • トレース ポリシーを構成して更新する: Compute ネットワーク管理者（roles/compute.networkAdmin）または Compute 管理者（roles/compute.admin）
  • Google Cloud コンソールでトレースを表示する: Cloud Trace ユーザー（roles/cloudtrace.user）

また、Agent Gateway がトレース スパンを Trace に書き込めるようにするには、次のサービス アカウントに Cloud Trace エージェント ロール（roles/cloudtrace.agent）を付与する必要があります。

  • Compute Engine サービス エージェント: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Network Security サービス エージェント: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • Agent Gateway サービス エージェント: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • エージェントまたはクライアント ワークロードのサービス アカウント: 呼び出し元の AI エージェントまたはクライアント ワークロードがトレースを開始し、独自の親スパンを Trace にエクスポートする場合、ワークロードのサービス アカウントまたはエージェントに接続されたカスタム サービス アカウントにも、プロジェクトに対する roles/cloudtrace.agent ロールが付与されている必要があります。それ以外の場合、Agent Gateway の子スパンのみが書き込まれ、親スパンは Trace に表示されません。

PROJECT_NUMBER は、使用する Google Cloud プロジェクト番号に置き換えます。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

トレースを有効にする

Agent Gateway のトレースを有効にするには、オブザーバビリティ ポリシーの YAML ファイルを作成し、gcloud CLI を使用してインポートします。

  1. tracing-policy.yaml という名前の構成ファイルを作成します。

    name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME"
telemetryTarget:
  resources: # You can attach a policy to multiple gateways
  - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME"
displayName: "Tracing policy for Agent Gateway traffic"
tracingConfiguration:
  samplingRate: SAMPLING_RATE
  parentBasedSampling:
    enabled: ENABLE_PARENT_BASED_SAMPLING
    samplingRate: PARENT_BASED_SAMPLING_RATE

    次のように置き換えます。

    • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
    • REGION: ゲートウェイのリージョン（europe-west1 など）。
    • POLICY_NAME: オブザーバビリティ ポリシーの名前（my-agw-tracing-policy など）。
    • AGENT_GATEWAY_NAME: ゲートウェイの名前。
    • SAMPLING_RATE: トレースするリクエストの割合。0.0 から 1.0 までの値に設定します。トラフィックの多い本番環境では、オブザーバビリティと取り込み費用のバランスを取るために、1%（0.01）または 0.1%（0.001）のレートをおすすめします。
    • ENABLE_PARENT_BASED_SAMPLING: 上流の呼び出し元からの受信 traceparent ヘッダーのサンプリングされたビットを尊重するかどうかを制御します。true または false に設定します。
    • PARENT_BASED_SAMPLING_RATE: トレースする事前サンプリングされたリクエストの割合。0.0 から 1.0 までの値に設定します。たとえば、1.0 はサンプリング前のリクエストの 100% をトレースします。

  2. オブザーバビリティ ポリシーをインポートします。

    gcloud beta network-services telemetry-policies import POLICY_NAME \
   --source=tracing-policy.yaml \
   --location=REGION

トレースを表示

分散トレースを有効にして、ゲートウェイを介してトラフィックを送信すると、 Google Cloud コンソールでトレースの詳細を表示できます。

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

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

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

  2. [フィルタ] バーに、トレース フィルタ式（レイテンシしきい値、HTTP ステータス コード、リクエスト URI でフィルタする場合など）を入力するか、特定のトレース ID で検索します。

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

    Trace エクスプローラ

    Cloud Trace の Trace エクスプローラ ビュー
    Trace の Trace エクスプローラ ビュー

    トレース タイムライン ビュー

    Cloud Trace のタイムライン ビュー
    Trace のタイムライン ビュー

    トレース グラフビュー

    Cloud Trace のグラフビュー
    Trace のグラフビュー

トレースをログと指標に関連付ける

Agent Gateway は、トレース、ログ、指標間のシームレスな関連付けを提供します。

  • ログとトレースの関連付け: Cloud Logging に書き込まれるすべてのゲートウェイ リクエストログ エントリには、projects/PROJECT_ID/traces/TRACE_ID 形式の trace フィールドが含まれています。

    • ログ エクスプローラで、ログエントリをクリックし、[トレースの詳細を表示] を選択して、Trace の対応するスパンに直接移動します。
    • Trace で、[トレースの詳細] ペインの [ログを表示] をクリックして、そのリクエストに関連付けられているすべてのゲートウェイ リクエスト ログを表示します。

  • 指標の関連付け: networkservices.googleapis.com/agentgateway/total_latencies などの Cloud Monitoring 指標で観測されたレイテンシの急増をトレース スパンの内訳と比較して、レイテンシの急増がゲートウェイ内で発生したのか、宛先ツールまたはサーバーで発生したのかを特定します。

トラブルシューティング

このセクションでは、一般的な問題とその解決策について説明します。

  • トレースが Cloud Trace に表示されない:

    1. プロジェクトで Cloud Trace API（cloudtrace.googleapis.com）が有効になっていることを確認します。

      gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID

    2. 必要な Cloud Trace エージェント IAM ロール（roles/cloudtrace.agent）が、必要なすべてのサービス アカウントに付与されていることを確認します。

    3. オブザーバビリティ ポリシーが正しいリージョンに存在し、適切な Agent Gateway を参照していることを確認します。

      gcloud beta network-services telemetry-policies describe POLICY_NAME \
    --location=REGION

    4. 構成された samplingRate を確認します。トラフィック量が少ない場合やサンプリング レートが低い場合は、トレースがすぐにキャプチャされないことがあります。トレースが機能していることを確認するには、100% サンプリング（samplingRate: 1.00）を使用するようにポリシーを一時的に更新します。テストが完了したら、本番環境のレートを復元します。

  • 不完全なトレース スパン:

    トレース スパンがアプリケーション リクエストの子スパンではなく、独立したルート トレースとして表示される場合は、次の操作を行います。

    1. オブザーバビリティ ポリシーで parentBasedSampling が有効（true に設定）になっていることを確認します。
    2. 呼び出し元の AI エージェントまたはワークロードのサービス アカウントに、プロジェクトの Cloud Trace エージェント ロール（roles/cloudtrace.agent）が付与されていることを確認します。これにより、親スパンを Trace にエクスポートできます。
    3. アプリケーションが、分散トレース コンテキストの伝播が有効になっている OpenTelemetry SDK を使用していることを確認します。これにより、W3C traceparent ヘッダーがサービス境界間で伝播されます。詳細については、OpenTelemetry TraceContext propagator のドキュメントをご覧ください。

次のステップ

Codelab

Gemini Enterprise Agent Platform の Agent Gateway でエージェント ワークロードを管理する方法について説明します。

トラブルシューティング

Agent Gateway の接続に関する問題のトラブルシューティング方法について説明します。