Accedere a tracce e intervalli

Questo documento descrive come accedere e visualizzare le tracce e gli intervalli generati dall'app Gemini Enterprise. Le tracce e gli intervalli forniscono informazioni dettagliate sul rendimento e sul flusso di esecuzione delle richieste all'interno dell'applicazione, ad esempio quando si utilizza l'assistente o gli agenti.

Puoi visualizzare i dati delle tracce 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
Trace	Una traccia è una raccolta di intervalli che rappresenta una singola richiesta o transazione mentre scorre 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 qualsiasi azione successiva attivata dalla risposta, ad esempio l'invio di un'email.
Intervallo	Un intervallo è una singola unità di lavoro temporizzata all'interno di una traccia. Rappresenta un'operazione specifica, come una chiamata di funzione, una richiesta API o una query del database. Ogni intervallo include dettagli come l'ora di inizio e di fine, un ID univoco e la sua relazione con altri intervalli. Queste relazioni insieme 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 un intervallo, aiutando gli utenti a eseguire il debug dei problemi e a comprendere il flusso di una richiesta.

Prima di iniziare

Assicurati di avere:

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

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

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

• Abilita l'impostazione di osservabilità Abilita l'instrumentazione di tracce e log OpenTelemetry. A seconda del tipo di agente, puoi abilitarla nelle configurazioni a livello di app (per l'agente Core Assistant) o all'interno della scheda Configurazione dell'agente (per gli agenti creati dai dipendenti di Workflow Builder e gli agenti Deep Research). Per ulteriori informazioni, vedi Gestire le impostazioni di osservabilità.

Conservazione dei dati

Le tracce e gli intervalli generati dall'app Gemini Enterprise vengono archiviati in Cloud Trace nel tuo Google Cloud progetto 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ù recenti, consulta Periodi di conservazione di Cloud Trace nella documentazione relativa a quote e limiti di Cloud Trace.

Accedere alle tracce in Esplora tracce

Per accedere alle tracce e agli intervalli utilizzando Esplora tracce:

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

   Vai a Esplora tracce

2. Seleziona il Google Cloud progetto in cui è stata creata l'app Gemini Enterprise. Vengono visualizzati tutti gli intervalli del progetto.

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

   Nota: per ulteriori informazioni sull'utilizzo di Esplora tracce, vedi Trovare ed esplorare le tracce.

   

Filtrare ed eseguire ricerche nelle tracce

In Esplora tracce per il tuo progetto, puoi isolare e analizzare le esecuzioni degli agenti e dei connettori dati di Gemini Enterprise utilizzando questi filtri, parametri di ricerca e attributi:

• Filtri sfaccettati:
  • Servizio: filtra per AssistantService o connectorsexecution per isolare i percorsi delle richieste dell'agente della piattaforma e del connettore dati.
  • Intervallo: filtra per /AssistantService.StreamAssist per individuare gli intervalli di turno utente principali o cerca intervalli 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 x-cloud-trace-context intestazioni delle risposte di StreamAssist.
• Attributi personalizzati: esegui query in base all'gemini_enterprise.assist_token attributo negli intervalli execute_tool o invoke_connector per mappare i token di assistenza legacy a livello di turno alla cascata di tracce W3C.
• Attributi risorsa: ogni intervallo esportato include cloud.region, il
• Attributi risorsa: ogni intervallo esportato include l'cloud.region attributo. Questo attributo rappresenta la località di pubblicazione 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 ha esito positivo in una località, ma non in un'altra. Questo valore rappresenta la località che pubblica l'app, non la regione che ospita l'origine dati di terze parti. Per applicare questo filtro, vedi Applicare i filtri degli intervalli.

Accedere 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 principale-secondario.

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

Per accedere alle tracce di un agente:

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

Tabella di riepilogo delle tracce

La tabella principale nella 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. Ecco alcuni esempi di intervalli per i connettori dati di Gemini Enterprise:
  • execute_tool <tool_name>: emesso durante il livello di invio degli strumenti nel runtime dell'agente (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 dall'agente a un modello linguistico di grandi dimensioni.
• Durata: il tempo impiegato per completare l'intervallo di traccia (in minuti).
• Input: i dati di input o il messaggio inviato all'intervallo, se presenti.
• Output: il risultato di output restituito dall'intervallo, se presente.
• Ora di inizio: il timestamp esatto in cui è iniziata l'esecuzione dell'intervallo.

Visualizzazione dettagliata della traccia

Se fai clic su un ID intervallo di traccia , si apre una pagina dettagliata con:

1. Riepilogo: visualizza i metadati di base, tra cui Ora di inizio, Durata e il numero totale di Intervalli. Puoi fare clic su Visualizza in Cloud Trace o passare dai pulsanti di visualizzazione Grafico e Sequenza temporale.
2. Visualizzazioni: passa da una gerarchia grafica a una visualizzazione cronologica che mostra le relazioni principale-secondario di tutti gli span di traccia.
3. Dettagli intervallo selezionato: seleziona un singolo intervallo per visualizzare le sezioni dettagliate, che possono includere:
   • Riepilogo: mostra il nome dell'intervallo, il servizio di destinazione, il conteggio degli 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 passare direttamente ai log standard.
   • Valutazione: mostra eventuali risultati di valutazione, se configurati.
   • 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.
   • Stacktrace: dettagli dell'errore se l'esecuzione di un intervallo non riesce.
   • Metadati e link: link che fanno riferimento alle entità di Cloud Explorer correlate.
   • Attributi: tag delle risorse e parametri di osservabilità aggiuntivi coppia chiave-valore.

Gerarchia degli intervalli principale-secondario

Per l'esecuzione dei connettori dati, la nidificazione degli intervalli principale-secondario all'interno di una singola traccia W3C consente di individuare esattamente dove si verificano latenza o errori:

1. /AssistantService.StreamAssist: 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 delle convenzioni semantiche dell'AI generativa sperimentale

Avviso: la telemetria delle convenzioni semantiche 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ù ricchi 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 essere modificate o rimosse e su cui non è consigliabile 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à dell'agente, del modello e dello strumento, come l'esecuzione dell'agente e dello strumento e i passaggi di prompt e risposta.

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