Resolver problemas

Esta página contém informações sobre solução de problemas do Trace.

Neste documento, descrevemos como solucionar problemas ao usar a página Explorador de traces ou a página legada Explorador de traces:

Problemas conhecidos

Esta seção lista os problemas conhecidos:

  • Os períodos gravados no seu projeto Google Cloud usando a API Telemetry não estão disponíveis na página legada do Trace Explorer. Para conferir esses intervalos, use a página padrão do Trace Explorer.

  • Os intervalos gravados no seu projeto Google Cloud usando a API Telemetry não estão acessíveis à API Cloud Trace. Por exemplo, se você tentar listar esses rastreamentos, o comando vai falhar com um erro 404 Not Found.

Resolver problemas na página Explorador de traces

Nesta seção, descrevemos como resolver problemas ao usar a página Explorador de rastreamentos.

Não há dados na página Explorador de traces

Você está usando a página Buscador de trace e não consegue ver nenhum trace no projeto Google Cloud quando espera que os dados de trace estejam presentes.

Para fazer isso, siga estas etapas:

  1. Verifique se a API Cloud Trace está ativada e se os dados estão sendo gravados no seu projeto:

    1. No console Google Cloud , acesse a página APIs e serviços ativados:

      Acessar APIs e serviços ativados

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

  2. Na página APIs e serviços ativados, encontre a linha API Cloud Trace.

  3. Se a coluna Erro listar um valor diferente de zero, haverá erros ao ler ou gravar dados de rastreamento pela API Cloud Trace. Para mais informações sobre a origem dos erros, selecione API Cloud Trace, a guia Métricas e encontre o gráfico Erros por método da 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ão cloudtrace.traces.patch, que permite que os aplicativos gravem dados de extensão em um projeto Google Cloud .

      Para mais informações, consulte papéis do IAM do Cloud Trace.

    • Se houver falha nas leituras, verifique se seu papel do IAM no projeto Google Cloud inclui as permissões do papel de usuário do Cloud Trace (roles/cloutrace.user). Para conferir uma lista de permissões desse papel, consulte Papéis do IAM do Cloud Trace.

  4. A coluna Solicitações lista o número de solicitações enviadas à API Cloud Trace. Quando essa coluna é zero, nenhum dado de rastreamento está sendo enviado pela API.

    O App Engine, o Cloud Run e as Funções do Cloud Run enviam dados de rastreamento sem usar a API Cloud Trace. Se você usa apenas esses serviços, vá para a próxima etapa.

    Se você tiver um aplicativo que está enviando dados de rastreamento pela API Cloud Trace e a coluna de solicitações for zero, verifique seus aplicativos e proxies para verificar se eles estão configurados para enviar os rastreamentos ao projeto correto.

  5. Na página Explorador de traces, verifique se o armazenamento de traces foi inicializado:

    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. Se o armazenamento de traces não estiver inicializado, a página Explorador de traces vai mostrar um banner com o seguinte texto:

      Trace storage is not initialized in this project. Enable trace storage to begin collecting trace data.

      Para inicializar o armazenamento do Trace, clique em Ativar no banner. A inicialização geralmente é concluída em alguns minutos.

      Quando a inicialização for bem-sucedida, um banner de notificação será exibido. O Trace ingere dados de rastreamento enviados na última hora, que foram armazenados anteriormente em um buffer. Atualize em alguns minutos à medida que os dados começarem a aparecer no Explorador de traces.

      Se você receber uma mensagem de erro indicando que a inicialização falhou, um membro da equipe de suporte do Google Cloud precisa resolver o problema manualmente. Clique em Registrar um tíquete para iniciar esse processo.

  6. Verifique se a página Explorador de traces está pesquisando dados de trace no projeto atual. Na barra de ferramentas, acesse o elemento Escopo, expanda o menu Refinar escopo, selecione Projeto atual e clique em Aplicar.

Pesquisar falhas de um trace específico

Você insere um ID de rastreamento na página Explorador de traces. O rastreamento não é encontrado, e uma mensagem semelhante a esta é mostrada:

