Para conferir uma representação agregada dos seus dados de trace ou encontrar e analisar traces individuais ou que contêm rótulos específicos, use a página Trace Explorer.
Esse recurso só é compatível com projetos do Google Cloud.
Sobre a página Explorador de traces
Para ajudar 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 extensões em uma célula. Uma célula com muitas extensões é mostrada com uma cor mais escura do que uma célula com poucas extensões. Você pode selecionar uma célula ou ativar a dica de ferramenta dela para conferir mais informações. As outras visualizações permitem que você confira a latência como um percentil e informações sobre a taxa de intervalo. Em todas as visualizações, é possível usar o ponteiro para expandir o eixo x. Para gráficos de linhas, é possível expandir os eixos x e y.
Ao investigar um problema, é possível conferir um rastro específico ou apenas períodos com determinadas propriedades:
Quando você souber o ID de um trace, na barra de ferramentas, clique em pageview Search for trace e insira o ID do trace na caixa de diálogo. Em seguida, você pode pesquisar as extensões e os atributos no rastro para encontrar palavras-chave .
Ao visualizar os dados agregados, você pode 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, adicione um segundo filtro que limite a exibição a intervalos de um serviço específico que informa um erro.
Os dados tabulares permitem conferir detalhes de intervalos individuais e ajudam a identificar outliers. Por exemplo, para encontrar o intervalo com o valor de latência mais alto, 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 de período e selecione a guia Agrupado, que mostra 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 trace mostrados pela página Trace Explorer dependem dos seguintes fatores:
- Os projetos pesquisaram dados de trace. Por padrão, apenas o projeto selecionado pelo seletor de projetos é pesquisado para dados de trace. No entanto, é possível configurar a página para pesquisar a lista de projetos em um escopo de trace.
- Suas permissões de gerenciamento de identidade e acesso (IAM) nos projetos pesquisados. Se você não tiver permissão para visualizar dados de rastreamento 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 do 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 trace usando o console do Google Cloud e selecionar um escopo de trace,
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 trace usando o console do Google Cloud e selecionar um escopo de trace. 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 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.
Conferir dados de trace agregados
Para conferir as informações agregadas sobre seus dados de trace, faça o seguinte:
-
No console do 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 trace forem gravados em um projeto do Google Cloud para que eles fiquem disponíveis para visualização. Se nenhum dado de rastreamento for exibido após alguns minutos, o projeto pode não ter dados para exibir ou pode haver um problema de configuração. Para saber como resolver esses problemas, consulte Resolver problemas: nenhum dado na interface de rastreamento.
Na barra de ferramentas do console do Google Cloud, selecione seu projeto.
Opcional: configure quais projetos são pesquisados para dados de rastreamento usando o elemento Scope:
Para mostrar os dados de rastreamento armazenados no projeto, defina o primeiro menu do elemento Scope como
Project ou
_Default. Essas duas configurações são equivalentes.
Para mostrar os dados de trace armazenados em vários projetos, expanda o primeiro menu do elemento Escopo, selecione Escopo do trace e selecione o escopo do trace que lista esses projetos. Depois de fazer a seleção, o menu Escopo mostra um ícone de escopo do trace,
, e o nome do escopo do trace selecionado.
Os dados retornados dependem das suas funções do IAM nos projetos pesquisados. Por exemplo, se os projetos pesquisados incluem um projeto do Google Cloud a que você não tem acesso, nenhum dado de rastreamento desse projeto será retornado.
Para mais informações, consulte Criar e gerenciar escopos de rastreamento.
Opcional: atualize o período usando o seletor de período ou o ponteiro para destacar um intervalo no eixo x.
Analise os gráficos, que mostram padrões e tendências nos dados de rastreamento:
Para receber 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 extensões. Para informações sobre uma célula, use o ponteiro. A dica de ferramenta mostra o número de extensões, a data e a hora e o intervalo de tempo da célula.
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 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 spans sendo enviados para seu projeto.
Analise os dados em tabela que listam spans individuais na guia Spans e spans agrupados por serviço e nome na guia Agrupado.
Cada linha nas tabelas mostra um período ou grupo, 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 extensões no grupo.
Para encontrar valores discrepantes, selecione um cabeçalho de coluna para classificar a tabela.
Adicione filtros para restringir os períodos exibidos. Por exemplo, você pode filtrar por nome do serviço e status. Quando você adiciona ou remove um filtro, os dados exibidos pela página Trace Explorer são atualizados e mostram apenas os intervalos que correspondem a todos os filtros aplicados.
Para mudar as configurações do filtro, faça o seguinte:
Acesse o painel Filtros de intervalo e selecione os filtros a serem aplicados.
O painel Filtros de span lista apenas os filtros mais comuns. Se você quiser filtrar por um atributo que não está listado, use a barra Filtrar.
Para adicionar um filtro usando a barra Filtro, selecione Adicionar filtro e preencha a caixa de diálogo.
Para filtrar por um atributo que não está listado no menu de opções, selecione Adicionar filtro de atributo e adicione a chave e o valor personalizados. Por exemplo, se você definir a chave como
/http/status_code
e o valor como200
, o filtro será/http/status_code: 200
. Para que o filtro corresponda a qualquer valor, selecione Qualquer valor.
Encontrar um trace por ID
Ao resolver um incidente ou falha, você pode saber o ID do rastro. Para analisar esse trace, faça o seguinte:
-
No console do 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.
- Na barra de ferramentas do console do Google Cloud, selecione seu projeto.
Acesse a barra de ferramentas, clique em pageview Search for trace e insira o ID do trace.
Quando você insere um ID válido, o menu suspenso Details é aberto e mostra informações sobre o trace e os períodos dele. Você pode usar as opções nesse painel para explorar o rastro. Por exemplo, você pode pesquisar os intervalos de palavras-chave.
Analisar um rastro
Para conferir um trace ou período, faça o seguinte:
-
No console do 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 trace forem gravados em um projeto do Google Cloud para que eles fiquem disponíveis para visualização. Se nenhum dado de rastreamento for exibido após alguns minutos, seu projeto pode não ter dados para exibir ou pode haver um problema de configuração. Para saber como resolver esses problemas, consulte Resolver problemas: nenhum dado na interface de rastreamento.
Na barra de ferramentas do console do Google Cloud, selecione seu projeto.
Escolha uma destas opções:
Acesse a seção de tabela da página Trace Explorer e selecione uma entrada na tabela que lista spans ou informações de resumo depois de agrupar os dados por serviço e nome de span.
Acesse a barra de ferramentas da página Trace Explorer, clique em pageview Search for trace e insira o ID do trace.
O painel suspenso Detalhes é aberto e mostra um trace e os períodos dele:
- 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
service.name
do OpenTelemetry, quando esse atributo é 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 de latência vermelha indica que ocorreu um erro.
- Um círculo em uma barra de latência indica que uma entrada de registro ou evento está associada à extensão. Para mudar esse comportamento, use o menu Registros e eventos.
Opcional: use o campo Find in Trace para pesquisar o nome do intervalo, do serviço e dos atributos em um trace.
Por exemplo, se você digitar
GET
, o texto no nome do span, do serviço ou no painel Atributos que mostraGET
, ignorando maiúsculas e minúsculas, será realçado.Não é possível pesquisar usando uma expressão regular nem pesquisar registros, eventos ou metadados.
Para conferir os detalhes de um período específico, selecione o período e confira os atributos e eventos. Consulte a próxima seção para mais informações.
Acessar atributos e eventos
Esta seção descreve como visualizar rótulos, registros e eventos.
Ver marcadores
Para conferir os rótulos anexados ao período, acesse a guia Atributos. Para informações sobre rótulos, consulte Rótulos de trace.
Conferir registros e eventos
Para conferir os registros e eventos relacionados ao período, acesse a guia Registros e eventos. Para informações sobre anotações de eventos, consulte Como anotar períodos de rastreamento.
Para conferir uma entrada de registro, clique em keyboard_arrow_down Mostrar mais.
Você também pode selecionar o botão View logs, que abre a página "Logs Explorer" com a consulta definida para filtrar um rastro, um período e um intervalo de tempo específicos. Essa consulta pode não retornar entradas de registro.
Conferir eventos de IA generativa
Para conferir 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,
resultando em mensagens com nomes que começam com gen_ai
.
Os 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 para o qual a solicitação é enviada.
Os eventos com nome que começa com "gen_ai" geralmente descrevem entradas ou saídas individuais de um sistema de IA generativa. Essas entradas e saídas incluem solicitações do sistema e do usuário, entradas e saídas de ferramentas e respostas de modelos. 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 normalmente não são vistas pelo usuário final e que orientam a interpretação do comando do usuário pelo modelo.gen_ai.user.message
: um evento que registra o comando fornecido pelo usuário que foi 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 de candidato são usadas pelo aplicativo.
Conferir stack traces
Para conferir os stacktraces, use a guia Stacktraces.
Conferir informações gerais e outros metadados
Para encontrar informações gerais sobre o intervalo e uma tabela de links para outros intervalos, acesse a guia Metadados e links. Essas informações incluem o seguinte:
- ID do período: o 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 outras extensões
Cada linha na tabela chamada Links lista um link entre o período atual
e outro. O campo Atributos lista os pares de chave-valor para
a extensão vinculada. O campo Trace é vinculado ao trace do período vinculado. Quando esse campo contém Trace atual, o
intervalo vinculado está no mesmo trace que o intervalo atual. Caso contrário,
o campo contém um ID de rastreamento. Para saber mais sobre links, consulte a
página de referência da API Links
.
A seguir
- Criar e gerenciar escopos de rastreamento
- Adicionar anotações de eventos a intervalos de rastreamento
- Compartilhar traces e períodos
- Criar e visualizar relatórios
- Resolver problemas