Per visualizzare una rappresentazione aggregata dei dati di traccia o per trovare ed esplorare tracce individuali o tracce che contengono etichette specifiche, utilizza la pagina Esplora tracce.
Questa funzionalità è supportata solo per i progetti Google Cloud . Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
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, 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 ottenere maggiori informazioni. Le altre visualizzazioni consentono di visualizzare la latenza come percentile e informazioni sulla frequenza di intervallo. Per tutte le visualizzazioni, puoi utilizzare il puntatore per espandere l'asse X. Per i grafici a linee, puoi espandere gli assi x e y.
Quando esamini 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 visualizzazione di pagina Cerca traccia e poi inserisci l'ID traccia nella finestra di dialogo. Successivamente, puoi cercare gli intervalli e gli attributi nella traccia per parole chiave .
Quando visualizzi i dati aggregati, puoi cercare intervalli specifici applicando filtri. Ad esempio, potresti filtrare i dati per visualizzare solo gli intervalli per un servizio specifico. Poi, potresti aggiungere un secondo filtro che limita la visualizzazione agli intervalli di un servizio specifico che segnala un errore.
I dati tabellari ti consentono di visualizzare i dettagli dei singoli intervalli e ti aiutano a identificare gli outlier. Ad esempio, per trovare lo span con il valore di latenza più alto, seleziona la scheda Span e poi ordina i dati in base alla latenza. Per trovare i servizi che generano errori, filtra i dati in base allo stato dello span, quindi seleziona la scheda Raggruppati, che mostra i dati aggregati per span 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 cercare i dati di traccia. Per impostazione predefinita, la ricerca dei dati di traccia viene eseguita solo nel progetto selezionato dal selettore di progetti. Tuttavia, puoi configurare la pagina per cercare l'elenco dei progetti in un ambito della traccia.
- Le tue autorizzazioni IAM (Identity and Access Management) per i progetti cercati. Se non disponi dell'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.
Il resto della 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 tuo 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 delle tracce aggregati
Per visualizzare le informazioni aggregate sui dati di traccia:
-
Nella Google Cloud console, vai alla pagina 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 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 nellTrace#39;interfaccia di traccia.
Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
(Facoltativo) Configura i progetti in cui cercare i dati di traccia utilizzando l'elemento Scope:
Per mostrare i dati di traccia memorizzati nel tuo progetto, imposta il primo menu dell'elemento Ambito su
Progetto o su 
_Default.
Queste due impostazioni sono equivalenti.Per mostrare i dati di traccia archiviati in più progetti, espandi il primo menu dell'elemento Ambito, seleziona Ambito traccia e poi seleziona l'ambito traccia che elenca 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 restituiti dipendono dai tuoi ruoli IAM nei progetti cercati. Ad esempio, se i progetti in cui è stata eseguita la ricerca includono un progetto Google Cloud a cui non hai accesso, non vengono restituiti dati di traccia per quel progetto.
Per saperne di più, vedi Creare e gestire gli ambiti di traccia.
(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 quando vuoi vedere se ci sono tendenze nei dati di latenza.
Vai alla barra degli strumenti e imposta il selettore dell'intervallo di tempo su almeno due settimane. Dati di apertura memorizzati per 30 giorni.
Esplora i grafici, che mostrano pattern e tendenze nei dati di traccia:
Per ottenere informazioni sui dati di latenza degli intervalli, imposta il menu Visualizzazione grafico su Durata intervallo (mappa termica). L'intensità del colore è proporzionale al numero di intervalli. Per informazioni su una cella, utilizza il puntatore. La descrizione comando mostra il numero di intervalli, la data e l'ora e l'intervallo di tempo della cella.
Per visualizzare le tendenze della latenza, imposta il menu Visualizzazione grafico su Durata intervallo (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 Tasso di intervallo. Il grafico mostra la velocità di invio degli intervalli al tuo progetto.
Esplora i dati tabellari 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 Raggruppato, le metriche includono il tasso di errore e il numero di intervalli nel gruppo.
Per trovare i valori anomali, seleziona un'intestazione di colonna per ordinare la tabella.
Aggiungi filtri per limitare gli intervalli visualizzati. Per scoprire di più sul filtraggio dei 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, potresti filtrare in base al nome del servizio e allo 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 intervalli che corrispondono a tutti i filtri applicati.
Per modificare le impostazioni del filtro, puoi utilizzare il riquadro Filtri intervallo o la barra Filtro.
Applicare filtri di intervallo
Il riquadro Filtri intervallo elenca i filtri più comuni. Puoi selezionare più voci da qualsiasi sottocategoria. Man mano che aggiungi o rimuovi filtri, viene aggiornata anche la barra Filtro.
I valori di tutti i menu derivano dai dati di tracciamento. 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 intervallo:
- Servizio OpenTelemetry: filtra in base all'attributo
service.name. - Nome intervallo: il nome dell'intervallo.
- Stato intervallo: lo stato della richiesta. Per informazioni sui valori, consulta la documentazione di OpenTelemetry SpanStatus.
- Durata: la durata dell'intervallo.
- Tipo di span: descrive le relazioni tra gli span. Per informazioni sui valori, consulta la documentazione di OpenTelemetry SpanKind.
- Applicazione App Hub: filtra in base all'attributo 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 risorsa
gcp.apphub.workload.id.
Se vuoi filtrare in base a un attributo non elencato nel riquadro Filtri intervallo, utilizza la barra Filtro.
Utilizzare la barra dei filtri
La barra Filtro ti consente di applicare un filtro con una chiave predefinita e un valore che selezioni oppure puoi inserire sia la chiave che 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 attributi e poi aggiungi la chiave e il valore personalizzati. Se inserisci una chiave di filtro personalizzata, utilizza la stessa sintassi di una chiave per un attributo in un intervallo.
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 su200, il che comporta il filtro/http/status_code: 200. Per consentire al filtro di corrispondere a qualsiasi valore, seleziona Qualsiasi valore.
Trovare una traccia in base all'ID
Quando risolvi un problema relativo a un incidente o a un errore, potresti conoscere l'ID traccia. Per esplorare la traccia, procedi nel seguente modo:
-
Nella Google Cloud console, vai alla pagina Esplora tracce:
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
Vai alla barra degli strumenti, fai clic su Visualizzazione di pagina Cerca traccia e inserisci l'ID traccia.
Quando inserisci un ID valido, si apre il riquadro Dettagli e vengono visualizzate le informazioni sulla traccia e i relativi intervalli. Puoi utilizzare le opzioni in questo riquadro per esplorare la traccia. Ad esempio, potresti cercare parole chiave negli intervalli.
Esplorare una traccia
Per visualizzare una traccia o un intervallo:
-
Nella Google Cloud console, vai alla pagina 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 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 nellTrace#39;interfaccia di traccia.
Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
Esegui una di queste operazioni:
Vai alla sezione della tabella della pagina Trace Explorer e seleziona una voce dalla tabella che elenca gli span o le informazioni di riepilogo dopo aver raggruppato i dati per servizio e nome dello span.
Vai alla barra degli strumenti della pagina Esplora tracce, fai clic su Visualizzazione di pagina Cerca traccia e inserisci l'ID traccia.
Si apre il riquadro 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, quando questo attributo è 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 una voce di log o un evento è associato all'intervallo. Per modificare questo comportamento, utilizza il menu Log ed eventi.
(Facoltativo) Cerca il nome dello span, 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 span, nel nome servizio o nel riquadro Attributi che mostraGET, senza distinzione tra maiuscole e minuscole, viene evidenziato.Non puoi eseguire ricerche utilizzando un'espressione regolare e non puoi cercare log, eventi o metadati.
Per visualizzare i dettagli di un intervallo specifico, selezionalo e visualizza i relativi attributi ed eventi. Per saperne di più, consulta la sezione successiva.
Visualizzare 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 di tracciamento.
Visualizzare le informazioni dell'applicazione
I seguenti attributi delle risorse specifici dell'applicazione possono essere collegati ai dati di traccia. In questa sezione, interpreta a.b.{x,y} come
a.b.x e a.b.y:
gcp.apphub.application.{container,id,location}gcp.apphub.{workload,service}.{criticality_type,environment_type,id}
Per trovare i dati di traccia per la tua applicazione:
-
Nella Google Cloud console, vai alla pagina Esplora tracce:
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
Vai al riquadro Filtri intervallo e aggiungi filtri per la tua applicazione App Hub:
- Per filtrare in base all'ID applicazione (
gcp.apphub.application.id), utilizza il menu Applicazione App Hub. - Per filtrare in base al servizio di un'applicazione (
gcp.apphub.service.id), utilizza il menu Servizio App Hub. - Per filtrare in base al workload di un'applicazione (
gcp.apphub.workload.id), utilizza il menu Workload App Hub.
- Per filtrare in base all'ID applicazione (
Gli attributi delle risorse specifici dell'applicazione vengono allegati ai dati di traccia quando si verificano le seguenti condizioni:
- Le tue applicazioni App Hub utilizzano risorse Google Cloud supportate.
- Strumenti un'applicazione con OpenTelemetry e invii i dati di traccia raccolti dalla tua applicazione al tuo progetto utilizzando l'endpoint OTLPGoogle Cloud .
- I dati inviati al tuo progetto includono
attributi delle risorse OpenTelemetry
che identificano le risorse Google Cloud supportate utilizzate dalla tua applicazione. Gli attributi
devono includere quanto segue:
cloud.account.id- Uno dei
cloud.{availability_zone,region} Attributi specifici della risorsa. Ad esempio, per un carico di lavoro Kubernetes, gli span devono avere impostati
k8s.cluster.name,k8s.namespacee il tipo di deployment Kubernetes.Puoi utilizzare i processori per fare in modo che OpenTelemetry Collector colleghi attributi specifici della risorsa agli span. Per saperne di più, consulta
resourcedetectionprocessorek8sattributesprocessor.
Quando instrumenti un'applicazione, Google Cloud Observability utilizza gli attributi della risorsa precedenti e l'API App Hub per identificare l'applicazione App Hub. Le etichette specifiche dell'applicazione vengono aggiunte ai dati di traccia quando viene identificata un'applicazione.
Per ulteriori informazioni su questi attributi, consulta Google Cloud Convenzioni semantiche di App Hub.
Visualizzare log ed eventi
Per visualizzare i log e gli eventi correlati all'intervallo, vai alla scheda Log ed eventi.
Per visualizzare una voce di log, fai clic su keyboard_arrow_down Mostra altro.
Puoi anche selezionare il pulsante Visualizza log, che apre la pagina Esplora log con la query impostata per filtrare una traccia, uno span e un intervallo di tempo specifici. Questa query potrebbe non restituire voci di log.
Visualizzare gli eventi di AI generativa
Per visualizzare gli eventi relativi agli agenti di AI generativa, utilizza la scheda GenAI.
Questa scheda è disponibile quando gli span inviati a Trace seguono le
convenzioni semantiche OpenTelemetry per i sistemi di AI generativa,
che generano messaggi i cui nomi iniziano con gen_ai.
Lo screenshot seguente mostra come la pagina Trace Explorer visualizza gli eventi di AI generativa:
Per informazioni sull'applicazione di esempio che ha generato lo screenshot precedente, vedi Strumentare un agente LangGraph ReAct con OpenTelemetry.
Gli attributi sono coppie chiave-valore che descrivono una caratteristica. Di seguito sono riportati alcuni esempi di attributi di un sistema di AI generativa:
gen_ai.system: identifica il sistema che fornisce le funzionalità di AI 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 AI generativa. Questi input e output includono prompt di sistema e dell'utente, input e output degli strumenti 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 di sistema inviato a un modello di AI generativa. Il prompt di sistema fornisce istruzioni al modello che in genere non sono visibili all'utente finale e che guidano l'interpretazione del prompt dell'utente da parte del modello.gen_ai.user.message: Un evento che registra il prompt fornito dall'utente che è stato inviato al modello.gen_ai.assistant.message: un evento che registra l'output del modello, che può includere la registrazione di una chiamata di un tool 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.
Visualizza analisi dello stack
Per visualizzare gli stacktrace, utilizza la scheda Stacktrace.
Visualizzare informazioni generali e altri metadati
Per trovare informazioni generali sulla durata e una tabella di link ad altre durate, visualizza la scheda Metadati e link. Queste informazioni includono:
- ID span: l'ID span è un numero intero a 64 bit diverso da 0. Per maggiori dettagli, vedi
TraceSpan. - ID intervallo padre
- ID progetto
- Ora di inizio e ora di fine
- Tabella che elenca i link ad altri intervalli
Ogni riga della tabella denominata Link elenca un link tra l'intervallo corrente
e un altro intervallo. Il campo Attributi elenca le coppie chiave-valore per
l'intervallo a cui è stato creato il link. Il campo Traccia rimanda alla traccia dell'intervallo
a cui è collegato. Quando questo campo contiene Traccia corrente, lo span collegato si trova nella stessa traccia dello span corrente. In caso contrario,
il campo contiene un ID traccia. Per informazioni sui link, consulta la pagina di riferimento dell'API
Links.
Visualizzare le tendenze
Dopo aver implementato un aggiornamento di un'applicazione, potresti voler determinare se l'aggiornamento ha influito sulla latenza della risposta. Puoi visualizzare le tendenze nei dati di latenza impostando il selettore dell'intervallo di tempo in modo che i dati di latenza vengano visualizzati sia prima che dopo l'upgrade.
Per visualizzare le tendenze nei dati di traccia:
-
Nella Google Cloud console, vai alla pagina Esplora tracce:
Puoi trovare questa pagina anche utilizzando la barra di ricerca.
- Nella barra degli strumenti della console Google Cloud , seleziona il tuo Google Cloud progetto. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione della cartella app.
- (Facoltativo) Aggiungi filtri per configurare gli intervalli visualizzati.
- Vai alla barra degli strumenti e imposta il selettore dell'intervallo di tempo su almeno due settimane. I dati relativi all'intervallo vengono archiviati per 30 giorni.
- (Facoltativo) Modifica la selezione per il menu Visualizzazione grafico.