Monitorare il traffico tramite Agent Gateway

Utilizza questa pagina per scoprire come visualizzare i log, monitorare le richieste e monitorare le tracce distribuite per il traffico instradato tramite il deployment di Agent Gateway.

Logging

I log di Agent Gateway vengono generati utilizzando la risorsa monitorata networkservices.googleapis.com/Gateway.

Puoi utilizzare questi log per monitorare le richieste di accesso al gateway. Sono inclusi i log creati quando viene eseguito il deployment di Agent Gateway in modalità dry run.

Visualizza i log per un gateway specifico

Per visualizzare i log di un gateway specifico, completa i seguenti passaggi.

Query dalla console

  1. Nella console Google Cloud , vai alla pagina Esplora log.

    Vai a Esplora log

  2. Fai clic sul pulsante di attivazione/disattivazione Mostra query.

  3. Incolla quanto segue nel campo della query.

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

    Sostituisci quanto segue:

    • REGION: la regione del gateway.
    • AGENT_GATEWAY_NAME: il nome del gateway.

  4. Fai clic su Esegui query.

Nomi dei log di Agent Platform

Per eseguire query su tipi specifici di voci di log in Esplora log, puoi filtrare la query in base al nome del log utilizzando il campo logName. La tabella seguente descrive i nomi dei log principali generati da Agent Gateway e dalle operazioni lato agente:

Nome log Descrizione
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests Log per le decisioni di autorizzazione e negazione del gateway.
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access Cloud Audit Logs per le decisioni di Identity-Aware Proxy (IAP) AuthorizeUser.
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr Errori di avvio ed esecuzione lato agente (motore di ragionamento stderr).
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout Output standard lato agente (motore di ragionamento stdout).

Sostituisci PROJECT_ID con l'ID progetto Google Cloud .

Se utilizzi Model Armor per la sanitizzazione dei contenuti, i log vengono emessi separatamente. Per istruzioni su come eseguire query sui log di Model Armor, consulta Visualizza i log di sicurezza dei contenuti non elaborati in Esplora log.

Informazioni registrate nei log

Le voci di log di Agent Gateway contengono informazioni utili per monitorare ed eseguire il debug del traffico da e verso il gateway.

Campo Formato campo Tipo di campo: obbligatorio o facoltativo Descrizione
severity
insertID
timestamp
receiveTimestamp
trace
traceSampled
logName		 LogEntry Obbligatorio I campi generali come descritti in una voce di log.
httpRequest HttpRequest Obbligatorio Un protocollo comune per il logging delle richieste HTTP.
resource MonitoredResource Obbligatorio

MonitoredResource è il tipo di risorsa associato a una voce di log. Il tipo di risorsa per Agent Gateway è networkservices.googleapis.com/Gateway.
jsonPayload oggetto (formato Struct) Obbligatorio

Il payload della voce di log espresso come oggetto JSON. L'oggetto JSON contiene i seguenti campi di Agent Gateway:

  • agentGatewayInfo: include informazioni sulle richieste di Agent Gateway.

    • mcpInfo: include informazioni sul metodo MCP della richiesta (ad esempio "tools/list" o "tools/call") e sul parametro principale associato al metodo, se presente. Ad esempio, nel caso del metodo "tools/call", il parametro è il nome dello strumento.
    • agentRegistryResource: il nome della risorsa Agent Registry del server MCP, dell'agente o dell'endpoint corrispondente alla richiesta.

  • Puoi anche esaminare i dettagli del campo serviceExtensionsInfo per informazioni sull'estensione dell'autorizzazione (IAP, Model Armor o altro) che ha gestito la richiesta.

Monitoraggio

Agent Gateway esporta alcune metriche di Service Extensions in Cloud Monitoring. Se deleghi l'autorizzazione alle estensioni di servizio, puoi utilizzare queste metriche per monitorare il traffico da e verso l'estensione. Per maggiori dettagli, consulta Logging e monitoraggio per i callout di Cloud Load Balancing.

Dashboard di osservabilità

Agent Gateway fornisce una dashboard di osservabilità che ti consente di monitorare, controllare ed eseguire il debug del traffico instradato attraverso i tuoi gateway:

  • Prospetti: monitora il numero totale di tentativi di autorizzazione, errori di autorizzazione e richieste al secondo.
  • Grafici: visualizza le percentuali di errori di autorizzazione (%) e le richieste al secondo nel tempo.
  • Log del traffico in uscita: esamina i log dettagliati per le query in uscita, inclusi i rifiuti di 403, il traffico verso endpoint non registrati e le tendenze generali del traffico.

