透過 Agent Gateway 監控流量

本頁面說明如何查看記錄、監控要求，以及追蹤透過 Agent Gateway 部署項目轉送的流量分散式追蹤記錄。

記錄

Agent Gateway 記錄是使用 networkservices.googleapis.com/Gateway 受監控資源產生。

您可以使用這些記錄，監控對閘道的存取要求。包括在空跑模式下部署 Agent Gateway 時建立的記錄。

查看特定閘道的記錄

如要查看特定閘道的記錄，請完成下列步驟。

Agent Platform 記錄名稱

如要在記錄檔探索工具中查詢特定類型的記錄項目，您可以使用 logName 欄位，依記錄名稱篩選查詢。下表說明 Agent Gateway 和代理端作業產生的主要記錄名稱：

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

如果您使用 Model Armor 清理內容，系統會另外產生這些記錄。如要瞭解如何查詢 Model Armor 記錄，請參閱「在記錄檔探索工具中查看原始內容安全性記錄」。

記錄內容

Agent Gateway 記錄項目包含實用資訊，有助監控進出閘道的流量及偵錯。

監控

Agent Gateway 會將部分 Service Extensions 指標匯出至 Cloud Monitoring。如果您將授權委派給 Service Extensions，可以使用這些指標監控擴充功能的往來流量。詳情請參閱「Cloud Load Balancing 呼叫的記錄和監控」。

觀測能力資訊主頁

Agent Gateway 提供觀測能力資訊主頁，可讓您監控、稽核及偵錯透過閘道轉送的流量：

• 評量表：追蹤授權嘗試總數、授權失敗次數，以及每秒要求數。
• 圖表：以圖表呈現授權失敗率 (%) 和每秒要求數。
• 輸出流量記錄：查看輸出查詢的詳細記錄，包括 403 拒絕、傳送至未註冊端點的流量，以及整體流量趨勢。

請按照下列步驟，在 Google Cloud 控制台存取閘道的觀測能力資訊主頁：

1. 前往 Google Cloud 控制台的「Agent Gateway」頁面。

   前往 Agent Gateway

2. 按一下要監控的閘道名稱。

3. 點選「觀測能力」分頁標籤。

資訊主頁資料規定

Agent Gateway 觀測能力資訊主頁會使用 Observability Analytics 顯示資料。如果資訊主頁未載入資料，請務必將 _Default 記錄檔 bucket 升級為使用 Observability Analytics。資訊主頁會從 _Default bucket 的 _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，直接將追蹤記錄 span 與閘道要求記錄和指標建立關聯，加快排解正式環境問題。

如要進一步瞭解 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 將追蹤記錄 span 寫入 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 代理或用戶端工作負載啟動追蹤記錄，並將自己的父項 span 匯出至 Trace，則工作負載的服務帳戶或附加至代理的自訂服務帳戶，也必須具備專案的 roles/cloudtrace.agent 角色。否則，系統只會寫入 Agent Gateway 子項 span，而 Trace 中會缺少父項 span。

將 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 Explorer」頁面：

   前往「Trace explorer」(Trace 探索工具)

   您也可以透過搜尋列找到這個頁面。

2. 在「Filter」(篩選器) 列中，輸入追蹤記錄篩選運算式 (例如依延遲時間門檻、HTTP 狀態碼或要求 URI 篩選)，或依特定追蹤記錄 ID 搜尋。

   如要進一步瞭解如何使用 Trace Explorer UI，請參閱「尋找及探索追蹤記錄」。

   Trace 探索工具

   

   追蹤記錄時間軸檢視畫面

   

   追蹤記錄圖表檢視畫面

   

將追蹤記錄與記錄和指標建立關聯

Agent Gateway 可完美連結追蹤記錄、記錄和指標：

• 記錄追蹤關聯：寫入 Cloud Logging 的每個閘道要求記錄項目都包含 trace 欄位，格式為：projects/PROJECT_ID/traces/TRACE_ID。

  • 在「Logs Explorer」中，按一下記錄項目，然後選取「View trace details」(查看追蹤記錄詳細資料)，即可直接前往 Trace 中的對應 span。
  • 在 Trace 中，按一下「Trace Details」(追蹤記錄詳細資料) 窗格中的「Show logs」(顯示記錄)，即可查看與該要求相關聯的所有閘道要求記錄。

• 指標關聯：比較 Cloud Monitoring 指標 (例如 networkservices.googleapis.com/agentgateway/total_latencies) 中觀察到的延遲時間高峰，以及追蹤記錄 span 細目，判斷延遲時間高峰是發生在閘道內，還是發生在目的地工具或伺服器。

疑難排解

本節說明常見問題和解決方法。

• 追蹤記錄未顯示在 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)。測試完成後，請還原正式環境取樣率。

• 追蹤記錄 span 不完整：

  如果追蹤記錄 span 顯示為獨立或中斷連線的根追蹤記錄，而非應用程式要求的子項 span，請執行下列操作：

  1. 確認觀測能力政策中的 parentBasedSampling 已啟用 (設為 true)。
  2. 確認呼叫的 AI 代理或工作負載服務帳戶，已具備專案的 Cloud Trace 代理角色 (roles/cloudtrace.agent)，這樣才能將父項 span 匯出至 Trace。
  3. 確認應用程式使用的 OpenTelemetry SDK 已啟用分散式追蹤記錄相關資訊傳播功能，以便 W3C traceparent 標頭在服務邊界之間傳播。詳情請參閱 OpenTelemetry TraceContext 傳播器說明文件。

後續步驟