Encontrar e analisar traces

Na página Explorador de traces, é possível conferir tendências de latência agregada, filtrar dados do Cloud Trace e inspecionar traces e intervalos individuais para resolver problemas de gargalos de performance e erros. Por padrão, a página Buscador de trace consulta os dados de trace armazenados no seu projetoGoogle Cloud . No entanto, é possível configurar a página para consultar dados de rastreamento armazenados em vários projetos.

Para realizar uma análise agregada personalizada dos seus períodos usando SQL, use a página Análise de Observabilidade ou o BigQuery. Na página Análise de observabilidade, é possível conferir os resultados da consulta como uma tabela ou um gráfico. Para informações sobre como usar SQL para consultar dados de trace, consulte Consultar e analisar traces.

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 cada célula mostra a latência e outras informações. Você também pode conferir percentis de latência e informações sobre a taxa de intervalos.

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

Ao investigar um problema, talvez você queira ver um rastreamento específico ou apenas períodos 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 rastreamento específico, use a opção Pesquisar rastreamento visualização de página 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 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 trace exibidos na página do Explorador de traces dependem do seguinte:

• A configuração Escopo, que determina quais visualizações o sistema pesquisa para dados de rastreamento. 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 a visualização _AllSpans do projeto. Essa visualização fornece acesso de leitura a todos os dados de rastreamento armazenados pelo projeto.

  É possível criar escopos de rastreamento que permitem consultar dados armazenados em vários projetos. Para mais informações, consulte Ver rastreamentos em vários projetos.

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

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 do Google Cloud antes que eles estejam 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 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 _Padrão. 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 sua seleção, o menu Escopo mostra um ícone de escopo de rastreamento, , e o nome do escopo de rastreamento selecionado.

      Os dados exibidos dependem dos seus papéis do IAM nas visualizações pesquisadas. Por exemplo, se você não tiver as permissões necessárias para acessar 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, defina 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.

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

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

4. Analisar percentis de latência e taxas de erro:

   • Para conferir as tendências de latência, defina o menu Visualização do 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 períodos 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 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 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 e mostra o período no contexto do rastreamento. Em seguida, explore o período e o trace.

6. Para restringir os períodos mostrados, adicione filtros. Para informações sobre como filtrar os dados de rastreamento, consulte a próxima seção.

Filtrar dados de rastreamento

Para mostrar apenas as informações relevantes, 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 intervalos que correspondem a todos os filtros aplicados.

Filtrar por ID de rastreamento

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.

Dica: se você inserir um ID de rastreamento válido, mas o resultado estiver vazio, talvez o rastreamento esteja armazenado em um projeto que não está sendo pesquisado. Para resolver essa falha, identifique o projeto que armazena o rastreamento e atualize a configuração de Escopo.

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.

Se você inserir um ID de rastreamento que não for encontrado, os dados poderão estar armazenados em uma visualização que não é pesquisada pela página Explorador de rastreamentos ou você pode não ter um papel do IAM que permita ver 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 lista a visualização padrão do projeto para dados de rastreamento. Para mais informações, consulte Configurar quais visualizações o Explorador de rastreamentos pesquisa.

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 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 período 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 período: descreve as relações entre períodos. Para mais informações sobre os valores, consulte a documentação do OpenTelemetry SpanKind.
• 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 Filtro 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 das seguintes 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

É possível filtrar os dados de rastreamento por um aplicativo, uma carga de trabalho ou um serviço do App Hub quando esses dados contêm os seguintes atributos de recurso:

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

Esses atributos são gerados pela instrumentação que você adiciona aos aplicativos.

Na página Explorador de rastreamentos, use os seguintes menus de Filtros de extensão para restringir as extensões por aplicativo, serviço ou 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 traces. Para informações sobre essas etapas, consulte Ver dados de rastreamento 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. Você pode aplicar filtros para restringir os períodos mostrados nas tabelas.

   • Acesse a barra de ferramentas da página Explorador de traces, clique em pageview Pesquisar trace e insira o ID do trace.

     O menu suspenso 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:

     

     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 informações sobre essas guias, consulte Ver atributos, entradas de registro e eventos.

     Os elementos da linha do tempo são dinâmicos. Selecione um período para conferir os atributos, entradas de registro e eventos.

Analisar 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 o nome de um serviço ou de uma carga de trabalho. O sistema define esse valor usando o atributo 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 conferir a hierarquia de chamadas como um gráfico acíclico dirigido (DAG), selecione Gráfico na barra de ferramentas:

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, qualquer correspondência sem diferenciação de maiúsculas e minúsculas para GET nos campos Nome, Serviço/carga de trabalho e Atributos será destacada.

Ver atributos, entradas de registro e eventos

O menu 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 da IA generativa.

• Atributos: lista os atributos anexados a 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 rastreamento.

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

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

• Stacktraces: lista os stacktraces disponíveis.

• Metadados e links: lista informações gerais, informações sobre o escopo da instrumentação e links para o esquema.

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

  • ID do intervalo: um número inteiro de 64 bits diferente de 0. 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 intervalo está vinculado a outro intervalo 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.

O menu suspenso Detalhes também pode 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 GenAI 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.

  • 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 informações sobre configurações compatíveis, consulte Coletar e visualizar comandos e respostas multimodais.

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

    

    Para informações 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 ver 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 períodos 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, algo semelhante a roll_dice.

Para informações sobre os servidores MCP do Google Cloud que geram rastreamentos e como configurar seu aplicativo para instruir os servidores MCP a gerar intervalos, consulte Investigar chamadas do MCP usando o Trace.

A seguir

• Mostrar dados de rastreamento em um painel personalizado
• Criar e gerenciar escopos de rastreamento
• Compartilhar traces e períodos
• Resolver problemas