Encontrar e analisar traces

Para ver uma representação agregada dos dados de trace ou encontrar e analisar traces individuais ou que contêm rótulos específicos, use a página Explorador de traces.

A captura de tela a seguir ilustra como os dados de rastreamento são mostrados:

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

Sobre a página Explorador de traces

Para ajudar você a identificar tendências e padrões nos dados de rastreamento, os dados de latência são agregados e mostrados em gráficos. O mapa de calor usa cores para representar o número de períodos em uma célula. Uma célula com muitos intervalos tem uma cor mais escura do que uma com poucos intervalos. A dica de ferramenta de cada célula mostra a latência e outras informações. Também é possível conferir percentis de latência e informações sobre a taxa de intervalos.

Ao investigar um problema, talvez você queira ver um rastreamento específico ou apenas intervalos com determinadas propriedades:

• Para restringir os períodos mostrados, aplique filtros. Por exemplo, é possível filtrar por serviço, aplicativo, estado de erro e outras propriedades.

• Para mostrar um trace específico, use a opção visualização de página Pesquisar trace da barra de ferramentas.

Para identificar outliers e ver detalhes de intervalos individuais, use a seção tabular:

• É possível classificar as linhas das guias Intervalos e Agrupados pelo cabeçalho de duração.

• Para entender quantos intervalos diferentes serviços estão gerando, use a guia Agrupado. Cada linha corresponde a um serviço e um nome de período, e para cada entrada, as estatísticas de latência são mostradas.

Para conferir os detalhes de um período ou agrupamento, selecione a entrada em uma linha na seção tabular. Um menu suspenso é aberto e mostra o intervalo no contexto do rastreamento. Nessa visualização, você pode explorar o intervalo, os atributos e ver eventos e dados de registro. Você também pode pesquisar os períodos e atributos no rastreamento por palavras-chave.

Os dados de rastreamento que a página Explorador de traces depende do seguinte:

• Os projetos pesquisados para dados de rastreamento. Por padrão, o sistema só pesquisa dados de trace no projeto selecionado pelo seletor de projetos. No entanto, é possível configurar a página para pesquisar a lista de projetos em um escopo de rastreamento.
• Suas permissões do Identity and Access Management (IAM) nos projetos pesquisados. Se você não tiver permissão para ver os dados de rastreamento de um projeto, o console Google Cloud vai mostrar uma mensagem de aviso, e os dados desse projeto não serão exibidos.
• A configuração de período.
• Os filtros que você aplica.

O restante desta página oferece mais informações sobre como encontrar e analisar seus dados de rastreamento.

Antes de começar

Para receber as permissões necessárias para visualizar dados de rastreamento usando o console do Google Cloud e selecionar um escopo de rastreamento, peça ao administrador para conceder a você o papel Usuário do Cloud Trace (roles/cloudtrace.user) do IAM no seu projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para visualizar dados de rastreamento usando o console Google Cloud e selecionar um escopo de rastreamento. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para visualizar dados de rastreamento usando o console Google Cloud e selecionar um escopo de rastreamento:

• Para selecionar um escopo de rastreamento: cloudtrace.traceScopes.[get, list]
• Para ler o escopo de rastreamento padrão: observability.scopes.get

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Para mais informações sobre papéis, consulte Controlar o acesso com o Identity and Access Management.

Visualizar dados agregados de trace

Para conferir as informações agregadas sobre os dados de rastreamento, faça o seguinte:

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

   Acessar o Explorador de traces

   Também é possível encontrar essa página usando a barra de pesquisa.

   Pode levar vários minutos depois que os primeiros dados de rastreamento são gravados em um projeto do Google Cloud para que eles fiquem disponíveis para visualização. Se você não encontrar nenhum dado de rastreamento depois de esperar alguns minutos, talvez o projeto não tenha dados para mostrar ou haja um problema de configuração. Para informações sobre como resolver esses problemas, consulte Resolver problemas: sem dados na interface de rastreamento.

