Encontrar e explorar traces

Para encontrar e explorar traces individuais em detalhes, use a página Explorador de traces. Essa página exibe traces para os quais seu projeto do Google Cloud armazena pelo menos um período. Os dados mostrados para cada trace e período exibidos incluem informações resumidas, como a latência e o tipo de comando, além de informações detalhadas. As informações detalhadas incluem registros, eventos e outras informações.

A página Explorador de traces exibe no máximo 1.000 traces.

Antes de começar

Para receber as permissões necessárias para visualizar os dados de trace usando o console do Google Cloud, 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 como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Para mais informações sobre papéis, consulte Controlar o acesso com o Identity and Access Management.

Mostrar traces recentes

Para exibir os traces mais recentes, faça o seguinte:

No painel de navegação do console do Google Cloud, selecione Trace e, em seguida, Trace Explorer:
Acessar o Explorador de traces

Se esta for a primeira vez que você usa o Trace, pode levar alguns minutos para que os traces apareçam. A captura de tela a seguir mostra um exemplo da página do Explorador de traces:

O gráfico de dispersão exibe um ponto para cada solicitação no intervalo de tempo selecionado:
- As coordenadas (x,y) de uma solicitação correspondem ao tempo e à latência da solicitação.
- As informações de erro são codificadas na cor de um ponto. Azul indica sucesso, e vermelho indica falha. Na captura de tela anterior, a maioria dos comandos foi concluída.
- A dica ativada quando você mantém o ponteiro sobre um ponto mostra a data, a hora, o URI e a latência:
Opcional: para filtrar os traces e os períodos mostrados, siga um destes procedimentos:
- Filtrar por tempo. Por padrão, a hora mais recente dos dados é exibida. Para visualizar um intervalo de tempo personalizado, faça o seguinte:
  1. Selecione uma opção predefinida que seja maior do que o intervalo de tempo personalizado.
  2. Coloque o ponteiro no gráfico Selecionar um rastro em uma extremidade do intervalo de tempo e arraste-o horizontalmente até a outra extremidade do intervalo.
  Para restaurar o gráfico para o intervalo de tempo predefinido, clique em Redefinir.
- Filtrar por latência. Por padrão, todos os traces no intervalo de tempo selecionado são exibidos. Para limitar a exibição aos traces com latência dentro de um intervalo, coloque o ponteiro em uma extremidade do valor de latência e arraste-o verticalmente até a outra extremidade.
  
  Para restaurar o gráfico para o intervalo de tempo predefinido, clique em Redefinir.
- Clique em Adicionar filtro de trace, selecione uma opção de filtro e selecione ou insira um valor de filtro. Se você adicionar vários filtros, somente os traces que satisfazem todos os filtros serão exibidos. Por exemplo, para mostrar todos os traces que contêm um comando HTTP GET e com latência de pelo menos dois segundos, adicione os filtros Method: GET e MinLatency: 2000.
  
  As seguintes opções de filtro estão sempre disponíveis:
  - RootSpan: corresponde ao nome do período raiz.
  - SpanName: corresponde ao nome do período.
  - Método: exibe traces com os períodos raiz que são anotados com o rótulo /http/method, em que o valor do rótulo corresponde ao valor do filtro.
  - Status: exibe traces com os períodos raiz anotados com o rótulo /http/status_code, em que o rótulo de valor corresponde ao valor do filtro. O valor do filtro pode conter códigos de status específicos, como 301, ou intervalos de valores de status, como 3xx.
  - MinLatency: exibe traces com latência pelo menos tão grande quanto o valor do filtro. O valor do filtro precisa estar em milissegundos.
  - HasLabel: exibe traces em que o rótulo especificado pelo valor do filtro aparece em pelo menos um período.
  - Serviço: exibe traces que contêm pelo menos um período com o nome de serviço que corresponde ao valor do filtro.
    
    O nome do serviço de um período é extraído 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 desse serviço será exibido. Caso contrário, o serviço não será especificado.
  - Versão: (somente no App Engine) exibe traces que contêm pelo menos um período com a versão do aplicativo que corresponde ao valor do filtro.
  Você pode ver outras opções de filtro, como URL ou rótulos HTTP. Se você tiver um rótulo definido pelo usuário que corresponda a um filtro predefinido, ele será prefixado com LABEL para que você possa distinguir entre os dois. Por exemplo, se você criar um rótulo Service, verá Service e LABEL:Service no menu de filtro.
  
  Observação :para realizar uma correspondência exata, insira um sinal de adição (+) como prefixo do valor do filtro. Se você omitir o sinal de adição, uma correspondência será determinada executando um teste de prefixo com o valor do filtro. Para mais detalhes sobre as opções de filtragem, consulte Filtros de trace.

Encontrar um trace por ID

Ao solucionar um incidente ou falha, você pode saber o ID de rastreamento. Para explorar esse rastro, faça o seguinte:

No painel de navegação do console do Google Cloud, selecione Trace e, em seguida, Trace Explorer:
Acessar o Explorador de traces
Selecione um projeto do Google Cloud para visualizar os dados de trace.

Selecione o projeto do Google Cloud que armazena os dados de trace, a menos que seu projeto faça parte de uma organização. Quando um projeto faz parte de uma organização, é possível configurar o rastreamento entre projetos, e isso permite visualizar dados de trace de qualquer projeto na organização. Para mais informações, consulte Visualizar traces entre projetos.
Insira o ID no campo ID do trace.

Quando você insere um ID válido, o painel Detalhes do trace é preenchido com informações sobre o trace e os períodos dele. Você pode usar as opções desse painel para explorar o rastro.

Explorar um trace

Para explorar um rastro, clique em um ponto no gráfico de dispersão. Quando você clica em um ponto no gráfico de dispersão, as seguintes alterações ocorrem na página do Explorador de traces:

O gráfico de dispersão é atualizado e o ponto selecionado é destacado com um círculo desenhado ao redor do ponto. Os pontos que representam todos os outros rastros ficam esmaecidos.
O painel Detalhes do trace mostra o seguinte:
- O identificador de trace. Esse identificador globalmente exclusivo para o trace é um número inteiro de 128 bits representado como uma string hexadecimal de 32 bytes. Para mais detalhes, consulte Resource: Trace.
- Uma linha de resumo que lista o horário de início, a duração e o número de períodos.
- Um menu Registros e eventos A seleção do menu controla como os registros e eventos são exibidos. Por padrão, quando um registro ou evento existe, um círculo é adicionado ao período do trace. Os círculos sobrepostos indicam que o período tem vários registros ou eventos. Para exibir cada registro ou evento como uma linha na tabela, expanda Registros e eventos e selecione Mostrar expandidos.
- Uma tabela. A primeira linha da tabela é para o trace. Uma linha é adicionada para cada período no trace.
  
  A tabela lista o nome do período e o serviço associado a ele. O nome do serviço é extraído do atributo OpenTelemetry service.name, quando esse atributo é definido. Se esse atributo não estiver definido e o serviço estiver em execução no App Engine, o nome desse serviço será exibido. Caso contrário, o serviço não será especificado.
  
  A coluna Latência oferece uma representação visual da latência, do status e, quando presentes, das anotações de eventos. Uma barra de latência azul indica que a conclusão foi bem-sucedida, uma barra de latência vermelha indica que ocorreu um erro. Cada anotação de evento no espaço é representada com um círculo na barra de latência.

Confira a seguir um exemplo do painel Detalhes do trace:

Exemplos do painel de detalhes do Cloud Trace.

Mais detalhes do período

Para informações detalhadas sobre o trace ou um período específico, no painel Detalhes do trace, clique na barra de latência da entrada. Quando você seleciona a barra de latência, o painel Detalhes do trace é redesenhado e exibe uma tabela com guias que fornece mais informações sobre a entrada.

Se você selecionar a barra de latência da primeira linha da tabela, a linha com o nome ID do trace, a tabela conterá duas guias: Resumo e Registros. A guia Resumo lista informações gerais sobre o trace. Por exemplo, para comandos HTTP, essa guia exibe o tipo de comando HTTP, o serviço e as informações de latência de cada período no trace.

Se você selecionar a barra de latência para outras linhas na tabela, ou seja, uma linha para um período, a tabela conterá quatro guias: Attributes, Logs & events, Stacktraces, Metadata & Links:

Para encontrar os rótulos anexados a um período, consulte a guia Atributos. Para informações sobre rótulos, consulte Rótulos de rastreamento. A captura de tela a seguir ilustra essa guia:

Para localizar um marcador específico ou um grupo de marcadores, adicione um filtro. Por exemplo, se você adicionar o filtro Key: g.co, a tabela listará todos os rótulos em que a chave contém g.co.
Para ver informações sobre entradas e eventos de registro relacionados, se houver, consulte a guia Registros e eventos. Para saber mais sobre anotações de eventos, consulte Como anotar períodos de trace. A captura de tela a seguir ilustra essa guia:

Quando os dados de registro estiverem disponíveis, clique em Mostrar mais para ver detalhes sobre uma entrada de registro:
Para encontrar informações sobre o número de stack traces disponíveis e informações detalhadas sobre um stack trace capturado, use a guia Stacktraces.
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
  
  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 de término
- Tabela que lista links para outros períodos
  
  Cada linha na tabela Links lista um vínculo entre o período atual e outro. O campo Atributos lista os pares de chave-valor do período vinculado. O campo Trace é vinculado ao trace do período vinculado. Quando esse campo contém Trace atual, o período vinculado está no mesmo trace que o período atual. Caso contrário, o campo conterá um ID de trace. Para mais informações sobre links, consulte a página de referência da API Links.
A captura de tela a seguir ilustra essa guia: