Trovare ed esplorare le tracce

Per visualizzare una rappresentazione aggregata dei dati delle tracce o per trovare ed esplorare singole tracce o tracce contenenti etichette specifiche, utilizza la pagina Esplora tracce.

Questa funzionalità è supportata solo per i progetti Google Cloud.

Informazioni sulla pagina Esplora tracce

Per aiutarti a identificare tendenze e pattern nei dati delle tracce, i dati sulla latenza vengono aggregati e visualizzati nei grafici. La mappa termica, che è la visualizzazione predefinita, utilizza il colore per rappresentare il numero di intervalli in una cella. Una cella con molti intervalli viene visualizzata con un colore più scuro rispetto a una cella con pochi intervalli. Puoi selezionare una cella o attivare la relativa descrizione comando per visualizzare ulteriori informazioni. Le altre visualizzazioni ti consentono di visualizzare la latenza come percentile e informazioni sulla frequenza di intervallo. Per tutte le visualizzazioni, puoi utilizzare il cursore per espandere l'asse X. Per i grafici a linee, puoi espandere gli assi x e y.

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

  • Quando conosci l'ID di una traccia, nella barra degli strumenti, fai clic su Cerca traccia e poi inserisci l'ID traccia nella finestra di dialogo. Successivamente, puoi cercare le parole chiave negli intervalli e negli attributi della traccia .

  • Quando visualizzi i dati aggregati, puoi cercare intervalli specifici applicando filtri. Ad esempio, puoi filtrare i dati per visualizzare solo gli intervalli relativi a un servizio specifico. Successivamente, puoi aggiungere un secondo filtro che limiti la visualizzazione agli intervalli per un servizio specifico che genera un errore.

I dati tabulari ti consentono di visualizzare i dettagli dei singoli intervalli e ti aiutano a identificare gli outlier. Ad esempio, per trovare l'intervallo con il valore di latenza più elevato, seleziona la scheda Intervalli e poi ordina i dati in base alla latenza. Per trovare i servizi che generano errori, filtra i dati in base allo stato dell'intervallo e seleziona la scheda Raggruppati, che mostra i dati aggregati per intervallo e nome del servizio. Ogni riga della tabella contiene un link a informazioni dettagliate.

I dati di traccia mostrati dalla pagina Esplora tracce dipendono da quanto segue:

  • I progetti in cui è stata eseguita la ricerca dei dati di traccia. Per impostazione predefinita, viene eseguita la ricerca dei dati di traccia solo nel progetto selezionato dal selettore di progetti. Tuttavia, puoi configurare la pagina in modo che esegua la ricerca nell'elenco dei progetti in un ambito della traccia.
  • Le tue autorizzazioni IAM (Gestione di identità e accessi) per i progetti cercati. Se non disponi dell'autorizzazione per visualizzare i dati delle tracce di un progetto, la console Google Cloud mostra un messaggio di avviso e i dati del progetto non vengono visualizzati.
  • L'impostazione dell'intervallo di tempo.
  • I filtri che applichi.

La parte rimanente di questa pagina fornisce ulteriori informazioni su come trovare ed esplorare i dati delle tracce.

Prima di iniziare

Per ottenere le autorizzazioni necessarie per visualizzare i dati delle tracce utilizzando la console Google Cloud e per selezionare o meno un ambito di traccia, chiedi all'amministratore di concederti il ruolo IAM Utente Cloud Trace (roles/cloudtrace.user) nel tuo progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire 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 o specificare l'ambito di una traccia. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per visualizzare i dati delle tracce utilizzando la console Google Cloud e per selezionare o specificare l'ambito di una traccia, sono necessarie le seguenti autorizzazioni:

  • Per selezionare l'ambito di una 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 ulteriori informazioni sui ruoli, consulta Controllare l'accesso con Identity and Access Management.

Visualizzare i dati aggregati delle tracce

Per visualizzare le informazioni aggregate sui dati di traccia:

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

    Vai a Trace Explorer

    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 traccia, il progetto potrebbe non avere dati da visualizzare o potrebbe esserci un problema di configurazione. Per informazioni su come risolvere questi problemi, consulta Risoluzione dei problemi: nessun dato nell'interfaccia di traccia.

  2. Nella barra degli strumenti della console Google Cloud, seleziona il tuo progetto Google Cloud.

  3. (Facoltativo) Configura i progetti in cui vengono cercati i dati traccia utilizzando l'elemento Ambito:

    • Per visualizzare i dati traccia memorizzati nel progetto, imposta il primo menu dell'elemento Ambito su Progetto o su _Predefinito. Queste due impostazioni sono equivalenti.

    • Per visualizzare i dati di traccia archiviati in più progetti, espandi il primo menu dell'elemento Ambito, seleziona Ambito traccia e poi l'ambito traccia che elenca i progetti. Dopo aver effettuato la selezione, il menu Ambito mostra un'icona di ambito traccia, , e il nome dell'ambito traccia selezionato.

    I dati restituiti dipendono dai tuoi ruoli IAM nei progetti cercati. Ad esempio, se i progetti sottoposti a ricerca includono un progetto Google Cloud a cui non hai accesso, non vengono restituiti dati di traccia per quel progetto.

    Per saperne di più, consulta Creare e gestire gli ambiti di traccia.

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

  5. Esplora i grafici, che mostrano schemi e tendenze nei dati traccia:

    • Per informazioni sui dati sulla latenza dell'intervallo, imposta il menu Visualizzazione del grafico su Durata intervallo (mappa termica). L'intensità del colore è proporzionale al numero di tratti. Per informazioni su una cella, utilizza il cursore. La descrizione comando mostra il numero di intervalli, la data e l'ora e l'intervallo di tempo della cella.

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

    • Per visualizzare lo stato della risposta in funzione del tempo, imposta il menu Visualizzazione grafico su Frequenza di scansione. Il grafico mostra la frequenza degli intervalli inviati al progetto.

  6. Esplora i dati tabulari che elencano i singoli intervalli nella scheda Intervalli e gli intervalli raggruppati per servizio e nome nella scheda Raggruppati.

    Ogni riga delle tabelle mostra un intervallo o un raggruppamento, insieme a un link a informazioni dettagliate e ad alcune metriche. Ad esempio, nella scheda Raggruppati, le metriche includono il tasso di errore e il numero di intervalli nel gruppo.

    Per trovare gli outlier, seleziona un'intestazione di colonna per ordinare la tabella.

  7. Aggiungi filtri per limitare gli intervalli visualizzati. Ad esempio, potresti filtrare per nome del servizio e stato. Quando aggiungi o rimuovi un filtro, i dati visualizzati dalla pagina Trace Explorer vengono aggiornati e vengono mostrati solo gli intervalli corrispondenti a tutti i filtri applicati.

    Per modificare le impostazioni del filtro, svolgi una delle seguenti operazioni:

    • Vai al riquadro Filtri intervallo e seleziona i filtri da applicare.

      Il riquadro Filtri intervallo elenca solo i filtri più comuni. Se vuoi filtrare in base a un attributo non elencato, utilizza la barra Filtro.

    • Per aggiungere un filtro utilizzando la barra Filtro, seleziona Aggiungi filtro e completa la finestra di dialogo.

      Per filtrare in base a un attributo non elencato nel menu delle opzioni, selezionate Aggiungi filtro attributo e aggiungete la chiave e il valore personalizzati. Ad esempio, se imposti la chiave su /http/status_code e il valore su 200, il filtro è /http/status_code: 200. Per consentire al filtro di corrispondere a qualsiasi valore, seleziona Qualsiasi valore.

Trovare una traccia per ID

Quando stai risolvendo un incidente o un errore, potresti conoscere l'ID traccia. Per esplorare la traccia:

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

    Vai a Trace Explorer

    Puoi trovare questa pagina anche utilizzando la barra di ricerca.

  2. Nella barra degli strumenti della console Google Cloud, seleziona il tuo progetto Google Cloud.

  3. Vai alla barra degli strumenti, fai clic su Cerca traccia e inserisci l'ID traccia.

    Quando inserisci un ID valido, si apre il menu a comparsa Dettagli, che mostra informazioni sulla traccia e sui relativi intervalli. Puoi utilizzare le opzioni in questo pannello per esplorare la traccia. Ad esempio, potresti cercare parole chiave negli intervalli.

Esplorare una traccia

Per visualizzare una traccia o uno span:

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

    Vai a Trace Explorer

    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 traccia, il progetto potrebbe non avere dati da visualizzare o potrebbe esserci un problema di configurazione. Per informazioni su come risolvere questi problemi, consulta Risoluzione dei problemi: nessun dato nell'interfaccia di traccia.

  2. Nella barra degli strumenti della console Google Cloud, seleziona il tuo progetto Google Cloud.

  3. Esegui una di queste operazioni:

    • Vai alla sezione della tabella della pagina Trace Explorer e seleziona una voce della tabella che elenca gli span o elenca informazioni di riepilogo dopo aver raggruppato i dati per nome del servizio e dello span.

    • Vai alla barra degli strumenti della pagina Esplora tracce, fai clic su Cerca traccia, e inserisci l'ID traccia.

    Si apre il popup Dettagli, che mostra una traccia e i relativi intervalli:

    • La colonna Nome mostra la gerarchia delle chiamate e la prima voce include l'ID traccia.
    • La colonna Servizio viene estratta dall'attributo OpenTelemetry service.name, se impostato. Se questo attributo non è impostato e se il servizio è in esecuzione su App Engine, viene visualizzato il nome del servizio App Engine. In caso contrario, non viene specificato alcun servizio.
    • La lunghezza della barra della latenza è rappresentativa del valore della latenza.
    • Il colore della barra della latenza indica lo stato. Una barra di latenza blu indica un completamento riuscito, mentre una barra di latenza rossa indica che si è verificato un errore.
    • Un cerchio su una barra di latenza indica che un evento o una voce di log è associata all'intervallo. Per modificare questo comportamento, utilizza il menu Log ed eventi.

  4. (Facoltativo) Cerca il nome dell'intervallo, il nome del servizio e gli attributi in una traccia utilizzando il campo Trova nella traccia.

    Ad esempio, se inserisci GET, il testo nel nome dello spazio, nel nome del servizio o nel riquadro Attributi che mostra GET, ignorando le maiuscole, viene evidenziato.

    Non puoi eseguire ricerche utilizzando un'espressione regolare e non puoi cercare log, eventi o metadati.

  5. Per visualizzare i dettagli di un intervallo specifico, selezionalo e visualizzane gli attributi e gli eventi. Per ulteriori informazioni, consulta la sezione successiva.

