Gestire le impostazioni di osservabilità

Questo documento descrive come configurare le impostazioni di osservabilità per l'app Gemini Enterprise o per i singoli agenti utilizzando la Google Cloud console o l'API REST.

La logica di attivazione dipende dal tipo di agente:

  • Agente Core Assistant: 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 Deep Research): utilizza l'opzione di attivazione/disattivazione a livello di agente all'interno delle impostazioni del singolo agente.

Dopo aver attivato le impostazioni, puoi visualizzare i seguenti dati dalle interazioni con l'assistente o gli agenti nell'app web Gemini Enterprise:

  • Visualizza le metriche in Metrics Explorer.
  • Visualizza tracce e intervalli in Esplora tracce.

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.
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à e degli accessi all'interno delle tue Google Cloud risorse. Forniscono informazioni dettagliate su chi ha eseguito l'azione, quando e da dove. Questi log sono essenziali per l'audit di sicurezza, la conformità e la comprensione di come vengono utilizzate le risorse.
Log degli errori dei connettori Gemini Enterprise I log degli errori dei connettori Gemini Enterprise acquisiscono gli errori e i guasti 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 API.

Prima di iniziare

Assicurati di avere:

Attivare le impostazioni di osservabilità

Per attivare l'osservabilità per l'app Gemini Enterprise o per i singoli agenti, puoi utilizzare la Google Cloud console o l'API REST.

Console

Per attivare le impostazioni di osservabilità utilizzando la Google Cloud console, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app che vuoi configurare.

  3. A seconda del tipo di agente che stai configurando, procedi in uno dei seguenti modi:

    • Agente Core Assistant: fai clic su Configurazioni e poi sulla scheda Osservabilità.
    • Altri agenti (agenti creati dai dipendenti di Workflow Builder e agenti di Deep Research): fai clic su Agenti, sul nome dell'agente che vuoi configurare e poi sulla scheda Configurazione.

  4. 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 log in Cloud Logging.
    Abilita il logging degli input dei prompt e degli output delle risposte Se questa opzione è abilitata, Cloud Logging registra i contenuti completi dei prompt degli utenti e delle risposte. Sono inclusi dati sensibili o informazioni che consentono l'identificazione personale (PII). Per abilitare questa impostazione, devi prima abilitare Abilita l'instrumentazione di tracce e log OpenTelemetry.

REST

Per configurare le impostazioni di osservabilità utilizzando l'API REST, consulta le seguenti sezioni:

Configurare le impostazioni di osservabilità per Core Assistant (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 seguenti sezioni:

Attivare 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 multi-regione per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID progetto.
  • LOCATION: la multi-regione del datastore: global, us o eu
  • APP_ID: l'ID dell'app che vuoi creare.
  • APP_DISPLAY_NAME: il nome visualizzato dell'app che vuoi creare.

Attivare l'osservabilità per un'app esistente

Per attivare l'osservabilità in 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 multi-regione per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID progetto.
  • LOCATION: la multi-regione del datastore: global, us o eu
  • APP_ID: l'ID dell'app.

Configurare le impostazioni di osservabilità per un singolo agente

Per attivare l'osservabilità per un singolo agente (ad esempio un agente di Workflow Builder o un agente di ricerca approfondita) utilizzando l'API REST, esegui questo comando per aggiornare 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 multi-regione per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID progetto.
  • LOCATION: la multi-regione del datastore: global, us o eu
  • APP_ID: l'ID dell'app.
  • AGENT_ID: l'ID dell'agente che vuoi configurare

Disattivare le impostazioni di osservabilità

Per disattivare le impostazioni di osservabilità per l'app Gemini Enterprise o per i singoli agenti, utilizza la Google Cloud console o l'API REST.

Console

Per disattivare le impostazioni di osservabilità utilizzando la Google Cloud console, segui questi passaggi:

  1. Nella Google Cloud console, vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app per cui vuoi disattivare le impostazioni di osservabilità.

  3. A seconda del tipo di agente che stai configurando, procedi in uno dei seguenti modi:

    • Agente Core Assistant: fai clic su Configurazioni e poi sulla scheda Osservabilità.
    • Altri agenti (inclusi gli agenti creati dai dipendenti di Workflow Builder e gli agenti di Deep Research): fai clic su Agenti, sul nome del l'agente che vuoi configurare e poi sulla scheda Configurazione.

  4. Puoi disattivare le seguenti impostazioni:

    Impostazione di osservabilità Descrizione
    Abilita l'instrumentazione di tracce e log OpenTelemetry Se questa opzione è disattivata, la raccolta di tracce, intervalli, log degli intervalli e metriche viene interrotta. Viene disattivata anche 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 questa opzione è disattivata, 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 seguenti sezioni:

Disattivare 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 multi-regione per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID progetto.
  • LOCATION: la multi-regione del datastore: global, us o eu
  • APP_ID: l'ID dell'app.

Disattivare l'osservabilità per un singolo agente

Per disattivare l'osservabilità per un singolo agente (ad esempio un agente di Workflow Builder o un agente di ricerca approfondita), 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/assistants/default_assistant/agents/AGENT_ID?updateMask=observabilityConfig" \
-d '{
  "observabilityConfig": {
    "observabilityEnabled": false,
    "sensitiveLoggingEnabled": false
  }
}'

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la multi-regione per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID progetto.
  • LOCATION: la multi-regione del datastore: global, us o eu
  • APP_ID: l'ID dell'app.
  • AGENT_ID: l'ID dell'agente che vuoi configurare

Passaggi successivi