Acessar traces e períodos

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

É possível conferir os dados de trace usando o Trace Explorer ou diretamente em agentes individuais usando a guia Traces do agente.

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.

Antes de começar

Verifique se você tem os seguintes itens:

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

• Um app da Web do Gemini Enterprise. Para saber como criar um novo app, consulte Criar um app.

• Para acessar traces, é preciso 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 Core Assistant) ou na guia Configuração do agente (para agentes criados por funcionários do Workflow Builder e agentes do Deep Research). Para mais informações, consulte Gerenciar configurações de observabilidade.

Retenção de dados

Os traces e períodos gerados pelo app do Gemini Enterprise são armazenados no Cloud Trace no seu projeto do Google Cloud , 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 ver os valores de retenção oficiais e mais atuais, consulte Períodos de retenção do Cloud Trace na documentação Cotas e limites do Cloud Trace.

Acessar traces no Trace Explorer

Para acessar traces e períodos usando o Trace Explorer, siga estas etapas:

1. No console do Google Cloud , acesse a página Análise de traces.

   Acessar o Explorador de traces

2. Selecione o projeto do Google Cloud em que o app do Gemini Enterprise foi criado. Você vê todos os períodos do projeto.

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 Trace Explorer, consulte Encontrar e explorar traces.

   

Filtrar e pesquisar traces

No Trace Explorer 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 raiz de turno do usuário ou pesquise períodos filhos, como execute_tool <tool_name> e invoke_connector <connector>.
• Pesquisa direta de ID de trace: encontre traces diretamente usando o ID de trace padrão do W3C de 32 caracteres, que pode ser extraído dos cabeçalhos de resposta x-cloud-trace-context do StreamAssist.
• Atributos personalizados: consulte pelo atributo gemini_enterprise.assist_token em períodos execute_tool ou invoke_connector para mapear tokens de assistência legados no nível da vez para o waterfall de trace do W3C.
• Atributos de recurso: cada período exportado carrega cloud.region, onome do serviço, e , o namespace do serviço.
• Atributos de recurso: cada período exportado carrega o atributo cloud.region. Esse atributo representa o local de veiculação do Gemini Enterprise que processou a solicitação, como global, us ou eu. É possível filtrar por esse atributo para comparar o desempenho entre regiões. Essa comparação é útil quando um conector de dados funciona em um local, mas falha em outro. Esse valor representa o local que veicula 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.

Traces de acesso para agentes

Também é possível ver 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 Core Assistant, os agentes criados por funcionários do Workflow Builder e os agentes do Deep Research.

Para acessar os traces de um agente:

1. No console do Google Cloud , 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, exibe Não definido).
• ID do período do trace: o identificador exclusivo do período do trace. Clique no link do ID do período para ver 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:
  • 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 de 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 necessário para concluir o período do trace (em minutos).
• Entrada: os dados de entrada ou a mensagem enviada ao período, se houver.
• Saída: o resultado 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 ser executado.

Visualização detalhada do trace

Clicar em um ID de período do trace abre uma página de detalhes com:

1. Resumo: confira os metadados de referência, incluindo Horário de início, Duração e contagem total de Períodos. Clique em Ver no Cloud Trace ou alterne 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 que mostra as relações pai-filho de todos os períodos de trace.
3. Detalhes do período selecionado: selecione um único período para exibir seções detalhadas, que podem incluir:
   • Resumo: mostra o nome do período, o serviço de destino, a contagem total de períodos com essa ação e a duração total (em segundos).
   • Registros: confira detalhes relevantes do evento, se configurados. Clique em Ver registros para acessar diretamente os registros padrão.
   • Avaliação: mostra os resultados da avaliação, se configurados.
   • 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 do W3C ajuda a identificar exatamente onde ocorrem latência ou erros:

1. /AssistantService.StreamAssist: período da plataforma raiz em C++ 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 experimental de convenção semântica de IA generativa

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 em estágio inicial que podem mudar ou ser removidas e não devem ser usadas em 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 de comandos e respostas em períodos de trace (como texto de comando e respostas geradas) só aparece quando as configurações de observabilidade permitem a geração de registros de entradas de comandos e saídas de respostas. Caso contrário, o conteúdo será editado ou omitido. Para mudar essas configurações, consulte Gerenciar configurações de observabilidade.