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 registros distribuidos para el tráfico que se enruta 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 creados 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.

Nombres de 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 Agent Gateway y las operaciones del agente:

Reemplaza PROJECT_ID por el ID del proyecto de Cloud de Confiance by S3NS .

Si usas Model Armor para la sanitización 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.

¿Qué se registra?

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

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 tu extensión y desde ella. 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 que se enruta a través de tus puertas de enlace:

• Cuadros de evaluación: Realiza un seguimiento de la cantidad total de autorizaciones intentadas, los errores de autorización y las solicitudes por segundo.
• Gráficos: Visualiza los porcentajes de errores 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 búsquedas de salida, incluidos los rechazos de 403, el tráfico a extremos no registrados y las tendencias de tráfico totales.

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

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

   Ir a Agent Gateway

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

3. Haz clic en la pestaña Observabilidad.

Requisitos de los datos del panel

El panel de observabilidad de Agent Gateway usa 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 _AllLogs del bucket _Default.

Usa Cloud Trace

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

Con Trace, puedes hacer lo siguiente:

• Depura las interacciones del agente con precisión: Haz un seguimiento del recorrido completo de una solicitud a través de los límites del servicio para aislar los cuellos de botella de latencia y las llamadas de backend con errores.
• Respeta las decisiones de muestreo ascendentes: Usa el muestreo basado en la relación principal-secundario para mantener la continuidad del registro de extremo a extremo cuando los agentes o clientes ascendentes inician el registro, 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: Las pistas, creadas con los estándares de OpenTelemetry y TraceContext de W3C, propagan el contexto sin problemas en tus agentes de IA, Agent Gateway, servidores o herramientas MCP de destino 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 más rápido.

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 los registros en la consola de Cloud de Confiance : 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: service-PROJECT_NUMBER@compute-system.s3ns-system.iam.gserviceaccount.com
• Agente de servicio de Seguridad de red: service-PROJECT_NUMBER@gcp-sa-networksecurity.s3ns-system.iam.gserviceaccount.com
• Agente de servicio de Agent Gateway: service-PROJECT_NUMBER@gcp-sa-agentgateway.s3ns-system.iam.gserviceaccount.com
• 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 inician el registro y exportan sus propios intervalos principales 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 escribirá el intervalo secundario de Agent Gateway y faltará el intervalo principal en Trace.

Reemplaza PROJECT_NUMBER por el número de proyecto de Cloud de Confiance .

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 registro de Agent Gateway, crea un archivo YAML de política de observabilidad y, luego, impórtalo con la 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 Cloud de Confiance .
   • 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 rastrearán. Se establece en un valor de 0.0 a 1.0. Para los entornos de producción con mucho tráfico, recomendamos una tasa del 1% (0.01) o del 0.1% (0.001) para equilibrar la observabilidad y los costos de transferencia.
   • ENABLE_PARENT_BASED_SAMPLING: Controla si se debe tener en cuenta el bit de muestra en los encabezados traceparent entrantes de los llamadores upstream. Se establece en true o false.
   • PARENT_BASED_SAMPLING_RATE: Es la fracción de solicitudes previas al muestreo que se registrarán. Se establece en un valor de 0.0 a 1.0. Por ejemplo, 1.0 registra el 100% de las solicitudes previas al muestreo.

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 tu puerta de enlace, puedes ver los detalles del seguimiento en la consola de Cloud de Confiance :

1. En la consola de Cloud de Confiance , 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 Cómo buscar y explorar seguimientos.

   Explorador de seguimiento

   

   Vista de línea de tiempo del registro

   

   Vista de gráfico de seguimiento

   

Correlaciona los registros con los seguimientos y las métricas

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

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

  • En el Explorador de registros, haz clic en la entrada de registro y, luego, selecciona Ver detalles de seguimiento para navegar directamente al intervalo correspondiente en Trace.
  • En Trace, haz clic en Mostrar registros en el panel Detalles del registro para ver todos los registros de solicitudes de la puerta de enlace asociados a 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 los 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 o la tasa de muestreo son bajos, es posible que los registros no se capturen de inmediato. Para confirmar que el registro de seguimiento funciona, puedes actualizar temporalmente tu política para usar un muestreo del 100% (samplingRate: 1.00). Restablece tu tasa de producción cuando termines 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 (configurado como true) en tu política de observabilidad.
  2. Verifica que se haya otorgado a la cuenta de servicio del agente de IA o la carga de trabajo que realiza la llamada el rol de agente de Cloud Trace (roles/cloudtrace.agent) en el proyecto para que los tramos principales 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 a través de los límites del servicio. Para obtener más información, consulta la documentación del propagador TraceContext de OpenTelemetry.

¿Qué sigue?