通过本页面，您可以了解如何查看日志、监控请求以及跟踪通过 Agent Gateway 部署路由的流量的分布式跟踪记录。
Cloud Logging
Agent Gateway 日志是使用 networkservices.googleapis.com/Gateway 受监控的资源生成的。
您可以使用这些日志来监控对网关的访问请求。这包括在试运行模式下部署 Agent Gateway 时创建的日志。如需查询 Identity-Aware Proxy (IAP) 统一访问权限政策 (UAP)、语义治理政策、Model Armor 和 VPC Service Controls 中的试运行违规日志，并生成合并的“本会被屏蔽”报告，请参阅审核各项控制措施的试运行政策违规情况。
查看特定网关的日志
如需查看特定网关的日志，请完成以下步骤。
控制台查询
在 Google Cloud 控制台中，前往 Logs Explorer 页面。
点击显示查询切换开关。
将以下内容粘贴到查询字段中。
resource.type="networkservices.googleapis.com/Gateway" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME"
替换以下内容：
REGION：网关所在的区域。AGENT_GATEWAY_NAME：网关的名称。
点击运行查询。
Agent Platform 日志名称
如需在 Logs Explorer 中查询特定类型的日志条目，您可以使用 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 日志，请参阅在 Logs Explorer 中查看原始内容安全日志。
记录的内容
Agent Gateway 日志条目包含对监控和调试进出网关的流量有用的信息。
| 字段 | 字段格式 | 字段类型：必填或可选 | 说明 |
|---|---|---|---|
| severity insertID timestamp receiveTimestamp trace traceSampled logName |
LogEntry | 必需 | 日志条目中描述的常规字段。 |
| httpRequest | HttpRequest | 必填 | 用于记录 HTTP 请求的通用协议。 |
| resource | MonitoredResource | 必填 |
|
| jsonPayload | object (Struct format) | 必需 | 以 JSON 对象表示的日志条目载荷。JSON 对象包含以下 Agent Gateway 字段：
|
政策传播和日志提取延迟时间
更新网关访问规则或调查安全性事件时，请考虑以下传播和提取时间范围：
- Unified Access Policies (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) 日志条目（通常可在几秒钟内在 Logs Explorer 中搜索到）。导出到 Trace 的分布式跟踪 span 也会在 span 完成后的几秒钟内显示，而来自代理异常检测的带外威胁检测则会异步评估（请参阅遥测和安全发现结果延迟时间）。
保留网关审核日志并将其导出到 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)，以强制执行一次写入、多次读取 (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 提供了一个可观测性信息中心，可让您监控、审核和调试通过网关路由的流量：
- 统计信息摘要：跟踪尝试授权的总次数、授权失败次数和每秒请求数。
- 图表：直观呈现一段时间内的授权失败率 (%) 和每秒请求数。
- 出站流量日志：查看出站查询的详细日志，包括
403拒绝、流向未注册端点的流量以及总体流量趋势。
请按照以下步骤在 Google Cloud 控制台中访问网关的可观测性信息中心：
在 Google Cloud 控制台中，前往 Agent Gateway 页面。
点击要监控的网关的名称。
点击可观测性标签页。
信息中心数据要求
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. - 网络安全服务代理：
service-PROJECT_NUMBER@gcp-sa-networksecurity. - Agent Gateway 服务代理：
service-PROJECT_NUMBER@gcp-sa-agentgateway. - 智能体或客户端工作负载服务账号：如果发起调用的 AI 智能体或客户端工作负载启动了跟踪记录并将其自己的父级 span 导出到 Trace，则还必须向工作负载的服务账号或附加到智能体的自定义服务账号授予项目的
roles/cloudtrace.agent角色。否则，系统只会写入 Agent Gateway 子 span，而 Trace 中会缺少父 span。
将 PROJECT_NUMBER 替换为您的 Google Cloud 项目编号。
如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。
启用跟踪功能
如需为 Agent Gateway 启用跟踪功能，请创建可观测性政策 YAML 文件，并使用 gcloud CLI 将其导入。
创建名为
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% 的预采样请求。
导入可观测性政策：
gcloud beta network-services telemetry-policies import POLICY_NAME \ --source=tracing-policy.yaml \ --location=REGION
查看跟踪记录
启用分布式跟踪并通过网关发送流量后，您可以在 Google Cloud 控制台中查看跟踪记录详细信息：
-
在 Google Cloud 控制台中，前往
Trace 探索器页面：您也可以使用搜索栏查找此页面。
在过滤条件栏中，输入跟踪记录过滤表达式（例如，按延迟时间阈值、HTTP 状态代码或请求 URI 进行过滤），或按特定跟踪记录 ID 进行搜索。
如需详细了解如何使用 Trace 探索器界面，请参阅查找和探索跟踪记录。
Trace 探索器
Trace 中的 Trace 探索器视图 跟踪记录时间轴视图
Trace 中的时间轴视图 跟踪记录图表视图
Trace 中的图表视图
将跟踪记录与日志和指标相关联
Agent Gateway 可在跟踪记录、日志和指标之间提供无缝关联：
日志跟踪记录关联：写入 Logging 的每个网关请求日志条目都包含一个
trace字段，格式为：projects/PROJECT_ID/traces/TRACE_ID。- 在 Logs Explorer 中，点击日志条目，然后选择查看跟踪记录详情，以直接前往 Trace 中的相应 span。
- 在 Trace 中，点击跟踪记录详情窗格中的显示日志，以查看与该请求关联的所有网关请求日志。
指标相关性：将 Monitoring 指标（例如
networkservices.googleapis.com/agentgateway/total_latencies）中观察到的延迟时间峰值与跟踪记录 span 细分进行比较，以确定延迟时间峰值是发生在网关内还是发生在目标工具或服务器上。
问题排查
本部分介绍了常见问题及其解决方法。
跟踪记录未显示在 Cloud Trace 中：
验证您的项目是否已启用 Cloud Trace API (
cloudtrace.googleapis.com)：gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
验证是否已向所有必需的服务账号授予必需的 Cloud Trace Agent IAM 角色 (
roles/cloudtrace.agent)。验证可观测性政策是否存在于正确的区域中，并且引用了适当的 Agent Gateway 网关：
gcloud beta network-services telemetry-policies describe POLICY_NAME \ --location=REGION检查配置的
samplingRate。如果流量较低或采样率较低，则可能无法立即捕获跟踪记录。如需确认跟踪功能是否正常运行，您可以暂时更新政策以使用 100% 采样 (samplingRate: 1.00)。测试完成后，请恢复生产速率。
不完整的跟踪 span：
如果跟踪 span 显示为独立或断开连接的根跟踪记录，而不是应用请求的子 span，请执行以下操作：
- 验证可观测性政策中是否已启用
parentBasedSampling（设置为true）。 - 验证调用方 AI 智能体或工作负载的服务账号是否已被授予项目的 Cloud Trace Agent 角色 (
roles/cloudtrace.agent)，以便将父级 span 导出到 Trace。 - 验证您的应用是否使用了启用了分布式跟踪记录上下文传播的 OpenTelemetry SDK，以便 W3C
traceparent标头跨服务边界传播。如需了解详情，请参阅 OpenTelemetry TraceContext 传播器文档。
- 验证可观测性政策中是否已启用
后续步骤
Codelab：使用 Agent Platform 治理智能体工作负载
了解如何通过 Gemini Enterprise Agent Platform 上的 Agent Gateway 治理智能体工作负载。