Per accedere alla dashboard di osservabilità di un gateway nella console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Agent Gateway.

    Vai ad Agent Gateway

  2. Fai clic sul nome del gateway che vuoi monitorare.

  3. Fai clic sulla scheda Osservabilità.

Requisiti dei dati della dashboard

La dashboard di osservabilità di Agent Gateway utilizza Observability Analytics per visualizzare i dati. Se la dashboard non carica i dati, assicurati di eseguire l'upgrade del bucket di log _Default per utilizzare Observability Analytics. La dashboard recupera i dati dalla vista _AllLogs del bucket _Default.

Utilizza Cloud Trace

Agent Gateway si integra con Cloud Trace per fornire l'osservabilità delle richieste end-to-end per i workload degli agenti. Poiché Agent Gateway funge da punto di controllo centrale per gli agenti AI, l'attivazione di Trace ti offre visibilità su come le richieste viaggiano dai tuoi agenti attraverso il gateway e su più servizi, strumenti, agenti e server MCP Google Cloud . Tracciando i flussi di richieste attraverso questi confini di servizio, Trace offre un tracciamento distribuito completo per le tue architetture di agenti.

Con Trace puoi:

  • Esegui il debug delle interazioni degli agenti con precisione: monitora l'intero percorso di una richiesta attraverso i confini dei servizi per isolare i colli di bottiglia della latenza e le chiamate backend non riuscite.
  • Rispetta le decisioni di campionamento upstream: utilizza il campionamento basato sul livello principale per mantenere la continuità delle tracce end-to-end quando gli agenti o i client upstream avviano il tracciamento, assicurandoti che le richieste con priorità elevata vengano acquisite completamente senza aumentare le frequenze di campionamento di base per il traffico di routine.
  • Unifica l'osservabilità con standard aperti: basate sugli standard OpenTelemetry e W3C TraceContext, le tracce propagano senza problemi il contesto tra gli agenti AI, Agent Gateway, i server o gli strumenti MCP di destinazione e le piattaforme di monitoraggio di terze parti.
  • Accelera l'analisi delle cause principali: correla gli intervalli di traccia direttamente con i log e le metriche delle richieste del gateway utilizzando trace_id per risolvere più rapidamente i problemi di produzione.

Per scoprire di più su Trace, consulta la panoramica di Cloud Trace.

Ruoli obbligatori

Devi disporre dei seguenti ruoli IAM (Identity and Access Management) nel tuo progetto:

  • Per configurare e aggiornare una policy di tracciamento: Compute Network Admin (roles/compute.networkAdmin) o Compute Admin (roles/compute.admin)
  • Per visualizzare le tracce nella console Google Cloud : Utente Cloud Trace (roles/cloudtrace.user)

Inoltre, per consentire ad Agent Gateway di scrivere intervalli di traccia in Trace, devi concedere il ruolo Cloud Trace Agent (roles/cloudtrace.agent) ai seguenti service account:

  • Agente di servizio Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Agente di servizio di sicurezza di rete: service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com
  • Service agent Agent Gateway: service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com
  • Account di servizio del workload dell'agente o del client: se l'agente AI o il workload del client chiamante avvia la traccia ed esporta i propri intervalli principali in Trace, al account di servizio del workload o al account di servizio personalizzato collegato all'agente deve essere concesso anche il ruolo roles/cloudtrace.agent nel progetto. In caso contrario, viene scritto solo l'intervallo secondario di Agent Gateway e l'intervallo principale non sarà presente in Trace.

Sostituisci PROJECT_NUMBER con il tuo numero di progetto Google Cloud .

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Abilita il tracciamento

Per abilitare il tracciamento per Agent Gateway, crea un file YAML della policy di osservabilità e importalo utilizzando gcloud CLI.

  1. Crea un file di configurazione denominato 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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto Google Cloud .
    • REGION: la regione del gateway (ad esempio, europe-west1).
    • POLICY_NAME: un nome per la policy di osservabilità (ad esempio my-agw-tracing-policy).
    • AGENT_GATEWAY_NAME: il nome del gateway.
    • SAMPLING_RATE: la frazione di richieste da tracciare. Imposta un valore compreso tra 0.0 e 1.0. Per gli ambienti di produzione con traffico elevato, consigliamo una frequenza dell'1% (0.01) o dello 0,1% (0.001) per bilanciare i costi di osservabilità e importazione.
    • ENABLE_PARENT_BASED_SAMPLING: controlla se rispettare il bit campionato nelle intestazioni traceparent in entrata dai chiamanti upstream. Da impostare su true o false.
    • PARENT_BASED_SAMPLING_RATE: la frazione di richieste pre-campionate da tracciare. Imposta un valore compreso tra 0.0 e 1.0. Ad esempio, 1.0 traccia il 100% delle richieste pre-campionate.

  2. Importa la policy di osservabilità:

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

