Gerenciar configurações de observabilidade

Neste documento, descrevemos como definir as configurações de observabilidade do app Gemini Enterprise ou de agentes individuais usando o console do Google Cloud ou a API REST.

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

  • Agente principal do Assistente: use o botão de alternância no nível do aplicativo (nível do mecanismo) nas configurações.
  • Outros agentes (limitados aos agentes criados por funcionários no Workflow Builder e aos agentes do Deep Research no momento): use o botão de alternância no nível do agente nas configurações individuais.

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

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

Principais conceitos

Nesta seção, apresentamos 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, a resposta do assistente e todas as ações subsequentes acionadas pela resposta, como o envio de um e-mail.
Período Um período é uma única unidade de trabalho 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 os 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 um período específico. Eles fornecem informações detalhadas e contextuais 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 medições numéricas que os sistemas coletam ao longo do tempo. Essas medições representam o desempenho, 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 realizou 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 a fontes de dados de terceiros, como o Jira e o 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 os seguintes itens:

Ativar as configurações de observabilidade

Para ativar a observabilidade no app Gemini Enterprise ou em agentes individuais, use o console do Google Cloud ou a API REST.

Console

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

  1. No console Google Cloud , 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, siga um destes procedimentos:

    • Agente principal do assistente: clique em Configurações e, em seguida, na guia Observabilidade.
    • Outros agentes (agentes criados por funcionários do Workflow Builder e agentes do Deep Research): clique em Agentes, no nome do agente que você quer configurar e na guia Configuração.

  4. Você pode 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, é possível ver traces, períodos, registros de período e métricas associados 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 das respostas dos usuários. 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 definir as configurações de observabilidade usando a API REST, consulte as seções a seguir:

Definir as configurações de observabilidade do Core Assistant (nível do app)

Para definir as configurações de observabilidade usando a API REST no nível do app (que se aplica ao agente do Core Assistant), 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 para um app atual

Para ativar a observabilidade em um 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": 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.

Definir as configurações de observabilidade de um agente específico

Para ativar a observabilidade de um agente individual (como um agente de criação do Workflow Builder ou 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 do Gemini Enterprise ou de agentes individuais, use o console do Google Cloud ou a API REST.

Console

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

  1. No console Google Cloud , 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, siga um destes procedimentos:

    • Agente principal do assistente: clique em Configurações e, em seguida, na guia Observabilidade.
    • Outros agentes (incluindo agentes criados por funcionários do Workflow Builder e agentes do Deep Research): clique em Agentes, clique no nome do agente que você quer configurar e, em seguida, clique na guia Configuração.

  4. Você pode 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. Ele 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 seguintes seções:

Desativar a observabilidade no nível do app (Core Assistant)

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 específico

Para desativar a observabilidade de um agente individual (como um agente do Workflow Builder ou do 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