Supervisa el tráfico a través de Agent Gateway

Usa esta página para aprender a ver registros, supervisar solicitudes y hacer un seguimiento de los seguimientos distribuidos del tráfico enrutado a través de tu implementación de Agent Gateway.

Logging

Los registros de Agent Gateway se generan con el recurso supervisado networkservices.googleapis.com/Gateway.

Puedes usar estos registros para supervisar las solicitudes de acceso a la puerta de enlace. Esto incluye los registros que se crean cuando Agent Gateway se implementa en modo de ejecución de prueba.

Visualiza los registros de una puerta de enlace específica

Para ver los registros de una puerta de enlace específica, completa los siguientes pasos.

Consulta en la consola

1. En la consola de Google Cloud , accede a la página Explorador de registros.

   Ir a Explorador de registros

2. Haz clic en el botón de activar o desactivar Mostrar consulta.

3. Pega lo siguiente en el campo de la consulta.

   resource.type="networkservices.googleapis.com/Gateway"
   resource.labels.location="REGION"
   resource.labels.gateway_name="AGENT_GATEWAY_NAME"
   

   Reemplaza lo siguiente:

   • REGION: Es la región de tu puerta de enlace.
   • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.

4. Haz clic en Ejecutar consulta.

Nombres de los registros de Agent Platform

Para consultar tipos específicos de entradas de registro en el Explorador de registros, puedes filtrar tu consulta por nombre de registro con el campo logName. En la siguiente tabla, se describen los nombres de los registros principales que generan el Agent Gateway y las operaciones del agente:

