Gerenciar configurações de observabilidade

Este documento descreve como configurar as definições de observabilidade do app Gemini Enterprise ou dos agentes individuais usando o Google Cloud console ou a API REST.

A lógica de ativação depende do tipo de agente:

  • Agente do Assistente principal: use a opção de ativação no nível do aplicativo (mecanismo) nas configurações.
  • Outros agentes: (limitado a agentes criados por funcionários do Agent Designer e agentes Deep Research no momento): use a opção de ativação no nível do agente nas configurações do agente individual.

Depois de ativar as configurações, você poderá conferir os seguintes dados das suas interações com o assistente ou os agentes no app da Web do Gemini Enterprise:

  • Visualizar métricas no Metrics Explorer.
  • Visualizar traces e períodos no Trace Explorer.

Principais conceitos

Esta seção apresenta os principais conceitos relacionados à observabilidade no Gemini Enterprise.

Conceito Descrição
Trace Um trace é uma coleção de períodos que representa uma única solicitação ou transação à medida que ela flui por diferentes serviços e componentes.

Por exemplo, um trace representa todo o ciclo de vida de uma solicitação. Isso inclui um usuário fazendo uma pergunta ao assistente do Gemini Enterprise, o assistente do Gemini Enterprise respondendo, e todas as ações subsequentes acionadas pela resposta, como enviar um e-mail.
Período Um período é uma unidade de trabalho única e cronometrada em um trace. Ele representa uma operação específica, como uma chamada de função, uma solicitação de API ou uma consulta de banco de dados. Cada período inclui detalhes como horários de início e término, um ID exclusivo e a relação com outros períodos. Essas relações juntas formam um trace.
Registros de período Os registros de período são mensagens ou eventos de formato livre com carimbo de data/hora associados a a um período específico. Eles fornecem informações contextuais detalhadas sobre a execução de um período, ajudando os usuários a depurar problemas e entender o fluxo de uma solicitação.
Métricas As métricas são medidas numéricas que os sistemas coletam ao longo do tempo. Essas medidas representam a performance, a utilização de recursos ou o comportamento de um sistema. Os engenheiros usam métricas para monitorar a integridade do sistema, identificar tendências e acionar alertas.
Registros de auditoria de uso Os registros de auditoria de uso são registros de atividades administrativas e acessos nos recursos do Google Cloud . Eles fornecem informações detalhadas sobre quem fez qual ação, quando e de onde. Esses registros são essenciais para auditoria de segurança, conformidade e compreensão de como seus recursos estão sendo usados.
Registros de erros do conector do Gemini Enterprise Os registros de erros do conector do Gemini Enterprise capturam erros e falhas encontrados ao integrar o Gemini Enterprise com fontes de dados de terceiros, como Jira e Microsoft OneDrive. Esses registros incluem problemas de conexão , problemas de transformação de dados e erros de API.

Antes de começar

Verifique se você tem o seguinte:

  • O papel de administrador do Gemini Enterprise.

  • Um app da Web do Gemini Enterprise. Para informações sobre como criar um novo app, consulte Criar um app.

Ativar as configurações de observabilidade

Para ativar a observabilidade do app Gemini Enterprise ou dos agentes individuais, você pode usar o Google Cloud console ou a API REST.

Console

Para ativar as configurações de observabilidade usando o Google Cloud console, siga estas etapas:

  1. No Google Cloud console, acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome do app que você quer configurar.

  3. Dependendo do tipo de agente que você está configurando, faça uma destas ações:

    • Agente do Assistente principal: clique em Configurações e na guia Observabilidade.
    • Outros agentes (agentes criados por funcionários do Agent Designer e agentes de Deep Research): clique em Agentes, no nome do agente que você quer configurar e na guia Observabilidade.

  4. É possível ativar ou desativar as seguintes configurações:

    Configuração de observabilidade Descrição
    Ativar a instrumentação de traces e registros do OpenTelemetry Quando ativado, você pode visualizar traces, períodos, registros de período e métricas associadas aos seus registros no Cloud Logging.
    Ativar a geração de registros de entradas de comandos e saídas de respostas Quando ativado, o Cloud Logging registra o conteúdo completo dos comandos e respostas do usuário. Isso inclui dados sensíveis ou informações de identificação pessoal (PII). Para ativar essa configuração, primeiro ative Ativar a instrumentação de traces e registros do OpenTelemetry.

REST

Para configurar as definições de observabilidade usando a API REST, consulte as seções a seguir:

Configurar as definições de observabilidade do Assistente principal (nível do app)

Para configurar as definições de observabilidade usando a API REST no nível do app (que se aplica ao agente do Assistente principal), consulte as seções a seguir:

Ativar a observabilidade ao criar um app

Para criar um novo app com a observabilidade ativada, execute o seguinte 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
  }
}'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: ID do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • APP_ID: o ID do app que você quer criar.
  • APP_DISPLAY_NAME: o nome de exibição do app que você quer criar.

Ativar a observabilidade de um app atual

Para ativar a observabilidade em um app atual, execute o seguinte 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
  }
}'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: ID do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • APP_ID: o ID do app.

Configurar as definições de observabilidade de um agente individual

Para ativar a observabilidade de um agente individual (como um agente do Agent Designer ou um agente do Deep Research) usando a API REST, execute o seguinte comando para atualizar o observabilityConfig do 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
  }
}'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: ID do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • APP_ID: o ID do app.
  • AGENT_ID: o ID do agente que você quer configurar

Desativar as configurações de observabilidade

Para desativar as configurações de observabilidade do app Gemini Enterprise ou dos agentes individuais, use o Google Cloud console ou a API REST.

Console

Para desativar as configurações de observabilidade usando o Google Cloud console, siga estas etapas:

  1. No Google Cloud console, acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. Clique no nome do app em que você quer desativar as configurações de observabilidade.

  3. Dependendo do tipo de agente que você está configurando, faça uma destas ações:

    • Agente do Assistente principal: clique em Configurações e na guia Observabilidade.
    • Outros agentes (incluindo agentes criados por funcionários do Agent Designer e agentes de pesquisa detalhada): clique em Agentes, no nome do agente que você quer configurar e na guia Observabilidade.

  4. É possível desativar as seguintes configurações:

    Configuração de observabilidade Descrição
    Ativar a instrumentação de traces e registros do OpenTelemetry Quando desativada, essa configuração interrompe a coleta de traces, períodos, registros de período e métricas. Ela também desativa a configuração Ativar a geração de registros de entradas de comandos e saídas de respostas, o que significa que nenhum registro é enviado ao Cloud Logging.
    Ativar a geração de registros de entradas de comandos e saídas de respostas Quando desativado, o Cloud Logging não registra entradas de comandos e saídas de respostas.

REST

Para desativar as configurações de observabilidade usando a API REST, consulte as seções a seguir:

Desativar a observabilidade no nível do app (Assistente principal)

Para desativar a observabilidade no nível do aplicativo (app), execute o seguinte 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
  }
}'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: ID do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • APP_ID: o ID do app.

Desativar a observabilidade de um agente individual

Para desativar a observabilidade de um agente individual (como um agente do Agent Designer ou um agente de Deep Research), execute o seguinte 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
  }
}'

Substitua:

  • ENDPOINT_LOCATION: a multirregião da sua solicitação de API. Especifique um dos seguintes valores:
    • us para a multirregião dos EUA
    • eu para a multirregião da UE
    • global para o local global
    Para mais informações, consulte Especificar uma multirregião para seu repositório de dados.
  • PROJECT_ID: ID do projeto.
  • LOCATION: a multirregião do seu repositório de dados: global, us ou eu
  • APP_ID: o ID do app.
  • AGENT_ID: o ID do agente que você quer configurar

A seguir