Questo documento descrive come configurare le impostazioni di osservabilità per la tua app Gemini Enterprise o per i singoli agenti utilizzando la console Google Cloud o l'API REST.
La logica di attivazione dipende dal tipo di agente:
- Agente dell'assistente principale: utilizza l'opzione di attivazione/disattivazione a livello di applicazione (a livello di motore) nelle configurazioni.
- Altri agenti (al momento limitati agli agenti creati dai dipendenti di Workflow Builder e agli agenti di Deep Research): utilizza l'opzione a livello di agente nelle impostazioni del singolo agente.
Dopo aver attivato le impostazioni, puoi visualizzare i seguenti dati delle tue interazioni con l'assistente o gli agenti nell'app web Gemini Enterprise:
- Visualizza le metriche in Metrics Explorer.
- Visualizza tracce e span in Esplora tracce.
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. |
| Metriche | Le metriche sono misurazioni numeriche che i sistemi raccolgono nel tempo. Queste misurazioni rappresentano le prestazioni, l'utilizzo delle risorse o il comportamento di un sistema. Gli ingegneri utilizzano le metriche per monitorare l'integrità del sistema, identificare le tendenze e attivare gli avvisi. |
| Audit log sull'utilizzo | Gli audit log sull'utilizzo sono record delle attività amministrative e degli accessi all'interno delle tue risorse Google Cloud . Forniscono informazioni dettagliate su chi ha eseguito un'azione, quando e da dove. Questi log sono essenziali per l'audit della sicurezza, la conformità e la comprensione di come vengono utilizzate le tue risorse. |
| Log degli errori del connettore Gemini Enterprise | I log degli errori del connettore Gemini Enterprise acquisiscono gli errori e i problemi riscontrati durante l'integrazione di Gemini Enterprise con origini dati di terze parti come Jira e Microsoft OneDrive. Questi log includono problemi di connessione, problemi di trasformazione dei dati ed errori dell'API. |
Prima di iniziare
Assicurati di disporre di quanto segue:
Il ruolo Gemini Enterprise Admin.
Un'app web Gemini Enterprise esistente. Per informazioni sulla creazione di una nuova app, consulta Crea un'app.
Attiva le impostazioni di osservabilità
Per attivare l'osservabilità per la tua app Gemini Enterprise o per i singoli agenti, puoi utilizzare la console Google Cloud o l'API REST.
Console
Per attivare le impostazioni di osservabilità utilizzando la console Google Cloud , segui questi passaggi:
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Fai clic sul nome dell'app che vuoi configurare.
A seconda del tipo di agente che stai configurando, esegui una delle seguenti operazioni:
- Agente dell'assistente principale: fai clic su Configurazioni, quindi sulla scheda Osservabilità.
- Altri agenti (agenti creati dai dipendenti con Workflow Builder e agenti di Deep Research): fai clic su Agenti, poi sul nome dell'agente che vuoi configurare e infine sulla scheda Configurazione.
Puoi attivare o disattivare le seguenti impostazioni:
Impostazione di osservabilità Descrizione Abilita l'instrumentazione di tracce e log OpenTelemetry Se questa opzione è abilitata, puoi visualizzare tracce, intervalli, log degli intervalli e metriche associati ai tuoi log in Cloud Logging. Abilita il logging degli input dei prompt e degli output delle risposte Se abilitato, Cloud Logging registra i contenuti completi dei prompt e delle risposte degli utenti. Sono inclusi i dati sensibili o le informazioni che consentono l'identificazione personale (PII). Per attivare questa impostazione, devi prima attivare Abilita l'instrumentazione di tracce e log OpenTelemetry.
REST
Per configurare le impostazioni di osservabilità utilizzando l'API REST, consulta le sezioni seguenti:
- Configura le impostazioni di osservabilità per l'assistente principale (livello di app)
- Configura le impostazioni di osservabilità per un singolo agente
Configura le impostazioni di osservabilità per l'assistente principale (a livello di app)
Per configurare le impostazioni di osservabilità utilizzando l'API REST a livello di app (che si applica all'agente Core Assistant), consulta le sezioni seguenti:
Attiva l'osservabilità durante la creazione di un'app
Per creare una nuova app con l'osservabilità attivata, esegui questo comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines?engineId=APP_ID" \
-d '{
"name": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID",
"displayName": "APP_DISPLAY_NAME",
"solutionType": "SOLUTION_TYPE_SEARCH",
"searchEngineConfig": {
"searchTier": "SEARCH_TIER_ENTERPRISE",
"searchAddOns": ["SEARCH_ADD_ON_LLM"],
"requiredSubscriptionTier": "SUBSCRIPTION_TIER_SEARCH_AND_ASSISTANT"
},
"industryVertical": "GENERIC",
"appType": "APP_TYPE_INTRANET",
"observabilityConfig": {
"observabilityEnabled": true,
"sensitiveLoggingEnabled": true
}
}'
Sostituisci quanto segue:
ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multi-regione UEglobalper la località globale
PROJECT_ID: l'ID progetto.LOCATION: la località multiregionale del datastore:global,usoeuAPP_ID: l'ID dell'app che vuoi creare.APP_DISPLAY_NAME: il nome visualizzato dell'app che vuoi creare.
Attiva l'osservabilità per un'app esistente
Per attivare l'osservabilità su un'app esistente, esegui questo comando:
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID?updateMask=observabilityConfig" \
-d '{
"observabilityConfig": {
"observabilityEnabled": true,
"sensitiveLoggingEnabled": true
}
}'
Sostituisci quanto segue:
ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multi-regione UEglobalper la località globale
PROJECT_ID: l'ID progetto.LOCATION: la località multiregionale del datastore:global,usoeuAPP_ID: l'ID dell'app.
Configura le impostazioni di osservabilità per un singolo agente
Per attivare l'osservabilità per un singolo agente (ad esempio un agente Workflow Builder o un agente Deep Research) utilizzando l'API REST, esegui il seguente comando per aggiornare il observabilityConfig dell'agente:
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID?updateMask=observabilityConfig" \
-d '{
"observabilityConfig": {
"observabilityEnabled": true,
"sensitiveLoggingEnabled": true
}
}'
Sostituisci quanto segue:
ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multi-regione UEglobalper la località globale
PROJECT_ID: l'ID progetto.LOCATION: la località multiregionale del datastore:global,usoeuAPP_ID: l'ID dell'app.AGENT_ID: l'ID dell'agente che vuoi configurare
Disattiva le impostazioni di osservabilità
Per disattivare le impostazioni di osservabilità per l'app Gemini Enterprise o per i singoli agenti, utilizza la console Google Cloud o l'API REST.
Console
Per disattivare le impostazioni di osservabilità utilizzando la console Google Cloud , segui questi passaggi:
Nella console Google Cloud , vai alla pagina Gemini Enterprise.
Fai clic sul nome dell'app per cui vuoi disattivare le impostazioni di osservabilità.
A seconda del tipo di agente che stai configurando, esegui una delle seguenti operazioni:
- Agente dell'assistente principale: fai clic su Configurazioni, quindi sulla scheda Osservabilità.
- Altri agenti (inclusi gli agenti creati dai dipendenti con Workflow Builder e gli agenti di Deep Research): fai clic su Agenti, poi sul nome dell'agente che vuoi configurare e infine sulla scheda Configurazione.
Puoi disattivare le seguenti impostazioni:
Impostazione di osservabilità Descrizione Abilita l'instrumentazione di tracce e log OpenTelemetry Se disattivata, questa impostazione interrompe la raccolta di tracce, intervalli, log degli intervalli e metriche. Inoltre, disattiva l'impostazione Abilita il logging degli input dei prompt e degli output delle risposte, il che significa che non vengono inviati log a Cloud Logging. Abilita il logging degli input dei prompt e degli output delle risposte Se disattivato, Cloud Logging non registra gli input dei prompt e gli output delle risposte.
REST
Per disattivare le impostazioni di osservabilità utilizzando l'API REST, consulta le sezioni seguenti:
- Disattiva l'osservabilità a livello di app (Core Assistant)
- Disattiva l'osservabilità per un singolo agente
Disattiva l'osservabilità a livello di app (Core Assistant)
Per disattivare l'osservabilità a livello di applicazione (app), esegui questo comando:
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID?updateMask=observabilityConfig" \
-d '{
"observabilityConfig": {
"observabilityEnabled": false,
"sensitiveLoggingEnabled": false
}
}'
Sostituisci quanto segue:
ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multi-regione UEglobalper la località globale
PROJECT_ID: l'ID progetto.LOCATION: la località multiregionale del datastore:global,usoeuAPP_ID: l'ID dell'app.
Disattiva l'osservabilità per un singolo agente
Per disattivare l'osservabilità per un singolo agente (ad esempio un agente Workflow Builder o un agente Deep Research), esegui il seguente comando:
curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID?updateMask=observabilityConfig" \
-d '{
"observabilityConfig": {
"observabilityEnabled": false,
"sensitiveLoggingEnabled": false
}
}'
Sostituisci quanto segue:
ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:usper la multi-regione Stati Unitieuper la multi-regione UEglobalper la località globale
PROJECT_ID: l'ID progetto.LOCATION: la località multiregionale del datastore:global,usoeuAPP_ID: l'ID dell'app.AGENT_ID: l'ID dell'agente che vuoi configurare
Passaggi successivi
- Per scoprire di più su come accedere ai log di Gemini Enterprise, consulta Accedi agli audit log sull'utilizzo.
- Per scoprire di più su come accedere ai dati di traccia e span di Gemini Enterprise, consulta Accedi a tracce e intervalli in Esplora tracce.
- Per scoprire di più su come accedere alle metriche di Gemini Enterprise, consulta Accedi alle metriche in Esplora metriche.