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 trace.

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

Exemplo de exibição de dados de rastreamento.

Para executar consultas que realizam uma análise agregada dos seus períodos, use a página Análise de observabilidade ou o BigQuery. As duas interfaces permitem consultar seus dados de período usando SQL. Ao usar a página Análise de observabilidade, é possível conferir os resultados da consulta como uma tabela ou um gráfico. Para saber mais sobre como usar SQL para consultar seus dados de trace, consulte Consultar e analisar traces.

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 trace, 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 períodos tem uma cor mais escura do que uma com poucos períodos. A dica de ferramenta de cada célula mostra a latência e outras informações. Também é possível conferir os percentis de latência e as informações de taxa de período.

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 na 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 períodos diferentes serviços estão gerando, use a guia Agrupada. Cada linha corresponde a um serviço e a um nome de período. 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 período no contexto do trace. Nessa visualização, você pode explorar o período, os atributos e ver eventos e dados de registro. Você também pode pesquisar intervalos e atributos no rastreamento por palavras-chave.

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

  • A configuração Escopo, que determina quais visualizações o sistema pesquisa para dados de trace. Quando a página é aberta, o elemento Escopo é definido como o escopo de trace padrão, e o sistema consulta as visualizações listadas nesse escopo para dados de trace.

    Em um novo projeto, o escopo de rastreamento padrão lista os _AllSpans do projeto. Essa visualização fornece acesso de leitura a todos os dados de rastreamento armazenados pelo projeto.

  • Suas permissões do Identity and Access Management (IAM) na visualização pesquisada. 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.

É possível salvar os dados de rastreamento em um painel personalizado. Para mais informações, consulte Mostrar dados de rastreamento em um painel personalizado.

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

Ver dados de rastreamento agregados

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 Google Cloud antes que esses dados estejam 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 informações sobre como resolver esses problemas, consulte Solução de problemas: não há dados na interface do Trace.

  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 visualizações o sistema pesquisa para dados de rastreamento usando o elemento Escopo:

      • Para mostrar os dados de rastreamento armazenados pelo 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 por vários projetos, expanda o primeiro menu do elemento Escopo, selecione Escopo de rastreamento e escolha o escopo que lista a visualização _AllSpans desses 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 que o sistema mostra dependem dos seus papéis do IAM nas visualizações pesquisadas. Por exemplo, se você não tiver as permissões necessárias para ver os dados em uma visualização, o sistema não vai mostrar esses dados.

      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 período 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.

    • Para ver detalhes da célula, use a dica dela. A dica lista o número de intervalos, 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 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 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. Use as tabelas Períodos e Agrupados para identificar outliers ou ver informações estatísticas. A tabela Períodos lista períodos individuais. A tabela Agrupados agrupa períodos por nome e por serviço ou nome da carga de trabalho.

    • Para ver outliers ou encontrar um nome de período, 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 carga de trabalho registrado 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 período em uma linha. Um menu suspenso vai abrir e mostrar o período no contexto do trace. Em seguida, analise o período e o trace.

  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 do aplicativo ou de 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 períodos.

Aplicar filtros de extensão

O painel Filtros de período 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 período: descreve as relações entre períodos. 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 ou inserir os dois.

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

  • Selecione uma chave definida, como Nome do período, 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 período.

    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 intervalos 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 por instrumentação que você adiciona aos seus aplicativos. É possível filtrar os dados de rastreamento por qualquer atributo de recurso. No entanto, os filtros de intervalo a seguir filtram por 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.

Analisar um trace

Para analisar um período no contexto do rastreamento, faça o seguinte:

  1. Abra e configure a página Explorador de trace. Para mais informações sobre essas etapas, consulte Ver dados de trace agregados.

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

    • Acesse a página Explorador de traces e selecione uma entrada na tabela. É 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 Explorador de traces, clique em Pesquisar trace e insira o ID do trace.

      O menu flutuante Detalhes é aberto e mostra um trace e os períodos dele em um formato de linha do tempo, além de informações sobre o período selecionado:

      Exemplo do painel de detalhes do rastreamento.

      O submenu tem uma tela dividida. Um lado mostra o período no contexto do trace. O outro lado mostra guias que permitem visualizar informações específicas do intervalo, como atributos, metadados e comandos e respostas anexados. Para saber mais sobre essas guias, consulte Ver atributos, entradas de registro e eventos.

      Os elementos da linha do tempo são dinâmicos. Para analisar outro período, selecione-o para conferir os atributos, entradas de registro e eventos.

