Gestire le impostazioni di osservabilità

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:

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:

  1. Nella console Google Cloud , 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, 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.
  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 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 (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:
    • 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 località multiregionale 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.

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:
    • 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 località multiregionale del datastore: global, us o eu
  • APP_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:
    • 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 località multiregionale del datastore: global, us o eu
  • APP_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:

  1. Nella console Google Cloud , 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, 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.
  4. 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)

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:
    • 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 località multiregionale del datastore: global, us o eu
  • APP_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:
    • 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 località multiregionale del datastore: global, us o eu
  • APP_ID: l'ID dell'app.
  • AGENT_ID: l'ID dell'agente che vuoi configurare

Passaggi successivi