2. Configure a página Explorador de traces:

   1. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.

   2. Opcional: configure quais projetos são pesquisados para dados de rastreamento usando o elemento Escopo:

      • Para mostrar os dados de rastreamento armazenados no seu projeto, defina o primeiro menu do elemento Escopo como Projeto ou _Default. Essas duas configurações são equivalentes.

      • Para mostrar os dados de rastreamento armazenados em vários projetos, expanda o primeiro menu do elemento Escopo, selecione Escopo de rastreamento e escolha o escopo que lista esses projetos. Depois de fazer a seleção, o menu Escopo mostra um ícone de escopo de rastreamento, , e o nome do escopo de rastreamento selecionado.

      Os dados retornados dependem dos seus papéis do IAM nos projetos pesquisados. Por exemplo, se os projetos pesquisados incluírem um projeto Google Cloud a que você não tem acesso, nenhum dado de rastreamento será retornado para ele.

      Para mais informações, consulte Criar e gerenciar escopos de rastreamento.

   3. Opcional: atualize o período usando o seletor ou o ponteiro para destacar um intervalo no eixo x.

      Por exemplo, você pode definir esse seletor como Últimas duas semanas quando quiser saber se há tendências nos dados de latência. Os dados de intervalo são armazenados por 30 dias.

3. Analise o mapa de calor:

   • Use cores para identificar tendências e outliers. Uma célula com muitos intervalos tem uma cor mais escura do que uma com poucos intervalos.

   • Confira os detalhes da célula usando a dica dela. A dica lista o número de períodos, a data e a hora e o intervalo de tempo da célula.

     Observação: se você selecionar uma célula no mapa de calor, a tabela que lista intervalos individuais ou agrupamentos de intervalos será atualizada.

4. Analise os percentis de latência e as taxas de erro:

   • Para ver as tendências de latência, defina o menu Visualização de gráfico como Duração do intervalo (percentil). O gráfico de duração mostra os percentis 50º, 90º, 95º e 99º.

   • Para ver o status da resposta em função do tempo, defina o menu Visualização de gráfico como Taxa de intervalo. O gráfico mostra a taxa de intervalos enviados ao seu projeto.

5. Para encontrar outliers, selecione a guia Intervalos e ordene a tabela por duração.

   Se quiser mais informações sobre um período específico, selecione-o. Um menu suspenso é aberto e mostra o intervalo no contexto do trace. Em seguida, analise o intervalo e o rastreamento.

6. Para conferir o número de intervalos gerados para cada serviço, além de informações estatísticas, selecione a guia Agrupado:

   • Cada linha é para um serviço e um nome de período específicos.
   • É possível classificar as linhas pelo cabeçalho de duração.

   Se quiser mais informações sobre um agrupamento específico, selecione o nome do intervalo de uma linha. Um menu suspenso é aberto, mostrando o intervalo no contexto do trace. Em seguida, analise o intervalo e o rastreamento.

7. Para restringir os períodos mostrados, adicione filtros. Para saber mais sobre como filtrar os dados de rastreamento, consulte a próxima seção.

Filtrar dados de rastreamento

Para mostrar apenas as informações que interessam a você, aplique filtros. Os filtros restringem os dados mostrados. Por exemplo, é possível filtrar por nome e status do serviço. Ou, se você tiver implantado aplicativos no App Hub, talvez queira ver os dados de rastreamento apenas para o aplicativo ou para um serviço ou carga de trabalho específica que faz parte dele.

Quando você adiciona ou remove um filtro, os dados mostrados na página do Trace Explorer são atualizados e mostram apenas os períodos que correspondem a todos os filtros aplicados.

Filtrar um rastreamento por ID

Ao resolver um incidente ou falha, talvez você saiba o ID do rastreamento. Para analisar esse trace, acesse a barra de ferramentas, clique em pageview Pesquisar trace e insira o ID do trace.

Quando você insere um ID válido, o menu suspenso Detalhes é aberto e mostra informações sobre o trace e os períodos dele. Use as opções nesse painel para analisar o rastreamento. Por exemplo, você pode pesquisar palavras-chave nos intervalos.

Observação: se você inserir um ID de rastreamento que não for encontrado, os dados poderão estar armazenados em um projeto que não é pesquisado pela página Explorador de rastreamento ou você não tem um papel do IAM que permita visualizar os dados de rastreamento. Para resolver essas falhas, identifique os projetos que armazenam os dados de rastreamento. Para cada projeto, verifique se sua função do IAM permite visualizar dados de rastreamento e se o elemento Escopo está configurado para pesquisar todos os projetos que armazenam seus dados de rastreamento. Para mais informações, consulte Atualizar a lista de projetos pesquisados para dados de rastreamento.

Aplicar filtros de extensão

O painel Filtros de extensão lista os filtros mais comuns. É possível selecionar várias entradas de qualquer subcategoria. À medida que você adiciona ou remove filtros, a barra Filtrar também é atualizada.

Os valores de todos os menus são derivados dos seus dados de rastreamento. Quando um menu inclui uma opção sem texto, ela se refere a intervalos que não incluem o atributo correspondente.

Os seguintes filtros de extensão estão disponíveis:

• Serviço OpenTelemetry: filtra pelo atributo service.name.
• Nome do período: nome do período.
• Status do período: o status da solicitação. Para informações sobre os valores, consulte a documentação do OpenTelemetry SpanStatus.
• Duração: a duração do período.
• Tipo de intervalo: descreve as relações entre intervalos. Para informações sobre os valores, consulte a documentação do SpanKind do OpenTelemetry.
• Aplicativo do App Hub: filtra pelo atributo de recurso gcp.apphub.application.id.
• Serviço do App Hub: filtra pelo atributo de recurso gcp.apphub.service.id.
• Carga de trabalho do App Hub: filtra pelo atributo de recurso gcp.apphub.workload.id.

Se você quiser filtrar por um atributo que não está listado no painel Filtros de extensão, use a barra Filtro.

Usar a barra de filtro

A barra Filtrar permite aplicar um filtro com uma chave predefinida e um valor selecionado. Também é possível inserir a chave e o valor.

Para adicionar um filtro, selecione Adicionar filtro e faça uma destas ações:

• Selecione uma chave definida, como Nome do intervalo, e escolha um valor no menu secundário.

• Selecione Adicionar filtro de atributo e adicione sua chave e valor personalizados. Se você inserir sua própria chave de filtro, use a mesma sintaxe de uma chave para um atributo em um intervalo.

  Por exemplo, para filtrar pelo identificador do host, defina a chave como host.id. Da mesma forma, para filtrar por código de status, defina a chave como /http/status_code. Nesse cenário, você pode definir o valor como 200, o que resulta no filtro /http/status_code: 200. Para permitir que o filtro corresponda a qualquer valor, selecione Qualquer valor.

Filtrar por app

Os períodos do Trace gerados pela instrumentação adicionada aos seus aplicativos podem incluir os seguintes atributos de recurso:

• gcp.apphub.application.{container,id,location}
• gcp.apphub.{workload,service}.{criticality_type,environment_type,id}

A página Explorador de traces inclui os seguintes filtros de extensão, cujos menus listam aplicativos, serviços e cargas de trabalho registrados no App Hub:

• Aplicativo do App Hub: filtra pelo atributo de recurso gcp.apphub.application.id.
• Serviço do App Hub: filtra pelo atributo de recurso gcp.apphub.service.id.
• Carga de trabalho do App Hub: filtra pelo atributo de recurso gcp.apphub.workload.id.

Para informações sobre como instrumentar seu aplicativo para que os períodos de rastreamento incluam atributos específicos do aplicativo, consulte Instrumentar para o Application Monitoring.

Explorar um trace

Esta seção fornece informações sobre como analisar um intervalo no contexto do rastreamento dele:

1. Abra e configure a página Explorador de traces. Para informações sobre essas etapas, consulte Visualizar dados de rastreamento agregados.

2. Para conferir os detalhes de um período ou um trace, faça o seguinte:

   • Acesse a seção de tabela da página Explorador de traces e selecione uma entrada na seção tabular. É possível classificar as linhas das tabelas por qualquer cabeçalho. É possível aplicar filtros para restringir os períodos mostrados nas tabelas.

   • Acesse a barra de ferramentas da página Trace Explorer, clique em visualização de página Pesquisar trace, e insira o ID do trace.

   O menu suspenso Detalhes é aberto e mostra um trace e seus intervalos. Os detalhes do período ou trace selecionado são mostrados:

   • A coluna Nome mostra a hierarquia de chamadas, e a primeira entrada inclui o ID do rastreamento. Essa coluna também pode incluir anotações que indicam se há eventos de IA generativa ou dados de registro disponíveis.
   • A coluna Serviço é extraída do atributo OpenTelemetry service.name quando ele está definido. Se esse atributo não estiver definido e o serviço estiver em execução no App Engine, o nome do serviço no App Engine vai aparecer. Caso contrário, nenhum serviço será especificado.
   • O comprimento da barra de latência representa o valor da latência.
   • A cor da barra de latência indica o status. Uma barra de latência azul indica uma conclusão bem-sucedida, enquanto uma barra vermelha indica que ocorreu um erro.
   • Um círculo em uma barra de latência indica que uma entrada de registro ou um evento está associado ao intervalo. Para mudar esse comportamento, use o menu Registros e eventos.

3. Para analisar o rastreamento, faça o seguinte:

   • Use o ponteiro para selecionar diferentes intervalos. Quando você seleciona um período, as guias na página são atualizadas para mostrar os atributos, entradas de registro e eventos do período.

   • Para pesquisar intervalos no rastreamento por palavras-chave, use o campo Encontrar no rastreamento.

     A pesquisa se aplica apenas aos campos "Nome do período", "Nome do serviço" e "Atributos". Só é possível pesquisar por texto simples, e não é possível pesquisar registros, eventos ou metadados.

     Por exemplo, se você inserir GET, o texto no nome do intervalo, no nome do serviço ou no painel Atributos que mostra GET, ignorando maiúsculas e minúsculas, será destacado.

   Observação: o Explorador de rastreamentos mostra no máximo 10.000 intervalos para um rastreamento.

Conferir atributos, entradas de registro e eventos

O menu suspenso Detalhes de um intervalo contém uma guia para cada um dos seguintes itens:

• Atributos: essa guia lista os rótulos anexados aos intervalos. Para informações sobre rótulos, consulte Rótulos de trace.

• Registros e eventos: essa guia lista eventos e entradas de registro cujos campos trace_id e span_id correspondem ao período selecionado. Somente as entradas de registro que você tem permissão para ver são mostradas.

  Para conferir uma entrada nessa guia, clique em Mostrar mais.

  Se você preferir usar a página do Explorador de registros para ver os dados de registros, clique em Ver registros. A consulta é definida para filtrar um rastreamento, um intervalo e um período específicos.

  Observação: os eventos de IA generativa são mostrados na guia Entradas/Saídas. Para saber mais, consulte Ver eventos de IA generativa.

• Stacktraces: lista os stacktraces disponíveis.

• Metadados e links: lista informações gerais sobre o período:

  • ID do período: um número inteiro de 64 bits diferente de zero. Para mais detalhes, consulte TraceSpan.
  • ID do período pai.
  • ID do projeto.
  • Horário de início e término.

  • Tabela que lista links para outros intervalos. Para cada link, esta tabela lista o seguinte:

    • Os pares de chave-valor para o intervalo vinculado.
    • O ID do rastreamento do período vinculado. Quando esse campo lista Trace atual, o período está vinculado a outro período no mesmo trace.

    Para informações sobre links, consulte a página de referência da API Links.

Os detalhes também podem incluir uma guia chamada Entradas/Saídas. Essa guia mostra eventos de IA generativa.

Conferir eventos de IA generativa

Pré-lançamento

Este recurso está sujeito aos "Termos da Oferta Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter assistência limitada. Para mais informações, consulte as descrições das fases de lançamento.

Para ver eventos relacionados a agentes de IA generativa, use a guia Entradas/Saídas. Essa guia mostra eventos que seguem as convenções semânticas de IA generativa do OpenTelemetry.

Há duas configurações compatíveis:

• Comandos e respostas baseados em texto anexados aos intervalos como atributos, que são pares de chave-valor que descrevem alguma característica ou um evento. Por exemplo, o valor da chave gen_ai.system identifica o sistema que oferece os recursos de IA generativa. As chaves dos atributos de IA generativa começam com gen_ai.

• Comandos e respostas multimodais armazenados em um bucket do Cloud Storage. O Cloud Trace identifica esses eventos correlacionando seus dados de rastreamento e de registros. Para saber mais sobre as configurações compatíveis, consulte Coletar e visualizar comandos e respostas multimodais.

A captura de tela a seguir ilustra como a página do Trace Explorer renderiza eventos de IA generativa baseados em texto anexados aos intervalos:

Para saber mais sobre o aplicativo de exemplo que gerou a captura de tela anterior, consulte Instrumentar um agente LangGraph ReAct com OpenTelemetry.

A seguir

• Criar e gerenciar escopos de rastreamento
• Compartilhar traces e períodos
• Resolver problemas