Accedere a tracce e intervalli

Questo documento descrive come accedere e visualizzare le tracce e gli intervalli generati dalla tua app Gemini Enterprise. Le tracce e gli intervalli forniscono insight dettagliati sulle prestazioni e sul flusso di esecuzione delle richieste all'interno della tua applicazione, ad esempio quando utilizzi l'assistente o gli agenti.

Puoi visualizzare i dati di traccia utilizzando Esplora tracce o direttamente all'interno dei singoli agenti utilizzando la scheda Tracce dell'agente.

Concetti fondamentali

Questa sezione introduce i concetti chiave relativi all'osservabilità in Gemini Enterprise.

Concetto	Descrizione
Traccia	Una traccia è una raccolta di intervalli che rappresenta una singola richiesta o transazione mentre passa attraverso diversi servizi e componenti. Ad esempio, una traccia rappresenta l'intero ciclo di vita di una richiesta. Ciò include un utente che pone una domanda all'assistente Gemini Enterprise, l'assistente Gemini Enterprise che risponde e tutte le azioni successive attivate dalla risposta, come l'invio di un'email.
Intervallo	Uno span è una singola unità di lavoro temporizzata all'interno di una traccia. Rappresenta un'operazione specifica, ad esempio una chiamata di funzione, una richiesta API o una query di database. Ogni intervallo include dettagli come l'ora di inizio e di fine, un ID univoco e la relazione con altri intervalli. Queste relazioni formano una traccia.
Log degli intervalli	I log degli intervalli sono messaggi o eventi in formato libero con timestamp associati a un intervallo specifico. Forniscono informazioni dettagliate e contestuali sull'esecuzione di uno span, aiutando gli utenti a eseguire il debug dei problemi e a comprendere il flusso di una richiesta.

Prima di iniziare

Assicurati di disporre di quanto segue:

• Il ruolo Gemini Enterprise Admin o il ruolo Gemini Enterprise User della console Google Cloud .

• Un'app web Gemini Enterprise esistente. Per informazioni sulla creazione di una nuova app, consulta Crea un'app.

• Per accedere alle tracce, devi disporre del ruolo Utente Cloud Trace (roles/cloudtrace.user).

