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 Trace Explorer consulta os dados de trace armazenados no repositório de dados doGoogle Cloud projeto. No entanto, é possível configurar a página para consultar dados de trace armazenados em vários projetos.

Para realizar uma análise agregada personalizada dos períodos usando SQL, use a página Análise de Observabilidade ou o BigQuery. Ao usar a 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 seus dados de trace, consulte Consultar e analisar traces.

Sobre a página Explorador de traces

Para ajudar a identificar tendências e padrões nos dados de trace, os dados de latência são agregados e exibidos 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 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.

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

Ao investigar um problema, talvez você queira ver um trace 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 exibir um trace específico, use a opção visualização de página ID do 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 Períodos e Agrupados pelo cabeçalho de duração.

• Para entender quantos períodos diferentes serviços estão gerando, use a guia Agrupados. Cada linha corresponde a um serviço e nome do 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 de uma linha na seção tabular. Um submenu é aberto e mostra o período no contexto do trace. Nessa visualização, você pode explorar o intervalo, 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 Explorador de traces dependem do seguinte:

• A configuração Escopo, que determina em quais visualizações o sistema pesquisa 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 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 trace que permitem consultar dados armazenados em vários projetos. Para mais informações, consulte Ver traces 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 do 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 Exibir dados de trace 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 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 trace 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 trace agregados

Para ver as informações agregadas sobre os dados de trace, 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. Se você não encontrar nenhum dado de trace exibido depois de esperar alguns minutos, talvez seu projeto não tenha dados para exibir ou talvez haja um problema de configuração. Para saber como resolver esses problemas, consulte Solução de problemas: nenhum dado na interface do Trace.

2. Configure a página Explorador de traces:

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

   2. Opcional: configure as visualizações em que o sistema pesquisa dados de trace usando o elemento Scope:

      • Para mostrar os dados de trace que seu projeto armazena, defina o primeiro menu do elemento Escopo como Projeto ou como _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 exibe um ícone de escopo de trace, , e o nome do escopo de trace 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 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 trace.

   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. Explore o mapa de calor:

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

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

     Dica: 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 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 Períodos e Agrupados para identificar outliers ou visualizar informações estatísticas. A tabela Spans 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, ordene a tabela. É possível classificar por qualquer cabeçalho de coluna.

     Por exemplo, classificar a tabela Períodos por duração permite encontrar períodos 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 você quiser mais informações sobre um agrupamento específico, selecione o nome do período de uma linha. Um submenu vai abrir e mostrar o período no contexto do trace. Em seguida, analise o intervalo e o rastreamento.

6. Para restringir os períodos exibidos, adicione filtros. Para saber como filtrar os dados de trace, consulte a próxima seção.

Filtrar os dados de trace

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 trace

Ao solucionar um incidente ou uma falha, talvez você saiba o ID do trace. Para explorar esse trace, acesse a barra de ferramentas, clique em pageview ID do 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, é possível pesquisar palavras-chave nos períodos.

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 Trace Explorer pesquisa.

Aplicar filtros de período

O painel Filtros de período lista os filtros mais comuns. É possível selecionar várias entradas de qualquer subcategoria. Conforme você adiciona ou remove filtros, a barra Filtro também é atualizada.

Os valores de todos os menus são derivados dos dados de trace. Quando um menu inclui uma opção sem texto, essa opção se refere a períodos 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 os 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 Filtro permite aplicar um filtro com uma chave predefinida e um valor selecionado, ou você pode inserir a chave e o valor.

Para adicionar um filtro, selecione Adicionar filtro e faça uma das seguintes 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

É possível filtrar os dados de trace 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 de recurso são gerados pela instrumentação que você adiciona aos seus 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 de monitoramento de aplicativos de um serviço e carga de trabalho registrados no App Hub, faça o seguinte:

1. Acesse a tabela Períodos ou Agrupados e encontre o serviço ou a carga de trabalho. Procure o ícone de serviço, , o ícone de 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 trace, 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 ver detalhes de um período ou de um trace, 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 pageview ID do 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 intervalo no contexto do rastreamento. 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 ver os atributos, as entradas de registro e os 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 de 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 do OpenTelemetry service.name. Como alternativa, para serviços do App Engine, o sistema exibe 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 do 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 palavras-chave nos períodos do trace, use o campo Localizar no trace.

A pesquisa se aplica apenas ao nome do período, ao nome do serviço ou da carga de trabalho e aos campos de 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 que não diferencia maiúsculas de 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 flutuante 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ó é mostrada 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 de 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 aos períodos. O Trace Explorer indica quais períodos contêm atributos de IA generativa exibindo um ícone de GenAI, . Para mais informações sobre rótulos, consulte Rótulos do 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 visualizar são mostradas.

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

  Se preferir usar a página de Análise de registros para ver os dados de registro, clique em Ver registros. A consulta é definida para filtrar um trace, um período 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.

• Stack traces: lista os stack traces 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 exibe informações como as seguintes:

  • ID do período: o ID do período é 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 períodos. 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 período é 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, além de fornecer links para o esquema. Essas seções são omitidas quando um período não contém essas informações.

O submenu 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 intervalo. 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 são mostrados na guia Atributos. Há duas configurações disponí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 os dados de trace e de registro. Para informações sobre as configurações compatíveis, consulte Coletar e visualizar comandos 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 ReAct do LangGraph 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 traces e como configurar seu aplicativo para instruir os servidores MCP a gerar períodos, consulte Investigar chamadas 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