Visualizza attributi ed eventi

Questa sezione descrive come visualizzare etichette, log ed eventi.

Visualizza etichette

Per visualizzare le etichette associate all'intervallo, vai alla scheda Attributi. Per informazioni sulle etichette, vedi Etichette traccia.

Visualizza log ed eventi

Per visualizzare i log e gli eventi correlati all'intervallo, vai alla scheda Log ed eventi. Per informazioni sulle annotazioni degli eventi, consulta Annotare gli intervalli di traccia.

Per visualizzare una voce di log, fai clic su Mostra altro.

Puoi anche selezionare il pulsante Visualizza log, che apre la pagina Esplora log con la query impostata per filtrare in base a una traccia, un intervallo e un intervallo di tempo specifici. Questa query potrebbe non restituire voci di log.

Visualizzare gli eventi di IA generativa

Per visualizzare gli eventi relativi agli agenti di IA generativa, utilizza la scheda GenAI. Questa scheda è disponibile quando gli span inviati a Trace rispettano le Convenzioni semantiche di OpenTelemetry per i sistemi di IA generativa, con messaggi i cui nomi iniziano con gen_ai.

Gli attributi sono coppie chiave-valore che descrivono una caratteristica. Di seguito sono riportati alcuni esempi di attributi di un sistema di IA generativa:

  • gen_ai.system: identifica il sistema che fornisce le funzionalità di IA generativa.
  • gen_ai.request.model: identifica il modello a cui viene inviata la richiesta.

Gli eventi il cui nome inizia con "gen_ai" in genere descrivono singoli input o output di un sistema di IA generativa. Questi input e output includono prompt di sistema e utente, input e output dello strumento e risposte del modello. Di seguito sono riportati alcuni esempi di eventi di un sistema di AI generativa:

  • gen_ai.system.message: un evento che registra il prompt del sistema inviato a un modello di IA generativa. Il prompt del sistema fornisce istruzioni al modello che in genere non vengono visualizzate dall'utente finale e che guidano l'interpretazione del prompt da parte del modello.
  • gen_ai.user.message: un evento che registra il prompt fornito dall'utente inviato al modello.
  • gen_ai.assistant.message: un evento che registra l'output del modello, che può includere il record di un'invocazione dello strumento o che potrebbe contenere un output di risposta testuale. Un messaggio potrebbe includere risposte candidate che non vengono utilizzate dall'applicazione.
  • gen_ai.choice: un evento utilizzato per segnalare quali output candidati vengono utilizzati dall'applicazione.

Visualizzare le analisi dello stack

Per visualizzare gli stack trace, utilizza la scheda Stack trace.

Visualizzare informazioni generali e altri metadati

Per trovare informazioni generali sull'intervallo e una tabella di link ad altri intervalli, visualizza la scheda Metadati e link. Queste informazioni includono quanto segue:

  • ID intervallo: l'ID intervallo è un numero intero a 64 bit diverso da 0. Per maggiori dettagli, consulta TraceSpan.
  • ID intervallo padre
  • ID progetto
  • Ora di inizio e di fine
  • Tabella che elenca i link ad altri intervalli

Ogni riga della tabella denominata Collegamenti elenca un collegamento tra l'intervallo corrente e un altro intervallo. Il campo Attributi elenca le coppie chiave-valore per l'intervallo a cui si fa riferimento. Il campo Traccia rimanda alla traccia per l'intervallo collegato. Quando questo campo contiene Traccia corrente, l'intervallo collegato si trova nella stessa traccia dell'intervallo corrente. In caso contrario, il campo contiene un ID traccia. Per informazioni sui link, consulta la pagina di riferimento dell'API Links.

Passaggi successivi