Este documento descreve como resolver problemas ao usar a página Trace Explorer ou a página legada Trace Explorer:
- Resolver problemas na página Explorador de traces
- Resolver problemas da página legada Explorador de traces
Problemas conhecidos
Há dois problemas conhecidos com a página Trace Explorer:
As extensões gravadas no seu projeto do Google Cloud antes de 11 de janeiro de 2025 podem não estar disponíveis. Esses períodos estão disponíveis na página Trace Explorer legada.
O painel de detalhes do evento para intervalos gravados no seu projeto do Google Cloud antes de 11 de janeiro de 2025 pode ser exibido de maneira diferente para intervalos gravados após essa data.
Resolver problemas na página Explorador de traces
Esta seção descreve como resolver problemas ao usar a página Trace Explorer.
Não há dados na página Explorador de trace
Você está usando a página Trace Explorer e não consegue visualizar nenhum trace no projeto do Google Cloud quando espera que os dados de trace estejam presentes.
Para fazer isso, siga estas etapas:
Verifique se a API Cloud Trace está ativada e se os dados estão sendo gravados no projeto:
No console do Google Cloud, acesse a página APIs e serviços ativados:
Se a API Cloud Trace estiver listada, prossiga para a próxima etapa. Caso contrário, ative a API.
Para ativar a API, clique em Ativar APIs e serviços, pesquise "API Cloud Trace", selecione a opção e clique em Ativar.
Na página Ativar APIs e serviços, encontre a linha API Cloud Trace.
Se a coluna Solicitações não listar informações numéricas, nenhum dado de trace será enviado ao seu projeto do Google Cloud.
Para resolver esse caso, verifique seus aplicativos e proxies para garantir que eles estão configurados para enviar os traces para o projeto correto.
Se a coluna Error listar um valor diferente de zero, haverá erros na leitura ou gravação de dados de rastreamento. Para saber mais sobre a origem dos erros, selecione a API Cloud Trace, a guia Métricas e encontre o gráfico Erros por método de API:
Se as gravações estiverem falhando, conceda à conta de serviço que está fornecendo as credenciais de autenticação o papel de agente do Cloud Trace (
roles/cloudtrace.agent
). Esse papel inclui a permissãocloudtrace.traces.patch
, que permite que os aplicativos gravem dados de abrangência em um projeto do Google Cloud.Para mais informações, consulte Papéis do IAM do Cloud Trace.
Se as leituras falharem, verifique se o papel do IAM no projeto do Google Cloud inclui as permissões no papel de usuário do Cloud Trace (
roles/cloutrace.user
). Para conferir uma lista de permissões para esse papel, consulte Papéis do Cloud IAM do Cloud Trace.
Verifique se a página Trace Explorer está pesquisando dados de trace no seu projeto atual:
-
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, acesse o elemento Escopo, expanda o menu Aprimorar escopo, selecione Projeto atual e Aplicar.
-
Tente uma destas alternativas:
Mude para a página Análise de rastros legada. Essa página lê dados de trace e de abrangência de um banco de dados diferente da página Trace Explorer.
Use a API Cloud Trace para enviar um período ao seu projeto do Google Cloud. Para mais informações, consulte Forçar a criação do banco de dados para a página Trace Explorer.
Dados mais antigos ausentes na página Explorador de traces
Você está usando a página Trace Explorer e pode conferir dados recentes, mas, quando você define o seletor de período como 30 dias ou um valor maior, os dados mais antigos não são mostrados.
A página Trace Explorer não mostra dados de períodos maiores do que o período de armazenamento de dados do Cloud Trace, que é de 30 dias.
Se o seletor de período for de 30 dias ou menos, os dados ausentes indicam que o banco de dados consultado pelas consultas da página Trace Explorer foi criado mais recentemente do que sua configuração de período. Por exemplo, se você definir esse valor como 20 dias e só conseguir ver os 10 dias mais recentes de dados, o banco de dados foi criado 10 dias atrás. Além disso, esse banco de dados contém apenas rastros que foram enviados ao seu projeto do Google Cloud após a criação do banco de dados.
Para conferir e analisar dados de trace mais antigos, mude para a página Explorador de traces legado. Essa página lê dados de trace e de abrangência de um banco de dados diferente da página Trace Explorer.
Acessar o Explorador de traces legado
Intervalos ausentes em um trace
Você abre a página Trace Explorer e seleciona um período para visualizar. O painel suspenso Detalhes mostra o trace, mas algumas extensões estão ausentes.
As spans podem estar ausentes pelos seguintes motivos:
A página Trace Explorer não está pesquisando todos os projetos do Google Cloud que armazenam dados de duração do trace.
Sua função do IAM em um projeto do Google Cloud que armazena dados de duração do rastreamento não contém as permissões necessárias para visualizar os dados de rastreamento.
Há um problema de instrumentação. Por exemplo, apenas alguns spans em um trace foram enviados para seu projeto do Google Cloud.
Eles foram gravados no seu projeto do Google Cloud antes de 11 de janeiro de 2025.
Para resolver esses problemas, faça o seguinte:
Determine se o trace está completo na página legado Análise de rastros:
No menu suspenso Details do trace, copie o ID dele para a área de transferência.
Acesse a página Explorador de traces legado:
Cole o ID de rastreamento no campo ID de rastreamento.
A página Detalhes do trace é atualizada e lista os projetos que armazenam períodos de trace.
Se o trace estiver concluído na página legado Trace Explorer, volte para a página Trace Explorer e defina o elemento Escopo para um escopo de trace que liste todos os projetos que você identificou na etapa anterior. Esses são os projetos que armazenam os períodos do trace selecionado.
Se não houver um escopo de rastreamento que inclua os projetos que você identificou na etapa anterior, crie ou modifique um escopo de rastreamento existente. Para mais informações, consulte Criar e gerenciar escopos de rastreamento.
Se o trace não estiver completo na página legado Trace Explorer, ou as extensões não foram gravadas ou você não tem a função de usuário do Cloud Trace (
roles/cloudtrace.user
) nos projetos que armazenam os dados de extensão.
Você não tem as permissões necessárias para acessar os dados de trace
Você está na página Trace Explorer e vê a seguinte notificação:
You don't have the required permissions to view trace data for one or more projects listed in the trace scope.
Para resolver essa mensagem, na barra de ferramentas, faça o seguinte:
- Abra o elemento Escopo e identifique o escopo de rastreamento selecionado.
- No menu suspenso Refinar escopo, selecione Gerenciar escopos.
- Localize o escopo de trace que você identificou na primeira etapa e abra os detalhes para conferir a lista de projetos do Google Cloud.
- Para cada projeto do Google Cloud no escopo do rastreamento, verifique se você tem
a função de usuário do Cloud Trace (
roles/cloudtrace.user
). Se você não tiver essa função em um projeto, peça a um administrador ou proprietário do projeto para conceder essa função.
Forçar a criação do banco de dados para a página Trace Explorer
Quando os únicos dados de trace no seu projeto são de serviços Google Cloud que estão pré-configurados para o Cloud Trace, o banco de dados que a página Trace Explorer lê para o trace e os dados de período podem não ser criados. No entanto, é possível forçar a criação desse banco de dados enviando um trace para o projeto do Google Cloud usando a API Cloud Trace.
Por exemplo, você pode fazer o seguinte:
- Acesse a página de documentação do
patchTraces
. No painel Testar este método, faça o seguinte:
- No campo projectId, insira o PROJECT_ID.
Copie o JSON, que define um trace com um único período, para a área de transferência e cole no campo Corpo da solicitação.
Antes de copiar o JSON, faça o seguinte:
- Substitua PROJECT_ID pelo ID do seu projeto.
Substitua END_TIME pelo horário atual e START_TIME por um valor anterior ao horário de término. Se você estiver usando o Linux, execute
date -Isec
para conferir a hora atual no formato correto. Por exemplo, você pode definir esses campos da seguinte maneira:"startTime": "2024-05-31T15:10:35.398448Z", "endTime": "2024-05-31T15:10:35.574999047Z",
Atualize os campos
traceId
espanId
sempre que executar o comando."traces": [ { "projectId": "
PROJECT_ID ", "traceId": "33fc0d8c45bb4e5cebb29f047931270d ", "spans": [ { "spanId": "17941747227541407973 ", "name": "/", "startTime": "START_TIME ", "endTime": "END_TIME ", } ] } ]
Pressione Executar.
Quando o comando é concluído, o corpo da resposta fica vazio. Se você acessar o Explorador de traces, poderá conferir seu trace. Pode haver um pequeno atraso até que o rastro fique disponível no console do Google Cloud.
Resolver problemas da página legada Trace Explorer
Esta seção descreve como resolver problemas ao usar a página Trace Explorer legado.
Não há dados na interface legada
Você está usando a página Trace Explorer legada e não consegue visualizar nenhum trace no projeto do Google Cloud quando espera que os dados de trace esteja presentes.
Para resolver esse problema, siga estas etapas:
-
Enable the Cloud Trace API.
No console do Google Cloud, acesse a página APIs e serviços:
Depois de encontrar a linha API Cloud Trace, faça o seguinte:
Se a coluna Solicitações não listar informações numéricas, nenhum dado de trace será enviado ao seu projeto do Google Cloud.
Para resolver esse caso, verifique seus aplicativos e proxies para garantir que eles estão configurados para enviar os traces para o projeto correto.
Selecione a API Cloud Trace, a guia Métricas e encontre o gráfico Erros por método de API:
Se as gravações estiverem falhando, conceda à conta de serviço que está fornecendo as credenciais de autenticação o papel de Agente do Cloud Trace (
roles/cloudtrace.agent
). Esse papel inclui a permissãocloudtrace.traces.patch
, que permite que os aplicativos gravem dados de abrangência em um projeto do Google Cloud.Para mais informações, consulte Papéis do IAM do Cloud Trace.
Se as leituras falharem, verifique se o papel do IAM no projeto do Google Cloud inclui as permissões no papel Usuário do Cloud Trace (
roles/cloutrace.user
). Para conferir uma lista de permissões para esse papel, consulte Papéis do Cloud IAM do Cloud Trace.
Não há dados de rastreamento para o app implantado na interface legada
Você implantou um app que envia dados para seu projeto do Google Cloud usando a API Cloud Trace, mas os dados de trace não são coletados.
Tente o seguinte:
Se não houver dados na página Explorador de traces legado do console do Google Cloud, siga as etapas na seção Não há dados na interface do legado do Trace.
Se o app não estiver implantado no Google Cloud ou se usar uma conta de serviço para fornecer credenciais de autenticação, verifique se a conta de serviço recebeu o papel de agente do Cloud Trace (
roles/cloudtrace.agent
).Esse papel inclui a permissão
cloudtrace.traces.patch
, que permite que os aplicativos gravem dados de abrangência em um projeto do Google Cloud.Se o app depender do OpenTelemetry, faça o seguinte:
Para o serviço raiz, tente atualizar as variáveis de ambiente para que o OpenTelemetry use o amostrador
traceidratio
com uma taxa de amostragem de0.5
:export OTEL_TRACES_SAMPLER="traceidratio" export OTEL_TRACES_SAMPLER_ARG="0.5"
Para todos os outros serviços, deixe a variável de ambiente
OTEL_TRACES_SAMPLER
definida como "unset" para usar o sampler padrão, que éparentbased_always_on
. A configuração padrão significa que a decisão de amostragem de um período é herdada do período pai, se ele existir. Se uma span pai não existir, ela será amostrada.
A menos que seu aplicativo sempre faça a amostragem de cada intervalo, não é possível, em geral, forçar que uma solicitação seja rastreada de ponta a ponta, porque cada componente em uma solicitação de ponta a ponta toma sua própria decisão de amostragem. No entanto, é possível influenciar a decisão adicionando ao cabeçalho do rastreamento uma flag
sampled
, com essa flag definida comotrue
. Essa configuração é uma dica para componentes filhos para amostrar a solicitação. Para mais informações sobre cabeçalhos de trace, consulte Protocolos para propagação de contexto.
Mensagem de ID de span ausente no trace
Seu rastro contém a mensagem "ID de span ausente".
Em sistemas de rastreamento distribuído, é esperado que os rastros sejam incompletos. Um rastro está incompleto quando um período amostrado contém uma referência a outro período que não foi recebido. A referência não resolvida pode ocorrer pelos seguintes motivos:
- O período de referência não foi amostrado.
- O período de referência foi amostrado, mas ainda não foi recebido pelo Cloud Trace ou o período foi recebido, mas não foi armazenado.
Quando você está visualizando um trace incompleto, o Cloud Trace mostra a mensagem "ID de período ausente" no painel de detalhes do trace.
Se a mensagem "ID de span ausente" aparecer com frequência, tente o seguinte:
Para os componentes que você gerencia, verifique se eles respeitam e propagam a flag
sampled
do cabeçalho, quando esse campo está presente. Essa configuração é uma dica para componentes filhos para amostrar a solicitação. Para mais informações sobre cabeçalhos de trace, consulte Protocolos para propagação de contexto.Os serviçosGoogle Cloud geralmente respeitam essa dica. No entanto, eles também limitam a taxa em que gravam dados de trace.
Se você estiver usando o Cloud Service Mesh, siga as orientações para propagar o contexto de rastreamento para essas configurações. Para orientações sobre o Cloud Service Mesh, consulte Rastrear a propagação de contexto.
Nenhum dado de rastreamento após a atualização do app Go para usar o OpenTelemetry
O aplicativo depende da biblioteca de cliente para capturar rastros. Depois de atualizar o aplicativo para usar o OpenTelemetry, você não vai mais ver dados do Cloud Trace.
Como algumas bibliotecas de cliente do Cloud para Go são integradas ao OpenCensus, é necessário usar uma ponte do OpenCensus. Para mais informações sobre o problema resolvido pela ponte, consulte OpenCensus Bridge.
Para informações sobre a atualização das bibliotecas de cliente do Cloud para Go, consulte Issue #4237.