Encontrar e analisar rastros

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.

Esse recurso só é compatível com projetos Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

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

Ao investigar um problema, talvez você queira ver um rastreamento específico ou apenas períodos com determinadas propriedades:

• Quando você souber o ID de um trace, clique em pageview Pesquisar trace na barra de ferramentas e insira o ID do trace na caixa de diálogo. Em seguida, você pode pesquisar intervalos e atributos no rastreamento por palavras-chave .

• Ao visualizar os dados agregados, é possível 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, você pode adicionar um segundo filtro que limita a exibição a intervalos de um serviço específico que informa um erro.

Os dados tabulares permitem ver detalhes de intervalos individuais e ajudam a identificar outliers. Por exemplo, para encontrar o intervalo com o maior valor de latência, 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 do período e selecione a guia Agrupada, que mostra os 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 rastreamento mostrados na página do Explorador de rastreamento dependem do seguinte:

• Os projetos pesquisados para dados de rastreamento. Por padrão, apenas o projeto selecionado pelo seletor de projetos é pesquisado para dados de rastreamento. 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 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 do IAM de Usuário do Cloud Trace (roles/cloudtrace.user) 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. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

3. 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 vai mostrar um ícone de escopo de rastreamento, , e o nome do escopo de rastreamento selecionado.

   Os dados retornados dependem das suas funções 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.

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

5. Acesse a barra de ferramentas e defina o seletor de período como pelo menos duas semanas. Dados de intervalo armazenados por 30 dias.

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

   • Para 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 intervalos. Para informações sobre uma célula, use o ponteiro. A dica de ferramenta mostra o número de períodos, a data e a hora e o intervalo de tempo da célula.

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

7. Analise os dados tabulares que listam intervalos individuais na guia Intervalos e intervalos agrupados por serviço e nome na guia Agrupados.

   Cada linha nas tabelas mostra um período ou agrupamento, 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 intervalos no grupo.

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

8. Adicione filtros para restringir os períodos exibidos. 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 Trace Explorer são atualizados e mostram apenas os períodos que correspondem a todos os filtros aplicados.

Para mudar as configurações de filtro, use o painel Filtros de período ou a barra Filtrar.

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 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 intervalo: descreve as relações entre intervalos. 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 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.

Encontrar um rastreamento por ID

Ao resolver um incidente ou falha, talvez você saiba o ID do rastreamento. Para analisar esse 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.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

3. Acesse a barra de ferramentas, clique em pageview 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.

Explorar um trace

Para ver um rastreamento ou período, 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. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.

3. Escolha uma destas opções:

   • Acesse a seção de tabela da página Explorador de rastreamentos e selecione uma entrada na tabela que lista intervalos ou informações de resumo após agrupar os dados por serviço e nome do intervalo.

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

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

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

4. Opcional: pesquise o nome do intervalo, o nome do serviço e os atributos em um rastreamento usando o campo Encontrar no rastreamento.

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

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

5. Para conferir os detalhes de um período específico, selecione-o e veja os atributos e eventos dele. Consulte a próxima seção para mais informações.

Ver atributos e eventos

Nesta seção, descrevemos como visualizar rótulos, registros e eventos.

Ver marcadores

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

Ver informações do aplicativo

Os seguintes atributos de recursos específicos do aplicativo podem ser anexados a dados de rastreamento. Nesta seção, interprete a.b.{x,y} como a.b.x e a.b.y:

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

Para encontrar os dados de rastreamento do seu aplicativo, 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.

2. Acesse o painel Filtros de extensão e adicione filtros para seu aplicativo do App Hub:

   • Para filtrar pelo ID do aplicativo (gcp.apphub.application.id), use o menu Aplicativo do App Hub.
   • Para filtrar por um serviço de aplicativo (gcp.apphub.service.id), use o menu Serviço do App Hub.
   • Para filtrar por uma carga de trabalho de aplicativo (gcp.apphub.workload.id), use o menu Carga de trabalho do App Hub.

Os atributos de recursos específicos do aplicativo são anexados aos dados de rastreamento quando as seguintes condições são verdadeiras:

• Seus aplicativos do App Hub usam recursos Google Cloud compatíveis.
• Você instrumenta um aplicativo com o OpenTelemetry e envia os dados de rastreamento coletados do seu aplicativo para o projeto usando o endpointGoogle Cloud OTLP.
• Os dados enviados ao seu projeto incluem atributos de recursos do OpenTelemetry que identificam os recursos Google Cloud compatíveis usados pelo seu aplicativo. Os atributos precisam incluir o seguinte:
  • cloud.account.id
  • Um de cloud.{availability_zone,region}

  • Atributos específicos de recursos. Por exemplo, para uma carga de trabalho do Kubernetes, os intervalos precisam ter o k8s.cluster.name, o k8s.namespace e o tipo de implantação do Kubernetes definidos.

    É possível usar processadores para que o coletor do OpenTelemetry anexe atributos específicos do recurso aos seus intervalos. Para saber mais, consulte resourcedetectionprocessor e k8sattributesprocessor.

  Quando você instrumenta um aplicativo, o Google Cloud Observability usa os atributos de recurso anteriores e a API App Hub para identificar seu aplicativo do App Hub. Os rótulos específicos do aplicativo são adicionados aos dados de rastreamento quando um aplicativo é identificado.

Para mais informações sobre esses atributos, consulte Convenções semânticas do App HubGoogle Cloud .

Ver registros e eventos

Para conferir os registros e eventos relacionados ao período, acesse a guia Registros e eventos.

Para ver uma entrada de registro, clique em keyboard_arrow_down Mostrar mais.

Você também pode selecionar o botão Ver registros, que abre a página do Explorador de registros com a consulta definida para filtrar um rastreamento, intervalo e período específicos. Essa consulta pode não retornar entradas de registro.

Conferir eventos de IA generativa

Para ver eventos relacionados a agentes de IA generativa, use a guia GenAI. Essa guia fica disponível quando os períodos enviados ao Trace seguem as Convenções semânticas do OpenTelemetry para sistemas de IA generativa, o que resulta em mensagens cujos nomes começam com gen_ai.

A captura de tela a seguir ilustra como a página do Trace Explorer renderiza eventos de IA generativa:

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

Atributos são pares de chave-valor que descrevem alguma característica. Confira a seguir exemplos de atributos de um sistema de IA generativa:

• gen_ai.system: identifica o sistema que fornece os recursos de IA generativa.
• gen_ai.request.model: identifica o modelo a que a solicitação é enviada.

Os eventos cujo nome começa com "gen_ai" geralmente descrevem entradas ou saídas individuais de um sistema de IA generativa. Essas entradas e saídas incluem comandos do sistema e do usuário, entradas e saídas de ferramentas e respostas do modelo. Confira a seguir exemplos de eventos de um sistema de IA generativa:

• gen_ai.system.message: um evento que registra o comando do sistema enviado a um modelo de IA generativa. O comando do sistema fornece instruções ao modelo que geralmente não são vistas pelo usuário final e que orientam a interpretação do modelo sobre o comando do usuário.
• gen_ai.user.message: um evento que registra o comando fornecido pelo usuário e enviado ao modelo.
• gen_ai.assistant.message: um evento que registra a saída do modelo, que pode incluir o registro de uma invocação de ferramenta ou que pode conter uma saída de resposta textual. Uma mensagem pode incluir respostas candidatas que não são usadas pelo aplicativo.
• gen_ai.choice: um evento usado para informar quais saídas candidatas são usadas pelo aplicativo.

Ver stack traces

Para ver stacktraces, use a guia Stacktraces.

Ver informações gerais e outros metadados

Para encontrar informações gerais sobre o período e uma tabela de links para outros períodos, consulte a guia Metadados e links. Essas informações incluem o seguinte:

• 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

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

Ver tendências

Depois de implantar uma atualização em um aplicativo, talvez você queira determinar se ela afetou a latência de resposta. Para conferir tendências nos dados de latência, defina o seletor de período para que os dados de latência sejam mostrados antes e depois do upgrade.

Para conferir tendências nos 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.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta com app ativado.
3. Opcional: adicione filtros para configurar os períodos mostrados.
4. Acesse a barra de ferramentas e defina o seletor de período como pelo menos duas semanas. Os dados de intervalo são armazenados por 30 dias.
5. Opcional: mude a seleção no menu Visualização de gráfico.

A seguir

• Criar e gerenciar escopos de rastreamento
• Compartilhar traces e períodos
• Resolver problemas