Trovare ed esplorare le tracce

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.

Lo screenshot seguente mostra come vengono visualizzati i dati di traccia:

Questa funzionalità è supportata solo per i Google Cloud progetti. Per le configurazioni di App Hub, seleziona il progetto host di App Hub o il progetto di gestione.

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 sulla velocità di intervallo.

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 in base a servizio, applicazione, stato di errore e altre proprietà.

• Per visualizzare una traccia specifica, utilizza l'opzione Visualizzazione di pagina Cerca traccia della barra degli strumenti.

Per identificare i valori anomali e visualizzare i dettagli dei singoli intervalli, utilizza la sezione tabellare:

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

• Per capire quanti intervalli generano i diversi servizi, utilizza la scheda Raggruppato. Ogni riga corrisponde a un servizio e a un nome dell'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 che mostra lo span nel contesto della relativa traccia. Da questa visualizzazione puoi esplorare lo span, i relativi attributi e visualizzare gli eventi e i dati di 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:

• I progetti in cui cercare i dati di traccia. Per impostazione predefinita, il sistema cerca i dati di traccia 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 in cui è stata eseguita la ricerca. 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 del 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:

1. Nella Google Cloud console, 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 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, vedi Risoluzione dei problemi: nessun dato nellTrace#39;interfaccia di traccia.

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 i progetti in cui cercare i dati di traccia utilizzando l'elemento Ambito:

      • 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 di traccia e poi seleziona l'ambito di 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ù, consulta la pagina Creare e gestire gli ambiti di traccia.

   3. (Facoltativo) Aggiorna l'intervallo di tempo utilizzando il selettore dell'intervallo di tempo o utilizzando 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. I dati relativi all'intervallo 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 relativa descrizione comando. La descrizione comando elenca il numero di intervalli, la data e l'ora e l'intervallo di tempo della cella.

     Nota: se selezioni una cella nella mappa termica, la tabella che elenca i singoli intervalli o i raggruppamenti di intervalli viene aggiornata.

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

   • 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à con cui gli intervalli vengono inviati al tuo progetto.

5. Per trovare i valori anomali, seleziona la scheda Intervalli e ordina la tabella in base alla durata.

   Se vuoi maggiori informazioni su un intervallo specifico, selezionalo. Si apre un riquadro che mostra lo span nel contesto della traccia. Puoi quindi esplorare lo span e la traccia.

6. Per esplorare il numero di intervalli generati per ogni servizio, insieme alle informazioni statistiche, seleziona la scheda Raggruppato:

   • Ogni riga corrisponde a un servizio e a un nome dell'intervallo specifici.
   • Puoi ordinare le righe in base all'intestazione della durata.

   Se vuoi maggiori informazioni su un raggruppamento specifico, seleziona il nome dell'intervallo per una riga. Si apre un riquadro che mostra lo span nel contesto della traccia. A questo punto, puoi esplorare lo span e la traccia.

7. Per limitare gli intervalli visualizzati, aggiungi filtri. 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 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 intervalli che corrispondono a tutti i filtri applicati.

Filtrare una traccia per ID

Quando risolvi un problema relativo a un incidente o a un errore, potresti conoscere l'ID traccia. Per esplorare la traccia, 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.

Nota: se inserisci un ID traccia non trovato, è possibile che i dati di traccia siano memorizzati in un progetto non cercato dalla pagina Esplora tracce o che tu non disponga di un ruolo IAM che ti consenta 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 ruolo IAM ti consenta di visualizzare i dati di traccia e poi assicurati che l'elemento Ambito sia configurato per cercare tutti i progetti che archiviano i dati di traccia. Per ulteriori informazioni, vedi Aggiornare l'elenco dei progetti in cui vengono cercati i dati di traccia.

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 di 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 attributo 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 su 200, il che comporta il filtro /http/status_code: 200. Per consentire al filtro di corrispondere a qualsiasi valore, seleziona Qualsiasi valore.

Filtra per applicazione

Gli intervalli di Trace generati dalla strumentazione aggiunta alle tue applicazioni possono includere i seguenti attributi delle risorse:

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

La pagina Explorer tracce include i seguenti filtri di intervallo i cui menu elencano applicazioni, servizi e workload registrati in App Hub:

• 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.

Per informazioni su come instrumentare l'applicazione in modo che gli intervalli di traccia includano attributi specifici dell'applicazione, consulta Instrumentazione per il monitoraggio delle applicazioni.

Esplorare una traccia

Questa sezione fornisce informazioni su come esplorare un intervallo nel contesto della relativa traccia:

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

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

   • Vai alla sezione della tabella della pagina Esplora tracce e seleziona una voce dalla sezione tabellare. 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 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. Vengono visualizzati i dettagli dello span o della traccia selezionati:

   • La colonna Nome mostra la gerarchia delle chiamate e la prima voce include l'ID traccia. Questa colonna potrebbe includere anche annotazioni che indicano se sono disponibili eventiAIA generativa o dati di log.
   • La colonna Servizio viene estratta dall'attributo OpenTelemetry service.name, se 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.

3. Per esplorare la traccia:

   • Utilizza il puntatore per selezionare intervalli diversi. Quando selezioni un intervallo, le schede della pagina vengono aggiornate per mostrare gli attributi, le voci di log e gli eventi dell'intervallo.

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

     La ricerca si applica solo ai campi nome span, nome servizio e attributi. Puoi eseguire ricerche solo per testo normale e non puoi cercare log, eventi o metadati.

     Ad esempio, se inserisci GET, il testo nel nome span, nel nome del servizio o nel riquadro Attributi che visualizza GET, senza distinzione tra maiuscole e minuscole, viene evidenziato.

   Nota:l'esploratore di tracce mostra un massimo di 10.000 intervalli per una traccia.

Visualizzare attributi, voci di log ed eventi

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

• Attributi: questa scheda elenca le etichette associate agli span. Per informazioni sulle etichette, vedi Etichette di tracciamento.

• Log ed eventi: in questa scheda sono elencati gli eventi e le voci di log i cui campi trace_id e span_id corrispondono all'intervallo selezionato. Vengono mostrate solo le voci di log che hai l'autorizzazione a visualizzare.

  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 log. La query è impostata per filtrare una traccia, uno span e un intervallo di tempo specifici.

  Nota :gli eventi di AI generativa vengono visualizzati nella scheda Input/Output. Per saperne di più, vedi Visualizzare gli eventi di AI generativa.

• Stacktrace: elenca gli stacktrace disponibili.

• Metadati e link: elenca le informazioni generali sull'intervallo:

  • 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. Per ogni link, questa tabella elenca quanto segue:

    • Le coppie chiave-valore per l'intervallo a cui è stato creato un link.
    • L'ID traccia per l'intervallo 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.

La sezione Dettagli potrebbe includere anche una scheda denominata Input/Output. Questa scheda mostra gli eventi di AI generativa.

Visualizzare gli eventi di AI generativa

Anteprima

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni delle fasi di lancio.

Per visualizzare gli eventi correlati agli agenti AI generativi, utilizza la scheda Input/Output. Questa scheda mostra gli eventi che seguono le convenzioni semantiche OpenTelemetry GenAI.

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 correlano i dati di traccia e log. Per informazioni sulle configurazioni supportate, vedi Raccogliere e visualizzare prompt e risposte multimodali.

Lo screenshot seguente mostra come la pagina Trace Explorer visualizza gli eventi di AI generativa basati su testo allegati agli span:

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

Passaggi successivi

• Creare e gestire gli ambiti della traccia
• Condividere tracce e intervalli
• Risolvere i problemi