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 Agent Gateway viene implementato in modalità di prova.

Visualizzare 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 per 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 sanificazione dei contenuti, questi log vengono emessi separatamente. Per istruzioni su come eseguire query sui log di Model Armor, vedi Visualizzare 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 dell'Agent Gateway.

    • mcpInfo: include informazioni sul metodo MCP della richiesta (ad esempio "tools/list" o "tools/call") e il 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 a Service Extensions, puoi utilizzare queste metriche per monitorare il traffico verso e da Service Extensions. Per maggiori dettagli, vedi Logging e monitoraggio dei 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 tramite i tuoi gateway:

  • Prospetti: monitora il numero totale di tentativi di autorizzazione, gli errori di autorizzazione e le 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 403, il traffico verso endpoint non registrati e le tendenze del traffico complessivo.

Per accedere alla dashboard di osservabilità per un gateway nella console Google Cloud :

  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 _Default _AllLogs visualizzazione del bucket.

Utilizzare Cloud Trace

Agent Gateway si integra con Cloud Trace per fornire l'osservabilità delle richieste end-to-end per i carichi di lavoro degli agenti. Poiché Agent Gateway funge da punto di controllo centrale per gli agenti AI, l'attivazione di Trace ti consente di visualizzare il percorso delle richieste dai tuoi agenti tramite il gateway e su più servizi, Google Cloud strumenti, agenti e server MCP. Monitorando i flussi di richieste oltre questi limiti di servizio, Trace fornisce una tracciabilità distribuita completa per le architetture degli agenti.

Utilizzando 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 di backend non riuscite.
  • Rispetta le decisioni di campionamento upstream: utilizza il campionamento basato sul parent per mantenere la continuità della traccia end-to-end quando gli agenti o i client upstream avviano la tracciatura, garantendo che le richieste ad alta priorità vengano acquisite completamente senza aumentare i tassi 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.
  • Accelerare l'analisi della causa principale: correla gli intervalli di traccia direttamente con i log e le metriche delle richieste del gateway utilizzando trace_id per risolvere i problemi di produzione più rapidamente.

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

Ruoli obbligatori

Devi disporre dei seguenti ruoli Identity and Access Management (IAM) 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 gli intervalli di traccia in Trace, devi concedere il ruolo Agente Cloud Trace (roles/cloudtrace.agent) ai seguenti service account:

  • Service agent Compute Engine: service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com
  • Service agent per la 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 carico di lavoro dell'agente o del client: se il carico di lavoro dell'agente AI o del client chiamante avvia la traccia ed esporta i propri intervalli principali in Trace, anche al account di servizio del carico di lavoro o al account di servizio personalizzato collegato all'agente deve essere concesso il ruolo roles/cloudtrace.agent nel progetto. In caso contrario, viene scritto solo lo span secondario di Agent Gateway e lo span principale non sarà presente in Trace.

Sostituisci PROJECT_NUMBER con il numero del tuo progetto Google Cloud .

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

Abilita il tracciamento

Per attivare la tracciabilità 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"
targetTelemetry:
  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 l'osservabilità e i costi di importazione.
    • ENABLE_PARENT_BASED_SAMPLING: controlla se rispettare il bit campionato nelle intestazioni traceparent in entrata dei 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 la tracciabilità distribuita 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 di traccia (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, vedi Trovare ed esplorare le tracce.

    Esplora tracce

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

    Visualizzazione cronologica Trace

    Visualizzazione Timeline in Cloud Trace
    Visualizzazione cronologica in Trace

    Visualizzazione grafico Trace

    Visualizzazione a grafico in Cloud Trace
    Visualizzazione del grafico in Trace

Correlare le tracce con log e metriche

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

  • Correlazione log-trace: 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 traccia per passare direttamente all'intervallo corrispondente in Trace.
    • In Trace, fai clic su Mostra log nel riquadro Dettagli traccia per visualizzare tutti i log delle richieste del gateway associati a quella 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 si è verificato un picco di latenza all'interno del gateway o nello strumento o nel 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 a tutti gli account di servizio richiesti siano stati concessi i ruoli IAM Cloud Trace Agent (roles/cloudtrace.agent) 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 il samplingRate configurato. Se il volume di traffico è basso o la frequenza di campionamento è bassa, le tracce potrebbero non essere acquisite immediatamente. Per verificare che la tracciabilità funzioni, puoi aggiornare temporaneamente le norme in modo da utilizzare il campionamento al 100% (samplingRate: 1.00). Ripristina la frequenza di produzione al termine del test.

  • Span della traccia incompleti:

    Se gli intervalli di traccia vengono visualizzati come tracce radice indipendenti o disconnesse anziché come intervalli secondari delle richieste dell'applicazione, procedi nel seguente modo:

    1. Verifica che parentBasedSampling sia attivato (impostato su true) nel criterio 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 span 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 tra i limiti del servizio. Per saperne di più, consulta la documentazione del propagatore TraceContext di OpenTelemetry.

Passaggi successivi

Codelab

Scopri come gestire i carichi di lavoro agentici con Agent Gateway su Gemini Enterprise Agent Platform.

Risoluzione dei problemi

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