Acessar traces e períodos

Este documento descreve como acessar e visualizar traces e períodos gerados pelo app Gemini Enterprise. Os traces e períodos oferecem insights detalhados sobre o desempenho e o fluxo de execução de solicitações no aplicativo, como ao usar o assistente ou os agentes.

É possível visualizar os dados de trace usando o Explorador de traces ou diretamente em agentes individuais usando a guia Traces do agente.

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 com carimbo de data/hora associados 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.

Antes de começar

Verifique se você tem o seguinte:

• O papel de admin do Gemini Enterprise ou o Google Cloud papel de usuário do Gemini Enterprise do console.

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

• Para acessar os traces, você precisa ter o papel de usuário do Cloud Trace (roles/cloudtrace.user).

• Ative a configuração de observabilidade Ativar a instrumentação de traces e registros do OpenTelemetry. Dependendo do tipo de agente, você ativa essa opção nas configurações do app (para o agente Assistente principal) ou na guia Configuração do agente (para agentes criados por funcionários do Workflow Builder e agentes de Deep Research). Para mais informações, consulte Gerenciar configurações de observabilidade.

Retenção de dados

Os traces e períodos gerados pelo app Gemini Enterprise são armazenados no Cloud Trace no seu Google Cloud projeto, e a retenção deles é regida pelo Cloud Trace. Por padrão, o Cloud Trace retém dados de período por 30 dias; os dados mais antigos que o período de armazenamento são excluídos automaticamente. Para os valores de retenção oficiais e mais atuais, consulte Períodos de retenção do Cloud Trace na documentação de cotas e limites do Cloud Trace.

Acessar traces no Explorador de traces

Para acessar traces e períodos usando o Explorador de traces, siga estas etapas:

1. No Google Cloud console, acesse a página Explorador de traces.

   Acessar o Explorador de traces

2. Selecione o Google Cloud projeto em que o app Gemini Enterprise foi criado. Todos os períodos do seu projeto serão exibidos.

3. Na tabela, clique em um ID do período para conferir os detalhes do trace, incluindo a duração do período e outros atributos.

   **Observação**: para mais informações sobre como usar o Explorador de traces, consulte Encontrar e explorar traces.

   

Filtrar e pesquisar traces

No Explorador de traces do seu projeto, é possível isolar e analisar as execuções do agente do Gemini Enterprise e do conector de dados usando estes filtros, parâmetros de consulta e atributos:

• Filtros facetados:
  • Serviço: filtre por AssistantService ou connectorsexecution para isolar os caminhos de solicitação do agente da plataforma e do conector de dados.
  • Período: filtre por /AssistantService.StreamAssist para localizar os períodos de turno do usuário raiz ou pesquise períodos filhos como execute_tool <tool_name> e invoke_connector <connector>.
• Pesquisa direta de ID do trace: encontre traces diretamente usando o ID de trace W3C padrão de 32 caracteres, que pode ser extraído dos x-cloud-trace-context cabeçalhos de resposta de StreamAssist.
• Atributos personalizados: consulte o gemini_enterprise.assist_token atributo em períodos execute_tool ou invoke_connector para mapear tokens de assistência legados no nível de turno para a cascata de traces W3C.
• Atributos de recurso: cada período exportado carrega cloud.region, o
• Atributos de recurso: cada período exportado carrega o cloud.region atributo. Esse atributo representa o local de serviço do Gemini Enterprise que processou a solicitação, como global, us ou eu. É possível filtrar por esse atributo para comparar a performance em regiões. Essa comparação é útil quando um conector de dados é bem-sucedido em um local, mas falha em outro. Esse valor representa o local que atende seu app, não a região que hospeda a fonte de dados de terceiros. Para aplicar esse filtro, consulte Aplicar filtros de período.

Acessar traces de agentes

Também é possível visualizar os períodos de trace diretamente para agentes individuais na guia Traces do agente, que mostra um resumo cronológico detalhado dos registros de trace de período e das estruturas de execução pai-filho.

Observação: a guia Traces está disponível para o agente Assistente principal, agentes criados por funcionários do Workflow Builder e agentes de Deep Research.

Para acessar traces de um agente:

1. No Google Cloud console, acesse seu app e clique em Agentes.
2. Selecione o agente que você quer inspecionar e clique na guia Traces.

Tabela de resumo de traces

A tabela principal na guia Traces mostra as seguintes informações para cada período de trace:

• Status: o status atual do trace (atualmente mostra Não definido).
• ID do período de trace: o identificador exclusivo do período de trace. Clique no link do ID do período para acessar os detalhes.
• Nome do período: uma breve descrição do trabalho que o período está fazendo. Exemplos de períodos para conectores de dados do Gemini Enterprise incluem:
  • execute_tool <tool_name>: emitido durante a camada de envio de ferramentas no ambiente de execução do agente (por exemplo, execute_tool federated_search).
  • invoke_connector <connector>: gerado pela camada de execução de conectores para representar a lógica de solicitação para o conector específico (por exemplo, invoke_connector jira ou invoke_connector servicenow), que substitui os períodos RPC padrão do lado do serviço.
• Tipo de período: o tipo de período. As opções incluem:
  • Agent to Tool: uma invocação do agente para uma ferramenta externa (reutilizada para operações execute_tool e invoke_connector).
  • Invoke Agent: uma invocação de um agente.
  • Agent to Model: uma solicitação do agente para um modelo de linguagem grande.
• Duração: o tempo gasto para concluir o período de trace (em minutos).
• Entrada: os dados de entrada ou a mensagem enviada ao período, se houver.
• Saída: o resultado de saída retornado pelo período, se houver.
• Horário de início: o carimbo de data/hora exato em que o período começou a execução.

Visualização detalhada do trace

Ao clicar em um ID do período de trace , uma página detalhada é aberta com:

1. Resumo: confira os metadados de linha de base, incluindo Horário de início, Duração e contagem total de Períodos. É possível clicar em Visualizar no Cloud Trace ou alternar entre os botões de visualização Gráfico e Linha do tempo.
2. Visualizações: alterne entre uma hierarquia gráfica ou uma visualização da linha do tempo mostrando as relações pai-filho de todos os períodos de trace.
3. Detalhes do período selecionado: selecione um único período para mostrar seções detalhadas, que podem incluir:
   • Resumo: mostra o nome do período, o serviço de destino, a contagem de períodos totais com esta ação e a duração total (em segundos).
   • Registros: confira detalhes relevantes do evento, se configurado. Clique em Ver registros para acessar diretamente os registros padrão.
   • Avaliação: mostra os resultados da avaliação, se configurado.
   • Entrada e saída: payloads completos de solicitação e resposta.
   • Registros e eventos: lista de eventos que ocorreram durante a execução desse período.
   • Stacktraces: detalhes do erro se uma execução de período falhar.
   • Metadados e links: links que fazem referência a entidades relacionadas do Cloud Explorer.
   • Atributos: tags de recursos e outros parâmetros de observabilidade de chave-valor.

Hierarquia de períodos pai-filho

Para a execução de conectores de dados, o aninhamento de períodos pai-filho em um único trace W3C ajuda a identificar exatamente onde a latência ou os erros ocorrem:

1. /AssistantService.StreamAssist: período da plataforma C++ raiz que inicia a solicitação.
2. invoke_agent core_assistant: o período de execução do agente.
3. execute_tool <tool_name>: o período de execução da ferramenta ativa (por exemplo, execute_tool federated_search).
4. invoke_connector <connector_name> (por exemplo, invoke_connector jira ou invoke_connector servicenow): o período de execução dos conectores, que representa o ciclo de vida da solicitação para o endpoint de terceiros.

Telemetria de convenção semântica de IA generativa experimental

Aviso:a telemetria de convenção semântica de IA generativa descrita nesta seção é experimental. Os atributos, esquemas e formatos estão sujeitos a mudanças em versões futuras.

Além da telemetria estável, os períodos de trace do Gemini Enterprise incluem metadados mais avançados com base nas convenções semânticas de IA generativa do OpenTelemetry. O OpenTelemetry classifica essas convenções como status de desenvolvimento. Esse status se aplica a especificações iniciais que podem ser alteradas ou removidas e não devem ser usadas na produção. Como essas convenções ainda não são estáveis, essa telemetria do Gemini Enterprise é experimental. Esses períodos incluem atributos gen_ai.* que descrevem a atividade do agente, do modelo e da ferramenta, como a execução do agente e da ferramenta e as etapas de comando e resposta.

O conteúdo do comando e da resposta nos períodos de trace (como texto do comando e respostas geradas) só aparece quando as configurações de observabilidade permitem o registro de entradas de comando e saídas de resposta. Caso contrário, o conteúdo será editado ou omitido. Para mudar essas configurações, consulte Gerenciar configurações de observabilidade.