The select trace with ID abcde does not exist or is older than 30 days and has been deleted per our retention policy.

Para resolver essa falha, tente o seguinte:

  1. Verifique se o carimbo de data/hora associado ao ID do rastreamento está dentro do período de armazenamento.

  2. Identifique o projeto Google Cloud que armazena o rastreamento e verifique se o seletor de recursos no console Google Cloud seleciona esse projeto. Por padrão, a página Buscador de trace só tem acesso aos dados de trace armazenados no projeto selecionado.

Dados mais antigos ausentes na página Explorador de traces

Você está usando a página Explorador de rastreamento e pode ver dados recentes, mas quando 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 Explorador de rastreamentos não mostra dados de períodos maiores 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 vão indicar que o banco de dados consultado pelas consultas da página Explorador de rastreamentos 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 há 10 dias. Além disso, esse banco de dados contém apenas rastreamentos enviados ao seu projeto Google Cloud depois da criação do banco de dados.

Para acessar e analisar dados de rastreamento mais antigos, mude para a página Explorador de traces legado. Essa página lê dados de trace e intervalo de um banco de dados diferente da página Explorador de traces.

Acessar o Explorador de traces legado

Intervalos ausentes em um rastreamento

Abra a página do Trace Explorer e selecione um período para visualizar. O submenu Detalhes mostra o rastreamento, mas alguns intervalos estão faltando.

Os intervalos podem estar ausentes pelos seguintes motivos:

  • A página Buscador de trace não pesquisa todos os projetos Google Cloud que armazenam dados de período para o trace.

  • Seu papel do IAM em um projeto Google Cloud que armazena dados de intervalo para o rastreamento não tem as permissões necessárias para ver os dados de rastreamento.

  • Há um problema de instrumentação. Por exemplo, apenas alguns intervalos em um rastreamento foram enviados para seu projeto do Google Cloud .

Para resolver esses problemas, faça o seguinte:

  1. Determine se o trace está completo na página legada do Explorador de traces:

    1. No menu suspenso Detalhes do trace, copie o ID dele para a área de transferência.

    2. Acesse a página Explorador de traces legado:

      Acessar o Explorador de traces legado

    3. 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 do trace.

  2. Se o trace estiver completo na página Buscador de trace legado, volte à página Buscador de trace e defina o elemento Escopo como um escopo de trace que liste todos os projetos identificados na etapa anterior. São os projetos que armazenam os períodos do rastreamento selecionado.

    Se não houver um escopo de rastreamento que inclua os projetos identificados na etapa anterior, crie ou modifique um escopo de rastreamento. Para mais informações, consulte Criar e gerenciar escopos de rastreamento.

  3. Se o trace não estiver completo na página Buscador de trace legado, os intervalos não foram gravados ou você não tem a função Usuário do Cloud Trace (roles/cloudtrace.user) nos projetos que armazenam os dados de intervalo.

Você não tem as permissões necessárias para acessar os dados de rastreamento

Você está na página Explorador de traces 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 esse problema, faça o seguinte na barra de ferramentas:

  1. Expanda o elemento Escopo e identifique o escopo do trace selecionado.
  2. No menu suspenso Refinar escopo, selecione Gerenciar escopos.
  3. Localize o escopo de rastreamento identificado na primeira etapa e expanda os detalhes para ver a lista de projetos Google Cloud .
  4. Para cada projeto Google Cloud no escopo do rastreamento, verifique se você tem o papel de usuário do Cloud Trace (roles/cloudtrace.user). Se você não tiver esse papel em um projeto, peça a um administrador ou proprietário do projeto para conceder esse papel a você.

Falha na inicialização do armazenamento de rastreamentos

Você tenta inicializar o armazenamento de rastreamento clicando em Ativar no banner mostrado no Explorador de rastreamento e recebe o seguinte erro:

Initializing trace storage has failed for an unexpected reason. Please file a support ticket for assistance.

Se a inicialização do armazenamento falhar, um membro da equipe de suporte do Google Cloud deverá resolver o problema manualmente. Para entrar em contato com o suporte, clique em Enviar um tíquete.

Resolver problemas da página legada do Explorador de traces