Nombre del registro	Descripción
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests	Registros de las decisiones de permitir y denegar de la puerta de enlace.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access	Registros de auditoría de Cloud para las decisiones de AuthorizeUser de Identity-Aware Proxy (IAP).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr	Errores de inicio y ejecución del agente (motor de razonamiento stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout	Salida estándar del agente (motor de razonamiento stdout).

Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

Si usas Model Armor para la limpieza de contenido, esos registros se emiten por separado. Para obtener instrucciones sobre cómo consultar los registros de Model Armor, consulta Visualiza los registros de seguridad del contenido sin procesar en el Explorador de registros.

Importante: Cuando se consultan registros, una ventana de actualización estrecha (por ejemplo, --freshness=6h en consultas de línea de comandos) a veces puede devolver cero filas, incluso si los registros se generaron recientemente. Si tu consulta muestra resultados vacíos, intenta ampliar la ventana de búsqueda (por ejemplo, a --freshness=1d) para verificar si el registro está inhabilitado.

¿Qué se registra?

Las entradas de registro de Agent Gateway contienen información útil para supervisar y depurar el tráfico que entra y sale de tu puerta de enlace.

Campo	Formato del campo	Tipo del campo: opcional u obligatorio	Descripción
				severity insertID timestamp receiveTimestamp trace traceSampled logName	LogEntry	Obligatorio	Los campos generales, como se describe en una entrada de registro.
httpRequest	HttpRequest	Obligatorio	Un protocolo común para registrar solicitudes HTTP.
resource	MonitoredResource	Obligatorio	MonitoredResource es el tipo de recurso asociado con una entrada de registro. El tipo de recurso para Agent Gateway es networkservices.googleapis.com/Gateway.
jsonPayload	objeto (formato de struct)	Obligatorio	Indica la carga útil de la entrada de registro que se expresa como un objeto JSON. El objeto JSON contiene los siguientes campos de Agent Gateway: agentGatewayInfo: Incluye información sobre las solicitudes de Agent Gateway. mcpInfo: Incluye información sobre el método de MCP de la solicitud (por ejemplo, "tools/list" o "tools/call") y el parámetro principal asociado con el método, si lo hay. Por ejemplo, en el caso del método "tools/call", el parámetro es el nombre de la herramienta. agentRegistryResource: Es el nombre del recurso de Agent Registry del servidor de MCP, el agente o el extremo que coincidió con la solicitud. También puedes inspeccionar los detalles del campo serviceExtensionsInfo para obtener información sobre la extensión de autorización (IAP, Model Armor o cualquier otra) que controló la solicitud.

Supervisión

Agent Gateway exporta algunas métricas de Service Extensions a Cloud Monitoring. Si delegas la autorización a las extensiones de servicio, puedes usar estas métricas para supervisar el tráfico hacia y desde tu extensión. Para obtener más detalles, consulta Registro y supervisión de las llamadas de Cloud Load Balancing.

Panel de observabilidad

Agent Gateway proporciona un panel de observabilidad que te permite supervisar, auditar y depurar el tráfico enrutado a través de tus puertas de enlace:

• Tarjetas de resultados: Realiza un seguimiento de la cantidad total de intentos de autorización, fallas de autorización y solicitudes por segundo.
• Gráficos: Visualiza los porcentajes de fallas de autorización (%) y las solicitudes por segundo a lo largo del tiempo.
• Registros de tráfico de salida: Revisa los registros detallados de las consultas de salida, incluidos los rechazos de 403, el tráfico a extremos no registrados y las tendencias generales del tráfico.

Sigue estos pasos para acceder al panel de observabilidad de una puerta de enlace en la consola de Google Cloud :

1. En la consola de Google Cloud , ve a la página Agent Gateway.

   Ir a Agent Gateway

2. Haz clic en el nombre de la puerta de enlace que quieres supervisar.

3. Haz clic en la pestaña Observabilidad.

Requisitos de datos del panel

El panel de observabilidad de Agent Gateway usa las Estadísticas de observabilidad para mostrar datos. Si el panel no carga datos, asegúrate de actualizar el bucket de registros _Default para usar Estadísticas de observabilidad. El panel recupera datos de la vista _AllLogsdel bucket _Default.

Usa Cloud Trace

Vista previa

Este producto o función está sujeto a las "Condiciones de la oferta previa a la DG" en la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Los productos y las funciones de la fase previa a la DG están disponibles “tal como están” y pueden estar sujetos a asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Agent Gateway se integra en Cloud Trace para proporcionar observabilidad de solicitudes de extremo a extremo para las cargas de trabajo de los agentes. Debido a que Agent Gateway funciona como el punto de control central para los agentes de IA, habilitar Trace te brinda visibilidad sobre cómo viajan las solicitudes desde tus agentes a través de la puerta de enlace y por varios servicios, herramientas, agentes y servidores de MCP de Google Cloud . Con el seguimiento de los flujos de solicitudes en estos límites de servicio, Trace ofrece un seguimiento distribuido completo para tus arquitecturas de agentes.

Con Trace, puedes hacer lo siguiente:

• Depura las interacciones de los agentes con precisión: Realiza un seguimiento del recorrido completo de una solicitud a través de los límites de los servicios para aislar los cuellos de botella de latencia y las llamadas de backend con errores.
• Respeta las decisiones de muestreo ascendente: Usa el muestreo basado en el elemento superior para mantener la continuidad del seguimiento de extremo a extremo cuando los agentes o clientes ascendentes inician el seguimiento, lo que garantiza que las solicitudes de alta prioridad se capturen por completo sin aumentar las tasas de muestreo de referencia para el tráfico de rutina.
• Unifica la observabilidad con estándares abiertos: Basados en los estándares de OpenTelemetry y W3C TraceContext, los seguimientos propagan el contexto sin problemas en tus agentes de IA, Agent Gateway, servidores de MCP de destino, o herramientas, y plataformas de supervisión de terceros.
• Acelera el análisis de la causa raíz: Correlaciona los intervalos de seguimiento directamente con los registros y las métricas de solicitudes de la puerta de enlace con trace_id para solucionar problemas de producción con mayor rapidez.

Para obtener más información sobre Trace, consulta la descripción general de Cloud Trace.

Roles obligatorios

Debes tener los siguientes roles de Identity and Access Management (IAM) en tu proyecto:

• Para configurar y actualizar una política de seguimiento: Administrador de red de Compute (roles/compute.networkAdmin) o Administrador de Compute (roles/compute.admin)
• Para ver seguimientos en la consola de Google Cloud : Usuario de Cloud Trace (roles/cloudtrace.user)

Además, para permitir que Agent Gateway escriba intervalos de seguimiento en Trace, debes otorgar el rol de agente de Cloud Trace (roles/cloudtrace.agent) a las siguientes cuentas de servicio:

• Agente de servicio de Compute Engine: [e-mail]
• Agente de servicio de seguridad de redes: [e-mail]
• Agente de servicio de Agent Gateway: [e-mail]
• Cuenta de servicio de la carga de trabajo del agente o del cliente: Si el agente de IA o la carga de trabajo del cliente que realiza la llamada inicia el seguimiento y exporta sus propios intervalos superiores a Trace, también se debe otorgar el rol roles/cloudtrace.agent en el proyecto a la cuenta de servicio de la carga de trabajo o a la cuenta de servicio personalizada adjunta al agente. De lo contrario, solo se escribe el intervalo secundario de Agent Gateway y el intervalo principal faltará en Trace.

Reemplaza PROJECT_NUMBER por el número del proyecto de Google Cloud .

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Habilita el seguimiento

Para habilitar el seguimiento de Agent Gateway, crea un archivo YAML de política de observabilidad y, luego, impórtalo con gcloud CLI.

1. Crea un archivo de configuración llamado 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
   

   Reemplaza lo siguiente:

   • PROJECT_ID: Es el ID del proyecto de Google Cloud .
   • REGION: Es la región de tu puerta de enlace (por ejemplo, europe-west1).
   • POLICY_NAME: Es un nombre para la política de observabilidad (por ejemplo, my-agw-tracing-policy).
   • AGENT_GATEWAY_NAME: Es el nombre de tu puerta de enlace.
   • SAMPLING_RATE: Es la fracción de solicitudes que se deben rastrear. Establece un valor de 0.0 a 1.0. Para entornos de producción con mucho tráfico, recomendamos una tasa del 1% (0.01) o del 0.1% (0.001) para equilibrar los costos de observabilidad y transferencia.
   • ENABLE_PARENT_BASED_SAMPLING: Controla si se debe respetar el bit de muestreo en los encabezados traceparent entrantes de los emisores ascendentes. Se establece en true o false.
   • PARENT_BASED_SAMPLING_RATE: Es la fracción de solicitudes muestreadas previamente que se deben rastrear. Establece un valor de 0.0 a 1.0. Por ejemplo, 1.0 realiza un seguimiento del 100% de las solicitudes previamente muestreadas.

2. Importa la política de observabilidad:

   gcloud beta network-services telemetry-policies import POLICY_NAME \
      --source=tracing-policy.yaml \
      --location=REGION
   

Ver seguimientos

Después de habilitar el seguimiento distribuido y enviar tráfico a través de la puerta de enlace, puedes ver los detalles del seguimiento en la consola de Google Cloud :

1. En la consola de Google Cloud , ve a la página Explorador de seguimiento:

   Ve al Explorador de seguimiento

   También puedes usar la barra de búsqueda para encontrar esta página.

2. En la barra Filtro, ingresa una expresión de filtro de seguimiento (por ejemplo, para filtrar por umbral de latencia, código de estado HTTP o URI de solicitud) o busca por el ID de seguimiento específico.

   Para obtener más información sobre cómo usar la IU del Explorador de seguimiento, consulta Busca y explora seguimientos.

   Explorador de seguimiento

   

   Vista del Explorador de seguimiento en Trace

   Vista de cronograma de seguimiento

   

   Vista de línea de tiempo en Trace

   Vista de gráfico de seguimiento

   

   Vista de gráfico en Trace

Correlaciona los seguimientos con los registros y las métricas

Agent Gateway proporciona una correlación fluida entre seguimientos, registros y métricas:

• Correlación de registro y seguimiento: Cada entrada de registro de solicitud de puerta de enlace escrita en Cloud Logging contiene un campo trace con el formato projects/PROJECT_ID/traces/TRACE_ID.

  • En el Explorador de registros, haz clic en la entrada de registro y, luego, selecciona Ver detalles del seguimiento para navegar directamente al tramo correspondiente en Trace.
  • En Trace, haz clic en Mostrar registros en el panel Detalles del seguimiento para ver todos los registros de solicitudes de puerta de enlace asociados con esa solicitud.

• Correlación de métricas: Compara los picos de latencia observados en las métricas de Cloud Monitoring, como networkservices.googleapis.com/agentgateway/total_latencies, con los desgloses de intervalos de seguimiento para identificar si se produjo un pico de latencia dentro de la puerta de enlace o en la herramienta o el servidor de destino.

Soluciona problemas

En esta sección, se describen los problemas comunes y sus soluciones.

• Los seguimientos no aparecen en Cloud Trace:

  1. Verifica que la API de Cloud Trace (cloudtrace.googleapis.com) esté habilitada en tu proyecto:

     gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
     

  2. Verifica que se hayan otorgado los roles de IAM de agente de Cloud Trace (roles/cloudtrace.agent) necesarios a todas las cuentas de servicio requeridas.

  3. Verifica que la política de observabilidad exista en la región correcta y que haga referencia a la puerta de enlace de Agent Gateway adecuada:

     gcloud beta network-services telemetry-policies describe POLICY_NAME \
         --location=REGION
     

  4. Verifica el samplingRate configurado. Si el volumen de tráfico es bajo o la tasa de muestreo es baja, es posible que los seguimientos no se capturen de inmediato. Para confirmar que el seguimiento funciona, puedes actualizar de forma temporal tu política para usar un muestreo del 100% (samplingRate: 1.00). Restablece tu tasa de producción cuando termines de realizar las pruebas.

• Intervalos de seguimiento incompletos:

  Si los intervalos de seguimiento aparecen como seguimientos raíz independientes o desconectados en lugar de intervalos secundarios de las solicitudes de tu aplicación, haz lo siguiente:

  1. Verifica que parentBasedSampling esté habilitado (establecido en true) en tu política de observabilidad.
  2. Verifica que se haya otorgado el rol de agente de Cloud Trace (roles/cloudtrace.agent) a la cuenta de servicio del agente de IA o de la carga de trabajo que realiza la llamada en el proyecto para que los intervalos superiores se puedan exportar a Trace.
  3. Verifica que tu aplicación use un SDK de OpenTelemetry que tenga habilitada la propagación del contexto de seguimiento distribuido para que el encabezado traceparent de W3C se propague entre los límites del servicio. Para obtener más información, consulta la documentación del propagador TraceContext de OpenTelemetry.

¿Qué sigue?

Codelab

Codelab: Administra cargas de trabajo de agentes con Agent Platform

Aprende a administrar las cargas de trabajo de agentes con Agent Gateway en Gemini Enterprise Agent Platform.

Solución de problemas

Soluciona problemas de Agent Gateway

Aprender a solucionar problemas de conectividad de Agent Gateway