透過 Agent Gateway 監控流量

請參閱本頁，瞭解如何查看記錄、監控要求，以及追蹤透過 Agent Gateway 部署作業轉送的流量分散式追蹤記錄。

記錄

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

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

查看特定閘道的記錄

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

Agent Platform 記錄名稱

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

將 PROJECT_ID 替換為 Cloud de Confiance by S3NS 專案 ID。

如果您使用 Model Armor 進行內容清除，系統會另外發出這些記錄。 如需查詢 Model Armor 記錄的說明，請參閱「在 Logs Explorer 中查看原始內容安全記錄」。

記錄內容

Agent Gateway 記錄項目包含實用資訊，有助於監控及偵錯 Agent Gateway 來回流量。

監控

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

觀測能力資訊主頁

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

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

如要在 Cloud de Confiance 控制台中存取閘道的觀測資訊主頁，請按照下列步驟操作：

1. 前往 Cloud de Confiance 控制台的「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 代理的中央控制點，啟用追蹤功能後，您就能掌握要求從代理傳輸到閘道，再傳輸到多個 Cloud de Confiance 服務、工具、代理和 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)
• 如要在 Cloud de Confiance 控制台中查看追蹤記錄，請使用 Cloud Trace 使用者 (roles/cloudtrace.user) 角色。

此外，如要允許代理程式閘道將追蹤記錄範圍寫入 Trace，您必須將 Cloud Trace 代理程式角色 (roles/cloudtrace.agent) 授予下列服務帳戶：

• Compute Engine 服務代理： service-PROJECT_NUMBER@compute-system.s3ns-system.iam.gserviceaccount.com
• Network Security 服務代理： service-PROJECT_NUMBER@gcp-sa-networksecurity.s3ns-system.iam.gserviceaccount.com
• Agent Gateway 服務代理： service-PROJECT_NUMBER@gcp-sa-agentgateway.s3ns-system.iam.gserviceaccount.com
• 代理程式或用戶端工作負載服務帳戶：如果呼叫的 AI 代理程式或用戶端工作負載啟動追蹤並將自己的父項範圍匯出至 Trace，則工作負載的服務帳戶或附加至代理程式的自訂服務帳戶也必須在專案中獲授 roles/cloudtrace.agent 角色。否則，系統只會寫入 Agent Gateway 子項時距，且追蹤記錄中會缺少父項時距。

將 PROJECT_NUMBER 替換為 Cloud de Confiance 專案編號。

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

啟用追蹤功能

如要為代理程式閘道啟用追蹤功能，請建立可觀測性政策 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： Cloud de Confiance 專案 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
   

查看追蹤記錄

啟用分散式追蹤並透過閘道傳送流量後，即可在 Cloud de Confiance 控制台中查看追蹤詳細資料：

1. 前往 Cloud de Confiance 控制台的 「Trace Explorer」頁面：

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

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

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

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

   追蹤記錄探索工具

   

   追蹤記錄時間軸檢視畫面

   

   追蹤記錄圖表檢視畫面

   

根據記錄和指標找出追蹤記錄的關聯

Agent Gateway 可順暢地將追蹤記錄、記錄和指標相互關聯：

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

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

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

疑難排解

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

• 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 傳播器說明文件。

後續步驟