Encontrar e analisar rastros

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

Sobre a página Explorador de traces

Para ajudar 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, que é a visualização padrão, usa cores para representar o número de extensões em uma célula. Uma célula com muitas extensões é mostrada com uma cor mais escura do que uma célula com poucas extensões. Você pode selecionar uma célula ou ativar a dica de ferramenta dela para conferir mais informações. As outras visualizações permitem que você confira a latência como um percentil e informações sobre a taxa de intervalo. Em todas as visualizações, é possível usar o ponteiro para expandir o eixo x. Para gráficos de linhas, é possível expandir os eixos x e y.

Ao investigar um problema, é possível conferir um rastro específico ou apenas períodos com determinadas propriedades:

  • Quando você souber o ID de um trace, na barra de ferramentas, clique em Search for trace e insira o ID do trace na caixa de diálogo. Em seguida, você pode pesquisar as extensões e os atributos no rastro para encontrar palavras-chave .

  • Ao visualizar os dados agregados, você pode pesquisar intervalos específicos aplicando filtros. Por exemplo, é possível filtrar os dados para mostrar apenas os intervalos de um serviço específico. Em seguida, adicione um segundo filtro que limite a exibição a intervalos de um serviço específico que informa um erro.

Os dados tabulares permitem conferir detalhes de intervalos individuais e ajudam a identificar outliers. Por exemplo, para encontrar o intervalo com o valor de latência mais alto, selecione a guia Intervalos e classifique os dados por latência. Para encontrar os serviços que estão gerando erros, filtre os dados por status de período e selecione a guia Agrupado, que mostra dados agregados por período e nome do serviço. Cada linha na tabela contém um link para informações detalhadas.

Os dados de trace mostrados pela página Trace Explorer dependem dos seguintes fatores:

  • Os projetos pesquisaram dados de trace. Por padrão, apenas o projeto selecionado pelo seletor de projetos é pesquisado para dados de trace. No entanto, é possível configurar a página para pesquisar a lista de projetos em um escopo de trace.
  • Suas permissões do Identity and Access Management (IAM) nos projetos pesquisados. Se você não tiver permissão para visualizar dados de rastreamento de um projeto, o console do Google Cloud vai mostrar uma mensagem de aviso e os dados desse projeto não serão exibidos.
  • A configuração do 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 trace usando o console do Google Cloud e selecionar um escopo de trace, peça ao administrador para conceder a você o Papel do IAM de usuário do Cloud Trace (roles/cloudtrace.user) no 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 trace usando o console do Google Cloud e selecionar um escopo de trace. 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 trace usando o console do Google Cloud e selecionar um escopo de trace:

  • Para selecionar um escopo de trace: 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.

Conferir dados de trace agregados

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

  1. No console do 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 trace forem gravados em um projeto do Google Cloud para que eles fiquem disponíveis para visualização. Se nenhum dado de rastreamento for exibido após alguns minutos, seu projeto pode não ter dados para exibir ou pode haver um problema de configuração. Para saber como resolver esses problemas, consulte Resolver problemas: nenhum dado na interface de rastreamento.

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

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

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

    Os dados retornados dependem das suas funções do IAM nos projetos pesquisados. Por exemplo, se os projetos pesquisados incluem um projeto do Google Cloud a que você não tem acesso, nenhum dado de rastreamento desse projeto será retornado.

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

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

  4. Analise os gráficos, que mostram padrões e tendências nos dados de rastreamento:

    • Para receber informações sobre dados de latência de período, defina o menu Visualização de gráfico como Duração do período (mapa de calor). A intensidade da cor é proporcional ao número de extensões. Para informações sobre uma célula, use o ponteiro. A dica de ferramenta mostra o número de extensões, a data e a hora e o intervalo de tempo da célula.

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

    • Para conferir o status da resposta como uma função do tempo, defina o menu Visualização de gráfico como Taxa de intervalo. O gráfico mostra a taxa de spans sendo enviados para seu projeto.

  5. Analise os dados em tabela que listam spans individuais na guia Spans e spans agrupados por serviço e nome na guia Agrupado.

    Cada linha nas tabelas mostra um período ou grupo, além de um link para informações detalhadas e algumas métricas. Por exemplo, na guia Agrupado, as métricas incluem a taxa de erro e o número de extensões no grupo.

    Para encontrar valores discrepantes, selecione um cabeçalho de coluna para classificar a tabela.

  6. Adicione filtros para restringir os períodos exibidos. Por exemplo, você pode filtrar por nome do serviço e status. Quando você adiciona ou remove um filtro, os dados mostrados pela página Trace Explorer são atualizados e só mostram os intervalos que correspondem a todos os filtros aplicados.

    Para mudar as configurações do filtro, faça o seguinte:

    • Acesse o painel Filtros de intervalo e selecione os filtros a serem aplicados.

      O painel Filtros de span lista apenas os filtros mais comuns. Se você quiser filtrar por um atributo que não está listado, use a barra Filtrar.

    • Para adicionar um filtro usando a barra Filtro, selecione Adicionar filtro e preencha a caixa de diálogo.

      Para filtrar por um atributo que não está listado no menu de opções, selecione Adicionar filtro de atributo e adicione a chave e o valor personalizados. Por exemplo, se você definir a chave como /http/status_code e o valor como 200, o filtro será /http/status_code: 200. Para que o filtro corresponda a qualquer valor, selecione Qualquer valor.

