通过 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 会将一些 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 日志存储桶以使用 Observability Analytics。信息中心从 _Default 存储桶的 _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 Network Admin (roles/compute.networkAdmin) 或 Compute Admin (roles/compute.admin)
• 如需在 Cloud de Confiance 控制台中查看跟踪记录：Cloud Trace User (roles/cloudtrace.user)

此外，如需允许 Agent Gateway 将跟踪范围写入 Trace，您必须向以下服务账号授予 Cloud Trace Agent 角色 (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 智能体或客户端工作负载服务账号：如果调用 AI 智能体或客户端工作负载启动了跟踪并将自己的父级 span 导出到 Trace，则还必须向工作负载的服务账号或附加到智能体的自定义服务账号授予项目的 roles/cloudtrace.agent 角色。否则，系统只会写入 Agent Gateway 子 span，而父 span 将在跟踪记录中缺失。

将 PROJECT_NUMBER 替换为您的 Cloud de Confiance 项目编号。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

启用跟踪功能

如需为 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：您的 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 探索器页面：

   转到 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）中观察到的延迟时间峰值与跟踪跨度细分进行比较，以确定延迟时间峰值是发生在网关内还是目标工具或服务器中。

问题排查

本部分介绍了常见问题及其解决方案。

• 跟踪记录未显示在 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：

  如果轨迹跨度显示为独立的根轨迹或断开连接的根轨迹，而不是应用请求的子跨度，请执行以下操作：

  1. 验证您的可观测性政策中是否已启用 parentBasedSampling（设置为 true）。
  2. 验证调用 AI 智能体或工作负载的服务账号是否已在项目上被授予 Cloud Trace Agent 角色 (roles/cloudtrace.agent)，以便将父 span 导出到 Trace。
  3. 验证您的应用是否使用了已启用分布式跟踪记录上下文传播的 OpenTelemetry SDK，以便 W3C traceparent 标头跨服务边界传播。如需了解详情，请参阅 OpenTelemetry TraceContext 传播器文档。

后续步骤