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:

Exemplo de exibição de dados de rastreamento.

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 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 seu projeto não tenha dados para mostrar ou haja um problema de configuração. Para saber 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.

  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 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 intervalos enviados ao seu projeto.

  5. Use as tabelas Intervalos e Agrupados para identificar outliers ou ver informações estatísticas. A tabela Períodos lista períodos individuais. A tabela Agrupada agrupa períodos pelo nome e pelo nome do serviço ou da carga de trabalho.

    • Para ver outliers ou encontrar um nome de intervalo, classifique a tabela. É possível classificar por qualquer cabeçalho de coluna.

      Por exemplo, classificar a tabela Intervalos por duração permite encontrar intervalos com alta latência.

    • Para conferir estatísticas como latência média, use a tabela Agrupada.

    • Para encontrar serviços e cargas de trabalho registrados no App Hub, pesquise na coluna Serviço/carga de trabalho entradas que incluem o ícone de serviço, , ou o ícone de carga de trabalho, . O link fornecido com um serviço ou uma carga de trabalho registrada no App Hub abre o painel de monitoramento de aplicativos correspondente.

    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.

  6. 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 Explorador de rastreamentos 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 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.

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 geralmente 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

Para encontrar ou visualizar períodos gerados pelos serviços e cargas de trabalho registrados no App Hub, eles precisam conter os seguintes atributos de recurso:

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

Os atributos de recurso anteriores são gerados pela instrumentação que você adiciona aos seus aplicativos. É possível filtrar os dados de rastreamento por qualquer atributo de recurso. No entanto, os seguintes filtros de intervalo filtram pelos IDs de aplicativo, serviço e carga de trabalho:

  • Aplicativo do App Hub
  • Serviço do App Hub
  • Carga de trabalho do App Hub

Para abrir o painel do monitoramento de aplicativos de um serviço e uma carga de trabalho registrados no App Hub, faça o seguinte:

  1. Acesse a tabela Intervalos ou Agrupados e encontre o serviço ou a carga de trabalho. Procure o ícone do serviço, , o ícone da carga de trabalho, , ou filtre a tabela.

  2. Selecione o link na coluna Serviço/carga de trabalho.

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 Ver 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 Pesquisar trace, e insira o ID do trace.

    O menu pop-up Detalhes é aberto e mostra um trace e os períodos dele.

    Exemplo do painel de detalhes do rastreamento.

    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 os eventos de IA generativa ou os dados de registro estão disponíveis.
    • A coluna Serviço/carga de trabalho mostra o nome de um serviço ou de uma carga de trabalho. Os nomes de serviço são extraídos 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 de nome do período, nome do serviço ou da carga de trabalho 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 nos painéis Nome, Serviço/carga de trabalho e Atributos que mostra GET, ignorando maiúsculas e minúsculas, será destacado.

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.

  • 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 trace do período vinculado. Quando esse campo lista Trace atual, o intervalo está vinculado a outro intervalo no mesmo trace.

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

A guia Detalhes também pode incluir uma guia chamada Entradas/Saídas. Essa guia mostra eventos de IA generativa.

Conferir eventos de IA generativa

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 trace e de registro. 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 generativos de IA baseados em texto anexados aos intervalos:

Exibição de intervalos de rastreamento.

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