Encontrar um trace por ID

Ao resolver um incidente ou falha, você pode saber o ID do rastro. Para analisar esse trace, faça o seguinte:

  1. No console do 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.

  2. Acesse a barra de ferramentas, clique em Search for trace e insira o ID do trace.

    Quando você insere um ID válido, o menu suspenso Details é aberto e mostra informações sobre o trace e os períodos dele. Você pode usar as opções nesse painel para explorar o rastro. Por exemplo, você pode pesquisar os intervalos para encontrar palavras-chave.

Analisar um rastro

Para conferir um trace ou período, faça o seguinte:

  1. No console do 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 trace forem gravados em um projeto do Google Cloud para que eles fiquem disponíveis para visualização. Se nenhum dado de rastreamento for exibido após alguns minutos, seu projeto pode não ter dados para exibir ou pode haver um problema de configuração. Para saber como resolver esses problemas, consulte Resolver problemas: nenhum dado na interface de rastreamento.

  2. Escolha uma destas opções:

    • Acesse a seção de tabela da página Trace Explorer e selecione uma entrada na tabela que lista spans ou informações de resumo depois de agrupar os dados por serviço e nome de span.

    • Acesse a barra de ferramentas da página Trace Explorer, clique em Search for trace e insira o ID do trace.

    O painel suspenso Detalhes é aberto e mostra um trace e os períodos dele:

    • A coluna Nome mostra a hierarquia de chamadas, e a primeira entrada inclui o ID do rastreamento.
    • A coluna Serviço é extraída do atributo service.name do OpenTelemetry, quando esse atributo é 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 de latência 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 à extensão. Para mudar esse comportamento, use o menu Registros e eventos.

  3. Opcional: use o campo Find in Trace para pesquisar o nome do intervalo, do serviço e dos atributos em um trace.

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

    Não é possível pesquisar usando uma expressão regular nem pesquisar registros, eventos ou metadados.

  4. Para conferir os detalhes de um período específico, selecione-o e faça o seguinte:

    1. Para conferir os rótulos anexados ao período, acesse a guia Atributos. Para informações sobre rótulos, consulte Rótulos de trace.

    2. Para conferir os registros e eventos relacionados ao período, acesse a guia Registros e eventos. Para informações sobre anotações de eventos, consulte Como anotar períodos de rastreamento.

      Para conferir uma entrada de registro, clique em Mostrar mais.

      Você também pode selecionar o botão View logs, que abre a página "Logs Explorer" com a consulta definida para filtrar um determinado intervalo, período e intervalo de tempo. Essa consulta pode não retornar nenhuma entrada de registro.

    3. Para conferir os stacktraces, use a guia Stacktraces.

    4. Para encontrar informações gerais sobre o intervalo e uma tabela de links para outros intervalos, acesse a guia Metadados e links. Essas informações incluem o seguinte:

      • ID do período: o 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 outras extensões

      Cada linha na tabela chamada Links lista um link entre o período atual e outro. O campo Atributos lista os pares de chave-valor para a extensão vinculada. O campo Trace é vinculado ao trace do período vinculado. Quando esse campo contém Trace atual, o intervalo vinculado está no mesmo trace que o intervalo atual. Caso contrário, o campo contém um ID de rastreamento. Para saber mais sobre links, consulte a página de referência da API Links.

A seguir