Trovare ed esplorare le tracce

La pagina Esplora trace consente di visualizzare le tendenze della latenza aggregata, filtrare i dati di Cloud Trace e analizzare singoli trace e span per risolvere i problemi relativi a colli di bottiglia delle prestazioni ed errori. Per impostazione predefinita, la pagina Esplora tracce esegue query sui dati di traccia archiviati nel datastore del progettoGoogle Cloud . Tuttavia, puoi configurare la pagina per eseguire query sui dati di traccia archiviati in più progetti.

Per eseguire un'analisi aggregata personalizzata degli span utilizzando SQL, utilizza la pagina Observability Analytics o BigQuery. Quando utilizzi la pagina Observability Analytics, puoi visualizzare i risultati della query come tabella o come grafico. Per informazioni sull'utilizzo di SQL per eseguire query sui dati di traccia, consulta Eseguire query e analizzare le tracce.

Informazioni sulla pagina Esplora tracce

Per aiutarti a identificare tendenze e pattern nei dati di traccia, i dati di latenza vengono aggregati e visualizzati nei grafici. La mappa termica utilizza il colore per rappresentare il numero di intervalli in una cella. Una cella con molti intervalli ha un colore più scuro di una con pochi intervalli. La descrizione comando di ogni cella mostra la latenza e altre informazioni. Puoi anche visualizzare i percentili di latenza e le informazioni sul tasso di intervallo.

Lo screenshot seguente illustra come vengono mostrati i dati di traccia:

Esempio di visualizzazione dei dati di traccia.

Quando esamini un problema, potresti voler visualizzare una traccia specifica o solo gli intervalli con determinate proprietà:

  • Per limitare gli intervalli visualizzati, applica filtri. Ad esempio, puoi filtrare per servizio, applicazione, stato di errore e altre proprietà.

  • Per visualizzare una traccia specifica, utilizza l'opzione pageview della barra degli strumenti.

Per identificare gli outlier e visualizzare i dettagli dei singoli intervalli, utilizza la sezione tabulare:

  • Puoi ordinare le righe delle schede Intervalli e Raggruppati in base all'intestazione Durata.

  • Per capire quanti intervalli vengono generati dai diversi servizi, utilizza la scheda Raggruppati. Ogni riga corrisponde a un nome di servizio e intervallo e, per ogni voce, vengono mostrate le statistiche di latenza.

Per esplorare i dettagli di un intervallo o di un raggruppamento, seleziona la voce da una riga nella sezione tabellare. Si apre un riquadro a scomparsa che mostra lo span nel contesto della sua traccia. Da questa visualizzazione puoi esplorare lo span, i relativi attributi e visualizzare gli eventi e i dati dei log. Puoi anche cercare parole chiave negli intervalli e negli attributi della traccia.

I dati di traccia visualizzati nella pagina Esplora tracce dipendono da quanto segue:

  • L'impostazione Ambito, che determina in quali viste il sistema cerca i dati di traccia. Quando si apre la pagina, l'elemento Ambito viene impostato sull'ambito della traccia predefinito e il sistema esegue query sulle visualizzazioni elencate in quell'ambito per i dati di traccia.

    In un nuovo progetto, l'ambito di traccia predefinito elenca la vista _AllSpans per il progetto. Questa visualizzazione fornisce l'accesso in lettura a tutti i dati di traccia archiviati dal progetto.

    Puoi creare ambiti di traccia che ti consentono di eseguire query sui dati archiviati in più progetti. Per saperne di più, consulta Visualizzare le tracce in più progetti.

  • Le tue autorizzazioni Identity and Access Management (IAM) sulla visualizzazione cercata. Se non hai l'autorizzazione per visualizzare i dati di traccia per un progetto, la console Google Cloud mostra un messaggio di avviso e i dati di quel progetto non vengono visualizzati.

  • L'impostazione dell'intervallo di tempo.

  • I filtri che applichi.

Puoi salvare i dati di traccia in una dashboard personalizzata. Per saperne di più, consulta Visualizza i dati di traccia su una dashboard personalizzata.

Il resto di questa pagina fornisce ulteriori informazioni su come trovare ed esplorare i dati di traccia.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per visualizzare i dati di traccia utilizzando la console Google Cloud e per selezionare un ambito di traccia, chiedi all'amministratore di concederti il ruolo IAM Cloud Trace User (roles/cloudtrace.user) sul progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questo ruolo predefinito contiene le autorizzazioni necessarie per visualizzare i dati di traccia utilizzando la console Google Cloud e per selezionare un ambito di traccia. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per visualizzare i dati di traccia utilizzando la console Google Cloud e per selezionare un ambito di traccia sono necessarie le seguenti autorizzazioni:

  • Per selezionare un ambito di traccia: cloudtrace.traceScopes.[get, list]
  • Per leggere l'ambito della traccia predefinito: observability.scopes.get

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più sui ruoli, consulta Controllare l'accesso con Identity and Access Management.

Visualizzare i dati di traccia aggregati

Per visualizzare i dati aggregati sulle tracce, procedi come segue:

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

    Vai a Esplora tracce

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

    Potrebbero essere necessari diversi minuti dopo la scrittura dei primi dati di traccia in un progetto Google Cloud prima che questi dati siano disponibili per la visualizzazione. Se dopo aver atteso qualche minuto non visualizzi dati di traccia, è possibile che il tuo progetto non abbia dati da visualizzare o che si sia verificato un problema di configurazione. Per informazioni su come risolvere questi problemi, consulta Risoluzione dei problemi: nessun dato nell'interfaccia di Trace.

  2. Configura la pagina Esplora tracce:

    1. Nella barra degli strumenti della console Google Cloud , seleziona il tuo progetto Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione.

    2. (Facoltativo) Configura le visualizzazioni in cui il sistema cerca i dati di traccia utilizzando l'elemento Scope:

      • Per mostrare i dati di traccia archiviati dal tuo progetto, imposta il primo menu dell'elemento Ambito su Progetto o su _Default. Queste due impostazioni sono equivalenti.

      • Per visualizzare i dati di traccia archiviati da più progetti, espandi il primo menu dell'elemento Ambito, seleziona Ambito traccia, quindi seleziona l'ambito traccia che elenca la visualizzazione _AllSpans per questi progetti. Dopo aver effettuato la selezione, nel menu Ambito viene visualizzata un'icona dell'ambito della traccia, , e il nome dell'ambito della traccia selezionato.

      I dati visualizzati dal sistema dipendono dai tuoi ruoli IAM nelle visualizzazioni cercate. Ad esempio, se non disponi delle autorizzazioni necessarie per visualizzare i dati in una vista, il sistema non li mostrerà.

      Per saperne di più, consulta Crea e gestisci gli ambiti di traccia.

    3. (Facoltativo) Aggiorna l'intervallo di tempo utilizzando il selettore dell'intervallo di tempo o il puntatore per evidenziare un intervallo sull'asse X.

      Ad esempio, puoi impostare questo selettore su Ultime 2 settimane per vedere se esistono tendenze nei dati sulla latenza. I dati degli intervalli vengono archiviati per 30 giorni.

  3. Esplora la mappa termica:

    • Utilizza il colore per identificare tendenze e outlier. Una cella con molti intervalli ha un colore più scuro rispetto a una con pochi intervalli.

    • Visualizza i dettagli della cella utilizzando la descrizione comando della cella. La descrizione comando elenca il numero di intervalli, la data e l'ora e l'intervallo di tempo della cella.

  4. Esplora i percentili di latenza e i tassi di errore:

    • Per visualizzare le tendenze della latenza, imposta il menu Visualizzazione grafico su Durata span (percentile). Il grafico della durata mostra il 50°, 90°, 95° e 99° percentile.

    • Per visualizzare lo stato della risposta in funzione del tempo, imposta il menu Visualizzazione grafico su Frequenza di intervallo. Il grafico mostra la velocità di invio degli span al tuo progetto.

  5. Utilizza le tabelle Intervalli e Raggruppati per identificare i valori anomali o per visualizzare informazioni statistiche. La tabella Intervalli elenca i singoli intervalli. La tabella Raggruppati raggruppa gli intervalli in base al nome e al nome del servizio o del workload.

    • Per visualizzare i valori anomali o trovare il nome di uno span, ordina la tabella. Puoi ordinare in base a qualsiasi intestazione di colonna.

      Ad esempio, l'ordinamento della tabella Intervalli in base alla durata consente di trovare intervalli con latenza elevata.

    • Per visualizzare statistiche come la latenza media, utilizza la tabella Raggruppati.

    • Per trovare servizi e workload registrati in App Hub, cerca nella colonna Servizio/workload le voci che includono l'icona del servizio, , o l'icona del workload, . Il link fornito con un servizio o un workload registrato in App Hub apre la dashboard di monitoraggio delle applicazioni corrispondente.

    Se vuoi saperne di più su un raggruppamento specifico, seleziona il nome dello span per una riga. Viene visualizzato un riquadro extra che mostra l'intervallo nel contesto della sua traccia. A questo punto, puoi esplorare lo span e la traccia.

  6. Per limitare gli intervalli visualizzati, aggiungi filtri. Per informazioni su come filtrare i dati di traccia, consulta la sezione successiva.

