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

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

Cloud Logging

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

これらのログを使用して、ゲートウェイへのアクセス リクエストをモニタリングできます。これには、Agent Gateway がドライラン モードでデプロイされたときに作成されたログが含まれます。Identity-Aware Proxy(IAP)統合アクセス ポリシー(UAP)、セマンティック ガバナンス ポリシー、Model Armor、VPC Service Controls でドライラン違反ログをクエリし、統合された「ブロックされた可能性がある」レポートを生成するには、コントロール全体でドライラン ポリシー違反を監査するをご覧ください。

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

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

コンソール クエリ

  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 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 など)に関する情報を確認することもできます。

ポリシーの伝播とログの取り込みレイテンシ

ゲートウェイ アクセスルールを更新する場合や、セキュリティ イベントを調査する場合は、次の伝播ウィンドウと取り込みウィンドウを考慮してください。

  • 統合アクセス ポリシー(UAP)の伝播: Agent Gateway によって適用される UAP の更新(DENY ルールの追加や iamEnforcementMode の "DRY_RUN" から "ENFORCE" への切り替えなど)は、結果整合性が保たれます。直接ポリシーの変更は通常 2 分以内に有効になりますが、グローバルに反映されるまでに 7 分以上かかることがあります(アクセス変更の伝播をご覧ください)。principalSet のメンバーシップの変更が同期されるまでに数分から数時間かかることがあります。
  • 緊急トラフィック停止: UAP ルールは、Agent Gateway での新しい認可チェック時に評価されます。エージェント コンテナを終了したり、すでに確立されているストリーミング接続を強制的に閉じたりすることはありません。アクティブなインシデント中に、不正使用されたエージェントや不正な動作をしているエージェントを直ちに停止するには、ゲートウェイ拒否ルールを適用するだけでなく、エージェント ランタイムを削除するか、リビジョン トラフィックを再ルーティングします。手順については、緊急停止とアクセス権の取り消しをご覧ください。
  • ログ、トレース、検出のレイテンシ: Agent Gateway は、リクエストパスで IAP ポリシーと Model Armor ポリシーを同期的に評価し、networkservices.googleapis.com/gateway_requests ログエントリと cloudaudit.googleapis.com/data_access(AuthorizeUser)ログエントリをほぼリアルタイムで書き込みます(通常、ログ エクスプローラで数秒以内に検索可能)。Trace にエクスポートされた分散トレーススパンも、スパンの完了から数秒以内に表示されます。一方、Agent Anomaly Detectionからの帯域外脅威検出は非同期で評価されます(テレメトリーとセキュリティ検出結果のレイテンシをご覧ください)。

ゲートウェイ監査ログを保持して SIEM にエクスポートする

Agent Gateway のアクセス決定を改ざん防止のコンプライアンス証拠として保持し、脅威モニタリングを一元化するには、Logging バケットをロックして、ゲートウェイ ログをセキュリティ情報およびイベント管理(SIEM)プラットフォームにストリーミングします。

  • 改ざん防止保持(ロックされたログバケット): networkservices.googleapis.com/gateway_requests ログと cloudaudit.googleapis.com/data_access ログを、保持期間(--retention-days)が構成されたカスタム Logging バケットに転送し、バケットを永続的にロック(gcloud logging buckets update BUCKET_ID --location=LOCATION --locked)して、1 回書き込み複数回読み取り(WORM)コンプライアンス ストレージを適用します。手順ガイドについては、監査ログの改ざん防止保持をご覧ください。
  • SIEM エクスポート: logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access") の一致フィルタを使用してログシンク(または組織レベルの集約シンク)を作成し、ゲートウェイの許可と拒否の決定を Google Security Operations(Google SecOps)、Pub/Sub(サードパーティの SIEM 取り込み用)、BigQuery、または Cloud Storage に継続的にエクスポートします。gcloud CLI シンク作成コマンドとフィルタの例については、監査ログを SIEM にエクスポートするをご覧ください。

Cloud Monitoring

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

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

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

  • スコアカード: 承認試行回数、承認失敗回数、1 秒あたりのリクエスト数の合計を追跡します。
  • グラフ: 承認失敗率(%)と 1 秒あたりのリクエスト数を時系列で可視化します。
  • 下り(外向き)トラフィック ログ: 403 拒否、未登録のエンドポイントへのトラフィック、全体的なトラフィックの傾向など、下り(外向き)クエリの詳細なログを確認します。

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

  1. Google Cloud コンソールで、[Agent Gateway] ページに移動します。

    Agent Gateway に移動

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

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

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

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

Cloud Trace を使用する

Agent Gateway は Cloud Trace と統合されており、エージェント ワークロードのエンドツーエンドのリクエスト オブザーバビリティを提供します。Agent Gateway は AI エージェントの一元管理ポイントとして機能するため、Trace を有効にすると、リクエストがエージェントからゲートウェイを介して複数の 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
  • ネットワーク セキュリティ サービス エージェント: 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 エクスプローラ

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

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

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

    トレースグラフ ビュー

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

トレースをログおよび指標と関連付ける

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

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

    • ログ エクスプローラでログエントリをクリックし、[トレースの詳細を表示] を選択して、Trace の対応するスパンに直接移動します。
    • Trace で、[トレースの詳細] ペインの [ログを表示] をクリックして、そのリクエストに関連付けられているすべてのゲートウェイ リクエスト ログを表示します。
  • 指標の相関関係: networkservices.googleapis.com/agentgateway/total_latencies などの 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. 親スパンを Trace にエクスポートできるように、呼び出し元の AI エージェントまたはワークロードのサービス アカウントに、プロジェクトに対する Cloud Trace エージェントのロール(roles/cloudtrace.agent)が付与されていることを確認します。
    3. アプリケーションが、分散トレース コンテキストの伝播が有効になっている OpenTelemetry SDK を使用していることを確認します。これにより、W3C traceparent ヘッダーがサービス境界を越えて伝播されます。詳細については、OpenTelemetry TraceContext プロパゲーターのドキュメントをご覧ください。

次のステップ

Codelab

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

トラブルシューティング

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