• Attiva l'impostazione di osservabilità Abilita l'instrumentazione di tracce e log OpenTelemetry. A seconda del tipo di agente, puoi attivare questa opzione nelle configurazioni a livello di app (per l'agente Assistente principale) o nella scheda Configurazione dell'agente (per gli agenti Workflow Builder creati dai dipendenti e gli agenti Deep Research). Per saperne di più, consulta Gestisci le impostazioni di osservabilità.

Conservazione dei dati

Le tracce e gli intervalli generati dalla tua app Gemini Enterprise vengono archiviati in Cloud Trace nel tuo progetto Google Cloud e la loro conservazione è regolata da Cloud Trace. Per impostazione predefinita, Cloud Trace conserva i dati degli intervalli per 30 giorni; i dati precedenti al periodo di conservazione vengono eliminati automaticamente. Per i valori di conservazione autorevoli e più aggiornati, consulta Periodi di conservazione di Cloud Trace nella documentazione Quote e limiti di Cloud Trace.

Accedi alle tracce in Esplora tracce

Per accedere a tracce e span utilizzando Esplora tracce, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Trace Explorer.

   Vai a Trace Explorer

2. Seleziona il progetto Google Cloud in cui è stata creata l'app Gemini Enterprise. Vedi tutti gli intervalli per il tuo progetto.

3. Nella tabella, fai clic su un ID intervallo per visualizzare i dettagli della traccia, tra cui la durata dell'intervallo e altri attributi.

   Nota: per saperne di più sull'utilizzo di Esplora tracce, consulta Trova ed esplora le tracce.

   

Filtra e cerca tracce

In Esplora tracce per il tuo progetto, puoi isolare e analizzare le esecuzioni dell'agente e del connettore dati di Gemini Enterprise utilizzando questi filtri, parametri di ricerca e attributi:

• Filtri con più opzioni:
  • Servizio: filtra per AssistantService o connectorsexecution per isolare i percorsi di richiesta dell'agente della piattaforma e del connettore dati.
  • Span: filtra per /AssistantService.StreamAssist per individuare gli span user-turn principali o cerca gli span secondari come execute_tool <tool_name> e invoke_connector <connector>.
• Ricerca diretta dell'ID traccia: trova le tracce direttamente utilizzando l'ID traccia W3C standard di 32 caratteri, che può essere estratto dalle intestazioni della risposta x-cloud-trace-context di StreamAssist.
• Attributi personalizzati: esegui una query in base all'attributo gemini_enterprise.assist_token su span execute_tool o invoke_connector per mappare i token di assistenza legacy a livello di turno alla struttura a cascata della traccia W3C.
• Attributi risorsa: ogni intervallo esportato contiene cloud.region,
• Attributi risorsa: ogni intervallo esportato contiene l'attributo cloud.region. Questo attributo rappresenta la località di gestione di Gemini Enterprise che ha gestito la richiesta, ad esempio global, us o eu. Puoi filtrare in base a questo attributo per confrontare il rendimento tra le regioni. Questo confronto è utile quando un connettore dati funziona in una località, ma non in un'altra. Questo valore rappresenta la località che gestisce la tua app, non la regione che ospita l'origine dati di terze parti. Per applicare questo filtro, consulta Applica filtri di intervallo.

Accedi alle tracce per gli agenti

Puoi anche visualizzare gli intervalli di traccia direttamente per i singoli agenti nella scheda Tracce dell'agente, che mostra un riepilogo cronologico dettagliato dei record di traccia degli intervalli e delle strutture di esecuzione padre-figlio.

Nota: la scheda Tracce è disponibile per l'agente Core Assistant, gli agenti creati dai dipendenti con Workflow Builder e gli agenti Deep Research.

Per accedere alle tracce di un agente:

1. Nella console Google Cloud , vai alla tua app e fai clic su Agenti.
2. Seleziona l'agente che vuoi ispezionare, quindi fai clic sulla scheda Tracce.

Tabella di riepilogo delle tracce

La tabella principale della scheda Tracce mostra le seguenti informazioni per ogni intervallo di traccia:

• Stato: lo stato attuale della traccia (al momento viene visualizzato Non impostato).
• ID intervallo di traccia: l'identificatore univoco dell'intervallo di traccia. Fai clic sul link dell'ID intervallo per visualizzarne i dettagli.
• Nome intervallo: una breve descrizione del lavoro svolto dall'intervallo. Esempi di intervalli per i connettori dati di Gemini Enterprise:
  • execute_tool <tool_name>: emesso durante il livello di invio dello strumento nell'Agent Runtime (ad esempio, execute_tool federated_search).
  • invoke_connector <connector>: generato dal livello di esecuzione dei connettori per rappresentare la logica della richiesta al connettore specifico (ad esempio invoke_connector jira o invoke_connector servicenow), che sostituisce gli intervalli RPC lato servizio predefiniti.
• Tipo di intervallo: il tipo di intervallo. Le opzioni includono:
  • Agent to Tool: una chiamata dall'agente a uno strumento esterno (riutilizzata per le operazioni execute_tool e invoke_connector).
  • Invoke Agent: una chiamata di un agente.
  • Agent to Model: una richiesta dell'agente a un modello linguistico di grandi dimensioni.
• Durata: il tempo impiegato per completare l'intervallo di traccia (in minuti).
• Input: i dati o il messaggio di input inviati allo span, se presenti.
• Output: il risultato dell'output restituito dallo span, se presente.
• Ora di inizio: il timestamp esatto di quando è iniziata l'esecuzione dello span.

Visualizzazione dettagliata della traccia

Se fai clic su un ID intervallo di Trace, si apre una pagina dei dettagli contenente:

1. Riepilogo: visualizza i metadati della baseline, tra cui Ora di inizio, Durata e conteggio totale degli intervalli. Puoi fare clic su Visualizza in Cloud Trace o passare dai pulsanti di visualizzazione Grafico a Cronologia e viceversa.
2. Visualizzazioni: passa da una gerarchia grafica a una visualizzazione cronologica che mostra le relazioni principale-secondario di tutti gli intervalli di traccia.
3. Dettagli dello span selezionato: seleziona un singolo span per visualizzare sezioni dettagliate, che possono includere:
   • Riepilogo: mostra il nome dell'intervallo, il servizio di destinazione, il numero di intervalli totali con questa azione e la durata totale (in secondi).
   • Log: visualizza i dettagli degli eventi pertinenti, se configurati. Fai clic su Visualizza log per accedere direttamente ai log standard.
   • Valutazione: mostra i risultati della valutazione, se configurata.
   • Input e output: payload completi di richiesta e risposta.
   • Log ed eventi: elenco degli eventi che si sono verificati durante l'esecuzione di questo intervallo.
   • Analisi dello stack: dettagli dell'errore se l'esecuzione di uno span non va a buon fine.
   • Metadati e link: link che fanno riferimento a entità correlate di Cloud Explorer.
   • Attributi: tag delle risorse e parametri di osservabilità aggiuntivi a coppia chiave-valore.

Gerarchia degli intervalli padre-figlio

Per l'esecuzione dei connettori dati, l'annidamento degli intervalli padre-figlio all'interno di una singola traccia W3C aiuta a individuare esattamente dove si verificano la latenza o gli errori:

1. /AssistantService.StreamAssist: l'intervallo della piattaforma C++ principale che avvia la richiesta.
2. invoke_agent core_assistant: l'intervallo di esecuzione dell'agente.
3. execute_tool <tool_name>: l'intervallo di esecuzione dello strumento attivo (ad esempio, execute_tool federated_search).
4. invoke_connector <connector_name> (ad esempio, invoke_connector jira o invoke_connector servicenow): l'intervallo di esecuzione dei connettori, che rappresenta il ciclo di vita della richiesta all'endpoint di terze parti.

Telemetria della convenzione semantica dell'AI generativa sperimentale

Avviso: la telemetria della convenzione semantica dell'AI generativa descritta in questa sezione è sperimentale. Gli attributi, gli schemi e i formati sono soggetti a modifiche nelle release future.

Oltre alla telemetria stabile, gli intervalli di traccia di Gemini Enterprise includono metadati più completi basati sulle convenzioni semantiche dell'AI generativa di OpenTelemetry. OpenTelemetry classifica queste convenzioni come Stato di sviluppo. Questo stato si applica alle specifiche in fase iniziale che possono cambiare o essere rimosse e su cui non si deve fare affidamento in produzione. Poiché queste convenzioni non sono ancora stabili, questa telemetria di Gemini Enterprise è sperimentale. Questi intervalli includono attributi gen_ai.* che descrivono l'attività di agenti, modelli e strumenti, come l'esecuzione di agenti e strumenti e i passaggi di prompt e risposta.

I contenuti dei prompt e delle risposte negli intervalli di traccia (come il testo del prompt e le risposte generate) vengono visualizzati solo se le impostazioni di osservabilità consentono il logging degli input dei prompt e degli output delle risposte. In caso contrario, i contenuti vengono oscurati o omessi. Per modificare queste impostazioni, consulta Gestisci le impostazioni di osservabilità.