通过 Agent Gateway 监控流量

通过本页面，您可以了解如何查看日志、监控请求以及跟踪通过 Agent Gateway 部署路由的流量的分布式跟踪记录。

日志记录

Agent Gateway 日志是使用 networkservices.googleapis.com/Gateway 受监控的资源生成的。

您可以使用这些日志来监控对网关的访问请求。这包括在试运行模式下部署 Agent Gateway 时创建的日志。

查看特定网关的日志

如需查看特定网关的日志，请完成以下步骤。

Agent Platform 日志名称

如需在 Logs Explorer 中查询特定类型的日志条目，您可以使用 logName 字段按日志名称过滤查询。下表介绍了由 Agent Gateway 和智能体端操作生成的主要日志名称：

请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

如果您使用 Model Armor 进行内容清理，这些日志会单独发出。 如需了解如何查询 Model Armor 日志，请参阅在 Logs Explorer 中查看原始内容安全日志。

记录的内容

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 日志存储桶以使用 Observability Analytics。信息中心从 _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 将跟踪记录 span 直接与网关请求日志和指标相关联，从而更快地排查生产问题。

如需详细了解 Trace，请参阅 Cloud Trace 概览。

所需的角色

您必须在项目中拥有以下 Identity and Access Management (IAM) 角色：

• 如需配置和更新跟踪政策，请执行以下操作：Compute Network Admin (roles/compute.networkAdmin) 或 Compute Admin (roles/compute.admin)
• 如需在 Google Cloud 控制台中查看跟踪记录：Cloud Trace User (roles/cloudtrace.user)

此外，如需允许 Agent Gateway 将跟踪 span 写入 Trace，您必须向以下服务账号授予 Cloud Trace Agent 角色 (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 智能体或客户端工作负载启动了跟踪记录并将其自己的父级 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 探索器页面：

   转到 Trace 探索器

   您也可以使用搜索栏查找此页面。

2. 在过滤条件栏中，输入跟踪记录过滤表达式（例如，按延迟时间阈值、HTTP 状态代码或请求 URI 进行过滤），或按特定跟踪记录 ID 进行搜索。

   如需详细了解如何使用 Trace 探索器界面，请参阅查找和探索跟踪记录。

   Trace 探索器

   

   跟踪记录时间轴视图

   

   跟踪记录图表视图

   

将跟踪记录与日志和指标相关联

Agent Gateway 可在跟踪记录、日志和指标之间建立无缝关联：

• 日志跟踪记录关联：写入 Cloud Logging 的每个网关请求日志条目都包含一个 trace 字段，其格式为：projects/PROJECT_ID/traces/TRACE_ID。

  • 在 Logs Explorer 中，点击日志条目，然后选择查看跟踪记录详细信息，以直接导航到 Trace 中的相应 span。
  • 在 Trace 中，点击跟踪记录详细信息窗格中的显示日志，以查看与该请求关联的所有网关请求日志。

• 指标相关性：将 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 Agent 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 Agent 角色 (roles/cloudtrace.agent)，以便将父级 span 导出到 Trace。
  3. 验证您的应用是否使用了启用了分布式跟踪记录上下文传播的 OpenTelemetry SDK，以便 W3C traceparent 标头跨服务边界传播。如需了解详情，请参阅 OpenTelemetry TraceContext 传播器文档。

后续步骤