Filtrare i dati di traccia

Per visualizzare solo le informazioni che ti interessano, applica i filtri. I filtri limitano i dati visualizzati. Ad esempio, puoi filtrare per nome del servizio e per stato. In alternativa, se hai eseguito il deployment di applicazioni in App Hub, potresti voler visualizzare i dati di traccia solo per l'applicazione o per un servizio o un workload specifico che fa parte dell'applicazione.

Quando aggiungi o rimuovi un filtro, i dati visualizzati dalla pagina Trace Explorer vengono aggiornati e mostrano solo gli span che corrispondono a tutti i filtri applicati.

Filtra per ID traccia

Quando risolvi un problema o un errore, potresti conoscere l'ID traccia. Per esplorare la traccia, vai alla barra degli strumenti, fai clic su visualizzazione di pagina e inserisci l'ID traccia.

Quando inserisci un ID valido, si apre il riquadro Dettagli e vengono visualizzate le informazioni sulla traccia e sui relativi intervalli. Puoi utilizzare le opzioni in questo riquadro per esplorare la traccia. Ad esempio, potresti cercare parole chiave negli intervalli.

Se inserisci un ID traccia che non viene trovato, i dati di traccia potrebbero essere archiviati in una vista non cercata dalla pagina Esplora tracce oppure potresti non avere un ruolo IAM che ti consente di visualizzare i dati di traccia. Per risolvere questi errori, identifica i progetti che memorizzano i dati di traccia. Per ogni progetto, verifica che il tuo ruolo IAM ti consenta di visualizzare i dati di traccia, quindi assicurati che l'elemento Ambito elenchi la visualizzazione predefinita del progetto per i dati di traccia. Per saperne di più, consulta Configurare le viste in cui viene eseguita la ricerca in Esplora tracce.

Applica filtri di intervallo

Il riquadro Filtri span elenca i filtri più comuni. Puoi selezionare più voci da qualsiasi sottocategoria. Man mano che aggiungi o rimuovi i filtri, viene aggiornata anche la barra Filtro.

I valori di tutti i menu derivano dai dati di traccia. Quando un menu include un'opzione senza testo, questa si riferisce agli intervalli che non includono l'attributo corrispondente.

In genere sono disponibili i seguenti filtri per gli intervalli:

  • Servizio OpenTelemetry: filtra in base all'attributo service.name.
  • Nome intervallo: il nome dell'intervallo.
  • Stato inclusivo: lo stato della richiesta. Per informazioni sui valori, consulta la documentazione di OpenTelemetry SpanStatus.
  • Durata: la durata dello span.
  • Tipo di intervallo: descrive le relazioni tra gli intervalli. Per informazioni sui valori, consulta la documentazione di OpenTelemetry SpanKind.
  • Applicazione App Hub: filtra in base all'attributo della risorsa gcp.apphub.application.id.
  • Servizio App Hub: filtra in base all'attributo risorsa gcp.apphub.service.id.
  • Workload App Hub: filtra in base all'attributo della risorsa gcp.apphub.workload.id.

Se vuoi filtrare in base a un attributo non elencato nel riquadro Filtri intervallo, utilizza la barra Filtro.

Utilizza la barra dei filtri

La barra Filtro consente di applicare un filtro con una chiave di filtro predefinita e un valore selezionato oppure di inserire sia la chiave sia il valore.

Per aggiungere un filtro, seleziona Aggiungi filtro e poi esegui una delle seguenti operazioni:

  • Seleziona una chiave definita, ad esempio Nome span, quindi seleziona un valore dal menu secondario.

  • Seleziona Aggiungi filtro attributo e poi aggiungi la chiave e il valore personalizzati. Se inserisci la tua chiave di filtro, utilizza la stessa sintassi di una chiave per un attributo in uno span.

    Ad esempio, per filtrare in base all'identificatore host, imposta la chiave su host.id. Analogamente, per filtrare in base al codice di stato, imposta la chiave su /http/status_code. In questo scenario, puoi impostare il valore su 200, il che genera il filtro /http/status_code: 200. Per fare in modo che il filtro corrisponda a qualsiasi valore, seleziona Qualsiasi valore.

Filtra per applicazione

Puoi filtrare i dati di traccia in base a un'applicazione, un workload o un servizio App Hub, se i dati contengono i seguenti attributi delle risorse:

  • gcp.apphub.application.{container,id,location}
  • gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