Visualizza tracce

Dopo aver attivato il tracciamento distribuito e inviato il traffico tramite il gateway, puoi visualizzare i dettagli della traccia nella console Google Cloud :

  1. Nella console Google Cloud , vai alla pagina Esplora tracce:

    Vai a Esplora tracce

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nella barra Filtro, inserisci un'espressione di filtro delle tracce (ad esempio, per filtrare in base alla soglia di latenza, al codice di stato HTTP o all'URI della richiesta) o cerca in base all'ID traccia specifico.

    Per scoprire di più sull'utilizzo della UI di Esplora Trace, consulta Trova ed esplora le tracce.

    Esplora tracce

    Visualizzazione di Esplora tracce in Cloud Trace
    Visualizzazione Esplora tracce in Trace

    Visualizzazione cronologica Trace

    Visualizzazione Timeline in Cloud Trace
    Visualizzazione cronologica in Trace

    Visualizzazione del grafico di Trace

    Visualizzazione grafico in Cloud Trace
    Visualizzazione grafico in Trace

Correlare le tracce con log e metriche

Agent Gateway fornisce una correlazione perfetta tra tracce, log e metriche:

  • Correlazione log-traccia: ogni voce di log delle richieste del gateway scritta in Cloud Logging contiene un campo trace con il formato: projects/PROJECT_ID/traces/TRACE_ID.

    • In Esplora log, fai clic sulla voce di log e poi seleziona Visualizza dettagli della traccia per passare direttamente allo span corrispondente in Trace.
    • In Trace, fai clic su Mostra log nel riquadro Dettagli traccia per visualizzare tutti i log delle richieste del gateway associati alla richiesta.

  • Correlazione delle metriche: confronta i picchi di latenza osservati nelle metriche di Cloud Monitoring, ad esempio networkservices.googleapis.com/agentgateway/total_latencies, con le suddivisioni degli intervalli di traccia per identificare se un picco di latenza si è verificato all'interno del gateway o nello strumento o server di destinazione.

Risoluzione dei problemi

Questa sezione descrive i problemi comuni e le relative soluzioni.

  • Le tracce non vengono visualizzate in Cloud Trace:

    1. Verifica che l'API Cloud Trace (cloudtrace.googleapis.com) sia abilitata nel tuo progetto:

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

    2. Verifica che i ruoli IAM Cloud Trace Agent (roles/cloudtrace.agent) richiesti siano stati concessi a tutti i service account richiesti.

    3. Verifica che la policy di osservabilità esista nella regione corretta e che faccia riferimento al gateway Agent Gateway appropriato:

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

    4. Controlla l'oggetto samplingRate configurato. Se il volume di traffico è basso o la frequenza di campionamento è bassa, le tracce potrebbero non essere acquisite immediatamente. Per verificare che il tracciamento funzioni, puoi aggiornare temporaneamente la policy in modo da utilizzare il campionamento al 100% (samplingRate: 1.00). Ripristina la frequenza di produzione al termine del test.

  • Intervalli di traccia incompleti:

    Se gli intervalli di traccia vengono visualizzati come tracce principali indipendenti o disconnesse anziché come intervalli secondari delle richieste dell'applicazione, segui questi passaggi:

    1. Verifica che parentBasedSampling sia abilitato (impostato su true) nella policy di osservabilità.
    2. Verifica che al account di servizio dell'agente AI o del workload chiamante sia stato concesso il ruolo Cloud Trace Agent (roles/cloudtrace.agent) nel progetto, in modo che gli intervalli principali possano essere esportati in Trace.
    3. Verifica che la tua applicazione utilizzi un SDK OpenTelemetry con la propagazione del contesto di tracciamento distribuito abilitata, in modo che l'intestazione traceparent W3C venga propagata oltre i confini del servizio. Per saperne di più, consulta la documentazione del propagatore TraceContext di OpenTelemetry.

Passaggi successivi

Codelab

Scopri come gestire i workload degli agenti con Agent Gateway su Gemini Enterprise Agent Platform.

Risoluzione dei problemi

Scopri come risolvere i problemi di connettività di Agent Gateway.