Nesta seção, descrevemos como resolver problemas ao usar a página Explorador de rastreamentos legada.

Não há dados na interface legada

Você está usando a página Buscador de trace legado e não consegue ver nenhum trace no projeto Google Cloud quando espera que os dados de trace estejam presentes.

Para resolver essa falha, siga estas etapas:

  1. Enable the Cloud Trace API.

    Enable the API

  2. No console Google Cloud , acesse a página APIs e serviços:

    Acessar APIs e serviços

    Depois de encontrar a linha API Cloud Trace, faça o seguinte:

    • Se a coluna Solicitações não listar nenhuma informação numérica, isso significa que nenhum dado de rastreamento está sendo enviado ao seu projeto Google Cloud .

      Para resolver esse caso, verifique seus aplicativos e proxies para garantir que eles estejam configurados para enviar os traces ao projeto correto.

    • Selecione 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ão cloudtrace.traces.patch, que permite que os aplicativos gravem dados de extensão em um projeto Google Cloud .

        Para mais informações, consulte papéis do IAM do Cloud Trace.

      • Se houver falha nas leituras, verifique se seu papel do IAM no projeto Google Cloud inclui as permissões do papel Usuário do Cloud Trace (roles/cloutrace.user). Para conferir uma lista de permissões desse papel, consulte Papéis do 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 Google Cloud usando a API Cloud Trace, mas os dados de rastreamento não são coletados.

Tente o seguinte:

  • Se você não estiver vendo dados na página Explorador de traces legado do console Google Cloud , siga as etapas na seção intitulada Não há dados na interface do Trace legado.

  • Se o app não estiver implantado no Google Cloud ou se ele 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 extensão em um projeto 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 sampler traceidratio com uma taxa de amostragem de 0.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 não definida para usar o sampler padrão, que é parentbased_always_on. A configuração padrão significa que a decisão de amostragem de um intervalo é herdada do intervalo pai, se ele existir. Se um intervalo pai não existir, o intervalo será coletado.

    A menos que seu aplicativo sempre faça amostragem de todos os intervalos, não é possível, em geral, forçar o rastreamento de uma solicitação 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 de rastreamento uma flag sampled, com essa flag definida como true. Essa configuração é uma dica para que os componentes filhos façam amostragem da solicitação. Para mais informações sobre cabeçalhos de rastreamento, consulte Protocolos para propagação de contexto.

Mensagem de ID de extensão ausente no rastreamento

Seu rastreamento contém uma mensagem "ID de intervalo ausente".

Em sistemas de rastreamento distribuído, é esperado que haja rastreamentos incompletos. Um rastreamento é 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 intervalo referenciado não foi amostrado.
  • O período referenciado foi coletado, mas ainda não foi recebido pelo Cloud Trace ou foi recebido, mas não armazenado.

Ao visualizar um trace incompleto, o Cloud Trace mostra a mensagem "ID do período ausente" no painel de detalhes do trace.

Se você estiver vendo a mensagem "ID de intervalo ausente" constantemente, tente o seguinte:

  • Para componentes gerenciados por você, verifique se eles respeitam e propagam a flag sampled do cabeçalho quando esse campo está presente. Essa configuração é uma dica para que os componentes filhos façam uma amostragem da solicitação. Para mais informações sobre cabeçalhos de rastreamento, consulte Protocolos para propagação de contexto.

    Os serviçosGoogle Cloud geralmente respeitam essa dica. No entanto, eles também limitam a taxa de gravação de dados de rastreamento.

  • Se você estiver usando o Cloud Service Mesh, siga as orientações para propagar o contexto de rastreamento dessas configurações. Para orientações sobre o Cloud Service Mesh, consulte Propagação do contexto de rastreamento.

Não há dados de rastreamento após a atualização do app Go para usar o OpenTelemetry

Seu aplicativo depende da biblioteca de cliente para capturar traces e, depois de atualizar o aplicativo para usar o OpenTelemetry, você não verá mais 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 Ponte do OpenCensus.

Para informações sobre a atualização das bibliotecas de cliente do Cloud para Go, consulte Problema nº 4237.