Questi attributi delle risorse vengono generati dalla strumentazione che aggiungi alle tue applicazioni.

Nella pagina Esplora tracce, utilizza i seguenti menu Filtri span per limitare gli intervalli in base ad applicazione, servizio o workload:

  • Applicazione App Hub
  • Servizio App Hub
  • Workload App Hub

Per aprire la dashboard di Application Monitoring per un servizio e un workload registrati in App Hub:

  1. Vai alla tabella Intervalli o Raggruppati e individua il servizio o il workload. Puoi cercare l'icona del servizio, , l'icona del workload, , o filtrare la tabella.

  2. Seleziona il link nella colonna Servizio/workload.

Esplorare una traccia

Per esplorare uno span nel contesto della sua traccia:

  1. Apri e configura la pagina Esplora tracce. Per informazioni su questi passaggi, consulta Visualizza i dati di traccia aggregati.

  2. Per visualizzare i dettagli di uno span o di una traccia, esegui una delle seguenti operazioni:

    • Vai alla pagina Esplora tracce e seleziona una voce dalla tabella. Puoi ordinare le righe delle tabelle in base a qualsiasi intestazione. Puoi applicare filtri per limitare gli intervalli mostrati nelle tabelle.

    • Vai alla barra degli strumenti della pagina Trace Explorer, fai clic su ID traccia e inserisci l'ID traccia.

      Viene visualizzato il riquadro di uscita Dettagli, che mostra una traccia e i relativi intervalli in un formato di sequenza temporale, nonché informazioni sull'intervallo selezionato:

      Esempio del riquadro a comparsa della traccia.

      Il menu a comparsa contiene uno schermo diviso. Un lato mostra lo span nel contesto della sua traccia. L'altro lato mostra schede che consentono di visualizzare informazioni specifiche dell'intervallo, come attributi, metadati e prompt e risposte allegati. Per informazioni su queste schede, consulta Visualizza attributi, voci di log ed eventi.

      Gli elementi della sequenza temporale sono dinamici. Seleziona uno span per visualizzarne attributi, voci di log ed eventi.

Esplora la gerarchia delle chiamate

Per impostazione predefinita, la gerarchia delle chiamate viene visualizzata come sequenza temporale. La prima voce rappresenta la traccia e ogni voce successiva rappresenta un intervallo. Ogni voce mostra quanto segue:

  • La colonna Nome mostra un nome e un ID intervallo o traccia. Un'icona di GenAI, , indica che uno span include eventi o attributi di AI generativa.
  • La colonna Servizio/workload mostra il nome di un servizio o di un workload. Il sistema imposta questo valore utilizzando l'attributo OpenTelemetry service.name. Come fallback, per i servizi App Engine, il sistema visualizza il nome del servizio App Engine.
  • Il colore e la lunghezza della barra della latenza riflettono lo stato e la durata del comando.
  • Un cerchio su una barra di latenza indica che una voce di log o un evento è associato allo span. Per modificare questo comportamento, utilizza il menu Log ed eventi.

Per visualizzare la gerarchia delle chiamate come grafo diretto aciclico (DAG), seleziona Grafo nella barra degli strumenti:

Trace che mostra un grafo diretto aciclico.

Nella visualizzazione DAG, il nome e la latenza vengono visualizzati con ogni elemento. Il colore riflette lo stato dell'intervallo. Puoi utilizzare la rotellina di scorrimento del puntatore per modificare le dimensioni del grafico.

Cerca gli intervalli in una traccia

Per cercare parole chiave negli intervalli della traccia, utilizza il campo Trova nella traccia.

La ricerca si applica solo ai campi del nome dello span, del nome del servizio o del workload e degli attributi. Puoi eseguire ricerche solo in base al testo normale e non puoi cercare log, eventi o metadati.

Ad esempio, se inserisci GET, viene evidenziata qualsiasi corrispondenza senza distinzione tra maiuscole e minuscole per GET nei campi Nome, Servizio/carico di lavoro e Attributi.

Visualizzare attributi, voci di log ed eventi

Il riquadro extra Dettagli per un intervallo contiene una scheda per ciascuno dei seguenti elementi:

  • Input/Output: mostra gli eventi che seguono le convenzioni semantiche di OpenTelemetry GenAI. Questa scheda viene visualizzata solo quando l'intervallo contiene questi eventi. Per aiutarti a identificare questi intervalli, la visualizzazione cronologica mostra un'icona GenAI, , con il nome dell'intervallo, quando l'intervallo contiene eventi o attributi che seguono queste convenzioni. Per saperne di più, consulta Visualizza gli eventi e gli attributi dell'AI generativa.

  • Attributi: elenca gli attributi associati agli intervalli. Trace Explorer indica quali span contengono attributi di AI generativa visualizzando un'icona GenAI, . Per informazioni sulle etichette, consulta Etichette di Trace.

  • Log ed eventi: questa scheda elenca gli eventi e le voci di log i cui campi trace_id e span_id corrispondono all'intervallo selezionato. Vengono visualizzate solo le voci di log per le quali disponi dell'autorizzazione di visualizzazione.

    Per esplorare una voce in questa scheda, fai clic su Mostra altro.

    Se preferisci utilizzare la pagina Esplora log per visualizzare i dati dei log, fai clic su Visualizza i log. La query è impostata per filtrare in base a una traccia, uno span e un intervallo di tempo specifici.

  • Analisi dello stack: elenca le analisi dello stack disponibili.

  • Metadati e link: elenca informazioni generali, informazioni sull'ambito della strumentazione e link allo schema.

    La sezione Metadati mostra informazioni quali:

    • ID intervallo: l'ID intervallo è un numero intero a 64 bit diverso da 0. Per maggiori dettagli, vedi TraceSpan.
    • ID span padre.
    • ID progetto.
    • Ora di inizio e ora di fine.

    • Tabella che elenca i link ad altri intervalli. Per ogni link, questa tabella elenca quanto segue:

      • Le coppie chiave-valore per l'intervallo a cui è stato creato il link.
      • L'ID traccia per lo span collegato. Quando questo campo elenca Traccia corrente, lo span è collegato a un altro span nella stessa traccia.

      Per informazioni sui link, consulta la pagina di riferimento dell'API Links.

    Le sezioni Ambito di strumentazione e Informazioni sullo schema mostrano il nome e la versione dell'ambito e forniscono link allo schema. Queste sezioni vengono omesse quando un intervallo non contiene queste informazioni.

Il menu a comparsa Dettagli potrebbe includere anche una scheda denominata Input/Output. Questa scheda mostra gli eventi di AI generativa.

Visualizza gli eventi di AI generativa

Per identificare gli intervalli che contengono attributi o eventi coerenti con le convenzioni semantiche di OpenTelemetry per l'AI generativa, cerca l'icona GenAI, :

  • La scheda Attributi mostra gli attributi associati allo span. Per elencare solo gli attributi di AI generativa, attiva Solo attributi di AI generativa.

  • La scheda Input/Output mostra gli eventi che seguono queste convenzioni e gli attributi associati, che vengono visualizzati anche nella scheda Attributi. Sono supportate due configurazioni:

    • Prompt e risposte basati su testo allegati agli intervalli come attributi, ovvero coppie chiave-valore che descrivono una caratteristica o un evento. Ad esempio, il valore della chiave gen_ai.system identifica il sistema che fornisce le funzionalità di AI generativa. Le chiavi per gli attributi dell'AI generativa iniziano con gen_ai.

    • Prompt e risposte multimodali archiviati in un bucket Cloud Storage. Cloud Trace identifica questi eventi mettendo in correlazione i dati di traccia e di log. Per informazioni sulle configurazioni supportate, consulta Raccogliere e visualizzare prompt e risposte multimodali.

      Lo screenshot seguente mostra come il Input/Output esegue il rendering degli eventi di AI generativa basati su testo allegati agli span:

      Eventi di AI generativa basati su testo in Esplora tracce.

      Per informazioni sull'applicazione di esempio che ha generato lo screenshot precedente, vedi Instrumenta un agente LangGraph ReAct con OpenTelemetry.

Visualizza le chiamate ai server MCP remoti

Per visualizzare gli intervalli generati dai server MCP, esegui una delle seguenti operazioni:

  • Filtra i dati di traccia in base al nome dello span.

  • Aggiungi un filtro degli attributi la cui chiave è mcp.method.name e il cui valore è tools/call.

    Questo filtro è specifico per la ricerca di intervalli il cui nome segue le convenzioni semantiche di OpenTelemetry per MCP. Il nome è simile al seguente:

    tools/call NAME

    Nell'espressione precedente, NAME si riferisce all'endpoint richiamato. Ad esempio, potrebbe essere simile a roll_dice.

Per informazioni sui server MCP di Google Cloud che generano tracce e su come configurare l'applicazione per indicare ai server MCP di generare intervalli, consulta Esamina le chiamate MCP utilizzando Trace.

Passaggi successivi