Explorar a hierarquia de chamadas

Por padrão, a hierarquia de chamadas aparece como uma linha do tempo. A primeira entrada representa o trace, e cada entrada subsequente representa um período. Cada entrada mostra o seguinte:

  • A coluna Nome mostra um nome e um ID de período ou trace. Um ícone de GenAI, , indica que um período inclui eventos ou atributos de IA generativa.
  • A coluna Serviço/carga de trabalho mostra um nome de serviço ou carga de trabalho. O sistema define esse valor usando o atributo do OpenTelemetry service.name. Como alternativa, para serviços do App Engine, o sistema mostra o nome do serviço do App Engine.
  • A cor e o comprimento da barra de latência refletem o status e a duração do comando.
  • Um círculo em uma barra de latência indica que uma entrada de registro ou um evento está associado ao período. Para mudar esse comportamento, use o menu Registros e eventos.

Para ver a hierarquia de chamadas como um gráfico acíclico dirigido (DAG), selecione Gráfico na barra de ferramentas:

Rastreamento mostrando um gráfico acíclico dirigido.

Na visualização de DAG, o nome e a latência aparecem com cada elemento. A cor reflete o status do intervalo. Use a roda de rolagem no ponteiro para mudar o tamanho do gráfico.

Pesquisar os períodos em um trace

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.

Ver atributos, entradas de registro e eventos

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

  • Entradas/saídas: mostra eventos que seguem as convenções semânticas de IA generativa do OpenTelemetry. Essa guia só aparece quando o período contém esses eventos. Para ajudar você a identificar esses períodos, a visualização da linha do tempo mostra um ícone GenAI, , com o nome do período, quando ele contém eventos ou atributos que seguem essas convenções. Para mais informações, consulte Ver eventos e atributos de IA generativa.

  • Atributos: lista os atributos anexados aos intervalos. O Trace Explorer indica quais intervalos contêm atributos de IA generativa mostrando um ícone GenAI, . 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 da Análise 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, informações sobre o escopo de instrumentação e links para o esquema.

    A seção Metadados mostra informações como:

    • 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 período vinculado.
      • O ID do trace 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.

    As seções Escopo de instrumentação e Informações do esquema mostram o nome e a versão do escopo e fornecem links para o esquema. Essas seções são omitidas quando um período não contém essas informações.

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

Conferir eventos de IA generativa

Para identificar períodos que contêm atributos ou eventos consistentes com as convenções semânticas da IA generativa do OpenTelemetry, procure o ícone GenAI, :

  • A guia Atributos mostra os atributos anexados ao período. Para listar apenas os atributos da IA generativa, ative a opção Somente atributos da IA generativa.

  • A guia Entradas/Saídas mostra os eventos que seguem essas convenções e os atributos associados, que também aparecem na guia Atributos. Há duas configurações compatíveis:

    • Comandos e respostas baseados em texto anexados a intervalos como atributos, que são pares de chave-valor que descrevem uma característica ou 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.

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

      A captura de tela a seguir ilustra como a Entradas/Saídas renderiza eventos de IA generativa baseados em texto anexados a intervalos:

      Eventos de IA generativa baseados em texto no explorador de rastreamento.

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

Ver chamadas para servidores MCP remotos

Para conferir os intervalos gerados pelos servidores do MCP, faça o seguinte:

  • Filtre os dados de trace pelo nome do período.

  • Adicione um filtro de atributo cuja chave seja mcp.method.name e cujo valor seja tools/call.

    Esse filtro é específico para encontrar intervalos cujo nome segue as Convenções semânticas do OpenTelemetry para MCP. O nome é semelhante a:

    tools/call NAME

    Na expressão anterior, NAME se refere ao endpoint invocado. Por exemplo, pode ser algo semelhante a roll_dice.

Para saber quais servidores MCP remotos do Google Cloud oferecem suporte à geração de rastreamentos e como configurar seu aplicativo para instruir esses servidores a gerar intervalos, consulte Investigar chamadas de MCP usando o Trace.

A seguir