Resolver problemas de roteamento e armazenamento de registros

Neste documento, explicamos problemas comuns de roteamento e armazenamento e como usar o console do Google Cloud para visualizar e solucionar erros de configuração ou resultados inesperados.

Para informações gerais sobre o uso de registros nos destinos do coletor, consulte Visualizar registros nos destinos do coletor.

Resolver problemas de registros de roteamento

Esta seção descreve como solucionar problemas comuns ao rotear seus registros.

O destino contém registros indesejados

Você está visualizando os registros roteados para um destino e determina que o destino contém registros indesejados.

Para resolver essa condição, atualize os filtros de exclusão dos coletores que roteiam os registros para o destino. Com os filtros de exclusão, é possível impedir que registros selecionados sejam roteados para um destino.

Por exemplo, suponha que você criou um coletor agregado para rotear os registros de uma organização para um destino. Para impedir que os registros de um projeto específico sejam roteados para o destino, adicione o seguinte filtro de exclusão ao coletor:

logName:projects/PROJECT_ID

Também é possível excluir registros de vários projetos usando o operador lógico OR para unir cláusulas logName.

Registros ausentes no destino

Talvez o problema mais comum relacionado ao coletor seja a ausência de registros em um destino de coletor.

Observação :se você tiver recebido uma notificação sobre um erro ou um registro de erros de configuração do coletor no console do Google Cloud for exibido, pule esta seção e visualize o registro de erros para identificar o problema e corrigir o problema.

Em alguns casos, um erro não é gerado, mas é possível que os registros estejam indisponíveis quando você tentar acessá-los no seu destino. Se você suspeitar que o coletor não está roteando os registros corretamente, verifique as métricas com base em registros do sistema:

• exports/byte_count: número de bytes em entradas de registro que foram roteadas.
• exports/log_entry_count: número de entradas de registro que foram roteadas.
• exports/error_count: número de entradas de registro que não foram roteadas.

As métricas têm rótulos que registram as contagens por nome do coletor e do destino e informam se o coletor está roteando dados de registros com êxito ou falha. Consulte Visualizar métricas com base em registros para saber mais.

Se as métricas do coletor indicarem que o coletor não está tendo o desempenho esperado, veja alguns possíveis motivos e o que fazer a respeito:

Latência

• Nenhuma entrada de registro correspondente foi recebida desde que você criou ou atualizou o coletor. Apenas entradas de registro novas serão roteadas.

  Tente aguardar uma hora e verifique o destino novamente.

• As entradas de registro correspondentes estão atrasadas.

  Pode haver um atraso até que você possa ver seus registros no destino. Os registros tardios são especialmente comuns para coletores que configuraram buckets do Cloud Storage como destinos. Espere algumas horas e verifique seu destino novamente.

O escopo/filtro de visualização está incorreto

• O escopo que você está usando para visualizar os registros nos destinos do bucket do Logging está incorreto.

  Restrinja sua pesquisa a uma ou mais visualizações de armazenamento, da seguinte maneira:

  • Se você estiver usando a Análise de registros, use o botão Refinar escopo.

  • Se você estiver usando a CLI gcloud, use o comando gcloud logging read e adicione uma sinalização --view=AllLogs.

• O intervalo de tempo que você está usando para selecionar e visualizar dados no destino do coletor é muito curto.

  Tente ampliar o intervalo de tempo usado ao selecionar dados no destino do coletor.

Erro no filtro do coletor

• O filtro do coletor está incorreto e não está capturando os registros que você esperava encontrar no destino.

  • Edite o filtro do coletor usando o Roteador de registros no console do Google Cloud. Para verificar se você inseriu o filtro correto, selecione Visualizar registros no painel Editar coletor. Isso abre a Análise de registros em uma nova guia com o filtro pré-preenchido. Para instruções sobre como visualizar e gerenciar coletores, consulte Gerenciar coletores.

Ver erros

Para cada um dos destinos de coletor compatíveis, o Logging fornece mensagens de erro para coletores configurados incorretamente.

Há várias maneiras de ver esses erros relacionados ao coletor. Esses métodos são descritos nas seguintes seções:

• Ver os registros de erros gerados para o coletor.
• Receber notificações de erro de coletor por e-mail.

Observação :erros relacionados ao coletor são informados uma vez por dia em cada grupo de erros.

Registros de erros

O método recomendado para inspecionar detalhes relacionados ao coletor é visualizar as entradas de registro de erros geradas pelo coletor. Para detalhes sobre como visualizar registros, consulte Visualizar registros usando a Análise de registros.

Use a consulta a seguir no painel do editor de consultas na Análise de registros para revisar os registros de erros do coletor. A mesma consulta funciona na API Logging e na CLI gcloud.

Antes de copiar a consulta, substitua a variável SINK_NAME pelo nome do coletor que você está tentando resolver. É possível encontrar o nome do coletor na página Roteador de registros no console do Google Cloud.

logName:"logging.googleapis.com%2Fsink_error"
resource.type="logging_sink"
resource.labels.name="<var>SINK_NAME</var>"

Por exemplo, se o nome do coletor for my-sink-123, a entrada de registro poderá ser semelhante a esta:

{
  "textPayload": "Cloud Logging export config error in my-logs-project, export sink my-sink-123: dataset_not_found ()",
  "insertId": "12akhzyb14452",
  "resource": {
    "type": "logging_sink",
    "labels": {
      "project_id": "my-logs-test-project",
      "destination": "",
      "name": "my-sink-123"
    }
  },
  "timestamp": "2021-08-02T17:01:28.620961700Z",
  "severity": "ERROR",
  "labels": {
    "error_code": "dataset_not_found",
    ...
    "destination": "bigquery.googleapis.com/projects/my-logs-project/datasets/my-dataset",
    "sink_id": "my-sink-123",
    "activity_type_name": "LoggingSinkConfigErrorV2"
  },
  "logName": "projects/cloud-logs-test-project/logs/logging.googleapis.com%2Fsink_error",
  "receiveTimestamp": "2021-08-02T17:01:30.148869575Z"
}

O campo LogEntry labels e as informações da chave-valor aninhada ajudam a segmentar a origem do erro do coletor. Ele contém o recurso afetado, o coletor afetado e o código de erro. O campo labels.error_code contém uma breve descrição do erro, informando qual componente do coletor precisa ser reconfigurado.

Para atualizar o coletor, use o Roteador de registros.

No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

Acessar o roteador de registros

Observação: se você não conseguir ver erros de coletor relacionados à permissão nos seus registros, verifique se você ativou os registros de auditoria de acesso a dados dos serviços que você está enviando registros. Os registros de auditoria de acesso a dados ajudam o Suporte do Google a resolver problemas na sua conta. Portanto, recomendamos ativar os registros de auditoria de acesso a dados quando possível.

Notificações por e-mail

Se você tiver um projeto do Google Cloud ou o recurso pai correspondente como contato técnico essencial, receberá notificações por e-mail sobre o erro de configuração do coletor. Se não houver contatos técnicos essenciais configurados para um recurso, os usuários listados como proprietários do projeto do IAM roles/owner receberão a notificação por e-mail.

A mensagem de e-mail contém as seguintes informações:

• ID do recurso: o nome do projeto do Google Cloud ou de outro recurso do Google Cloud em que o coletor foi configurado.
• Nome do coletor: o nome do coletor que contém o erro de configuração.
• Destino do coletor: o caminho completo do destino de roteamento do coletor. Por exemplo, bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
• Código do erro: é uma descrição abreviada da categoria de erro. Por exemplo, dataset_not_found
• Detalhes do erro: informações detalhadas sobre o erro, incluindo recomendações para resolver o problema.

Para conferir e gerenciar os coletores, use o Roteador de registros.

No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

Acessar o roteador de registros

Qualquer erro de configuração de coletor que se aplique ao recurso aparece na lista como um Cloud Logging sink configuration error. Cada erro contém um link para uma das entradas de registro geradas pelo coletor com defeito. Para examinar os erros subjacentes em detalhes, consulte a seção Registros de erros.

Tipos de erros de coletor

As seções a seguir descrevem categorias amplas de erros relacionados ao coletor e como resolvê-los.

Destino incorreto

Se você configurou um coletor, mas recebeu um erro de configuração informando que o destino não foi encontrado quando o Logging tentou rotear os registros, veja alguns motivos possíveis:

• A configuração do coletor contém um erro de ortografia ou outro erro de formatação no destino especificado do coletor.

  Você precisa atualizar a configuração do coletor para especificar corretamente o destino atual.

• O destino especificado pode ter sido excluído.

  Altere a configuração do coletor para usar um destino diferente ou recrie o destino com o mesmo nome.

Em ambos os casos, para corrigir problemas, acesse a página Roteador de registros.

No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

Acessar o roteador de registros

O coletor começa a encaminhar registros quando o destino é encontrado e novos registros que correspondem ao filtro são recebidos pelo Logging.

Como gerenciar problemas de coletores

Se você desativou um coletor para interromper o armazenamento de registros em um bucket de registros, mas ainda vir os registros sendo roteados, aguarde alguns minutos para que as alterações no coletor sejam aplicadas.

Problemas de permissões.

Observação: se você não conseguir ver erros de coletor relacionados à permissão nos seus registros, verifique se você ativou registros de auditoria de acesso a dados para os serviços aos quais você está enviando registros. Os registros de auditoria de acesso a dados ajudam o Suporte do Google a resolver problemas na sua conta. Portanto, recomendamos ativar os registros de auditoria de acesso a dados quando possível.

Se um coletor tentar encaminhar uma entrada de registro, mas não tiver as permissões de IAM apropriadas para o destino do coletor, o coletor informará um erro, que pode ser visualizado, e vai ignorar a entrada de registro.

Quando você cria um coletor, a conta de serviço dele precisa receber as permissões de destino apropriadas. Se você criar o coletor no console do Google Cloud no mesmo projeto do Google Cloud, o console do Google Cloud atribuirá essas permissões automaticamente. Se você criar o coletor em um projeto diferente do Google Cloud ou usando a CLI gcloud ou a API Logging, será necessário configurar as permissões manualmente.

Se você estiver vendo erros relacionados à permissão para seu coletor, adicione as permissões necessárias ao destino ou atualize o coletor para usar um destino diferente. Para instruções sobre como atualizar essas permissões, consulte Permissões de destino.

Há um pequeno atraso entre a criação do coletor e o uso da nova conta de serviço do coletor para autorizar a gravação no destino da exportação. O coletor começa a rotear registros quando alguma permissão é corrigida e novos registros que correspondem ao filtro são recebidos pelo Logging.

Problemas com a política da organização

Se você estiver tentando rotear uma entrada de registro, mas encontrar uma política da organização que restrinja o Logging na gravação no destino do coletor, o coletor não poderá rotear para o destino selecionado e relatará um erro.

Se você estiver vendo erros relacionados às políticas da organização, faça o seguinte:

• Atualize a política da organização do destino para remover as restrições que impedem o coletor de rotear entradas de registro. Isso pressupõe que você tenha as permissões apropriadas para atualizar a política da organização. Para instruções, consulte Como criar e editar políticas.

• Se não for possível atualizar a política da organização, atualize o coletor na página Roteador de registros para usar um destino compatível.

  No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

  Acessar o roteador de registros

O coletor começa a encaminhar registros quando a política da organização não bloqueia mais a gravação do destino e os novos registros que correspondem ao filtro são recebidos pelo Logging.

Problemas com a chave de criptografia

Se você estiver usando chaves de criptografia, gerenciadas com o Cloud Key Management Service ou por você, para criptografar os dados no destino do coletor, talvez você veja erros relacionados. Veja alguns possíveis problemas e maneiras de corrigi-los:

• O faturamento não está sendo ativado para o projeto do Google Cloud que contém a chave do Cloud KMS.

  • Mesmo que o coletor tenha sido criado com o destino correto, essa mensagem de erro será exibida se não houver uma conta de faturamento válida associada ao projeto do Google Cloud que contém a chave.

  • Verifique se há uma conta de faturamento vinculada ao projeto do Google Cloud que contenha a chave. Se uma conta de faturamento não estiver vinculada ao projeto do Google Cloud, ative o faturamento desse projeto ou use uma chave do Cloud KMS contida em um projeto do Google Cloud que tenha uma conta de faturamento válida vinculada a ele.

• A chave do Cloud KMS não foi encontrada.

  • O projeto do Google Cloud que contém a chave do Cloud KMS configurada para criptografar os dados não foi encontrado.

  • Use uma chave válida do Cloud KMS de um projeto atual do Google Cloud.

• O local da chave do Cloud KMS não corresponde ao local do destino.

  • Se o projeto do Google Cloud que contém a chave do Cloud KMS estiver em uma região diferente da região de destino, a criptografia falhará e o coletor não poderá rotear dados para esse destino.

  • Use uma chave do Cloud KMS contida por um projeto do Google Cloud com uma região que corresponda ao destino do coletor.

• O acesso à chave de criptografia é negado para a conta de serviço do coletor.

  • Mesmo que o coletor tenha sido criado com as permissões corretas da conta de serviço, essa mensagem de erro será exibida se o destino do coletor usar uma chave de criptografia que não conceda à conta de serviço permissões suficientes para criptografar ou descriptografar os dados.

  • Conceda o papel Criptografador/Descriptografador do CryptoKey do Cloud KMS para a conta de serviço especificada no campo writerIdentity do coletor para a chave usada no destino. Verifique também se a API Cloud KMS está ativada.

Problemas de cotas

Quando os coletores gravam registros, as cotas específicas do destino são aplicadas aos projetos do Google Cloud em que os coletores foram criados. Se as cotas se esgotarem, o coletor interromperá o roteamento de registros para o destino.

Por exemplo, ao rotear dados para o BigQuery, talvez você veja um erro informando que a cota de inserção por streaming por tabela foi excedida para uma determinada tabela no conjunto de dados. Nesse caso, o coletor pode estar roteando muitas entradas de registro muito rapidamente. O mesmo conceito se aplica a outros destinos de coletor compatíveis, por exemplo, para tópicos do Pub/Sub.

Para corrigir os problemas de esgotamento da cota, reduza o volume de dados de registro que está sendo roteado atualizando o filtro do coletor para corresponder a menos entradas de registro. É possível usar a função sample no filtro para selecionar uma fração do número total de entradas de registro.

O coletor começa a encaminhar registros para o destino quando você o atualiza para corresponder a menos entradas de registro ou quando as cotas são atualizadas.

Para detalhes sobre os limites que podem ser aplicados ao rotear registros, revise as informações de cota do destino apropriado:

• Cloud Logging: cotas e limites
• Cloud Storage: cotas e limites
• BigQuery: cotas e limites
• Pub/Sub: cotas e limites

Além dos tipos de erro gerais de coletor, veja os tipos de erro específicos de destino mais comuns e como é possível corrigi-los.

Erros no roteamento para o Cloud Storage

Veja a seguir os erros mais comuns ao rotear registros para o Cloud Storage:

• Entradas de registro atrasadas:

  • As entradas de registro roteadas são salvas em lotes a cada hora nos buckets do Cloud Storage. Pode ser necessário aguardar de duas a três horas até que as primeiras entradas comecem a aparecer.

  • Os fragmentos do arquivo de registro encaminhado com o sufixo An ("Append") mantêm as entradas de registro que chegaram atrasadas. Se o destino do Cloud Storage sofrer uma interrupção, o Cloud Logging armazenará os dados em buffer até que a interrupção termine.

• Não foi possível conceder permissões corretas ao destino:

  • Mesmo que o coletor tenha sido criado com as permissões corretas da conta de serviço, essa mensagem de erro será exibida se o modelo de controle de acesso ao bucket do Cloud Storage estiver definido como acesso uniforme quando o bucket foi criado.

  • Para os buckets atuais do Cloud Storage, é possível alterar o modelo de controle de acesso para os primeiros 90 dias após a criação do bucket usando a guia Permissões. Para novos buckets, selecione o modelo de controle de acesso Detalhado durante a criação do bucket. Para mais detalhes, consulte Como criar buckets do Cloud Storage.

Erros no roteamento para o BigQuery

Veja a seguir os erros mais comuns ao rotear registros para o BigQuery:

• Esquema de tabela inválido:

  • Os registros transmitidos para a tabela no conjunto de dados do BigQuery não correspondem ao esquema da tabela atual. Problemas comuns incluem a tentativa de rotear entradas de registro com tipos de dados diferentes, o que causa uma incompatibilidade de esquema. Por exemplo, um dos campos na entrada de registro é um número inteiro, enquanto uma coluna correspondente no esquema tem um tipo de string.

  • Verifique se as entradas de registro correspondem ao esquema da tabela. Depois de corrigir a origem do erro, é possível renomear a tabela atual e permitir que o Logging crie a tabela novamente.

  • O BigQuery suporta o carregamento de dados aninhados nas tabelas. No entanto, ao carregar dados do Logging, o limite de profundidade aninhado para uma coluna é de 13 níveis.

  Quando o BigQuery identifica uma incompatibilidade de esquema, ele cria uma tabela no conjunto de dados correspondente para armazenar as informações de erro. O tipo de uma tabela determina o nome dela. Para tabelas fragmentadas por data, o formato de nomenclatura é export_errors_YYYYMMDD. Para tabelas particionadas, o formato de nomenclatura é export_errors. Para informações sobre o esquema das tabelas de erro e como evitar incompatibilidades futuras de tipo de campo, consulte Incompatibilidades no esquema.

• As entradas de registro estão fora dos limites de tempo permitidos:

  • Os registros transmitidos para a tabela particionada do BigQuery estão fora dos limites de tempo permitidos. O BigQuery não aceita registros que estão muito distantes no passado ou no futuro.

  • Atualize o coletor para encaminhar esses registros para o Cloud Storage e usar um job de carga do BigQuery. Para mais informações, consulte a documentação do BigQuery.

• O conjunto de dados não permite que a conta de serviço associada ao coletor de registros grave nele:

  • Mesmo que o coletor tenha sido criado com as permissões de conta de serviço corretas, essa mensagem de erro será exibida se não houver uma conta de faturamento válida associada ao projeto do Google Cloud que contenha o destino do coletor.

  • Verifique se há uma conta de faturamento vinculada ao seu projeto do Google Cloud. Se uma conta de faturamento não estiver vinculada ao projeto do Google Cloud de destino do coletor, ative o faturamento desse projeto ou atualize o destino do coletor para que ele fique localizado em um projeto do Google Cloud que tenha uma conta de faturamento válida vinculada a ele.

• O conjunto de dados contém entradas de registro duplicadas:

  • Entradas de registro duplicadas podem ocorrer quando há falhas nos registros de streaming para o BigQuery, inclusive devido a novas tentativas ou configurações incorretas. O Cloud Logging elimina a duplicação de entradas de registro com os mesmos timestamp e insertId no momento da consulta. O BigQuery não elimina entradas de registro duplicadas.

  • Para ignorar entradas de registro duplicadas no BigQuery, inclua a cláusula SELECT DISTINCT na consulta. Exemplo:

  SELECT DISTINCT insertId, timestamp FROM TABLE_NAME
  

Erros ao rotear para buckets do Cloud Logging

É possível encontrar uma situação em que é possível ver os registros no Explorador de registros que você excluiu com o coletor. É possível ainda ver esses registros se qualquer uma das seguintes condições for verdadeira:

• Você está executando sua consulta no projeto do Google Cloud que gerou os registros.

  Para corrigir isso, verifique se você está executando sua consulta no projeto correto do Google Cloud.

• Os registros excluídos foram enviados a vários buckets. Você está vendo uma cópia do mesmo registro que pretende excluir.

  Para corrigir isso, verifique seus coletores na página Roteador de registros para garantir que você não esteja incluindo os registros nos filtros de outros coletores.

• Você tem acesso a visualizações no bucket de registro para onde os registros foram enviados. Nesse caso, você poderá ver esses registros por padrão.

  Para evitar que esses registros apareçam na Análise de registros, é possível refinar o escopo da pesquisa para o projeto ou bucket de origem do Google Cloud.

Solução de problemas com o armazenamento de registros

Por que não consigo excluir esse bucket?

Se você estiver tentando excluir um bucket, faça o seguinte:

• Verifique se você tem as permissões corretas para excluir o bucket. Para a lista das permissões necessárias, consulte Controle de acesso com o IAM.

• Determine se o bucket está bloqueado listando os atributos do bucket. Se o bucket estiver bloqueado, verifique o período de armazenamento do bucket. Não é possível excluir um bucket bloqueado até que todos os registros nele tenham cumprido o período de armazenamento.

• Verifique se o bucket de registros não tem um conjunto de dados do BigQuery vinculado. Não é possível excluir um bucket de registros com um conjunto de dados vinculado.

  O erro a seguir é mostrado em resposta a um comando delete em um bucket de registros que tem um conjunto de dados vinculado:

  FAILED_PRECONDITION: This bucket is used for advanced analytics and has an active link. The link must be deleted first before deleting the bucket
  

  Para listar os links associados a um bucket de registros, execute o comando [gcloud logging links list][link-list] ou o método de API projects.locations.buckets.links.list.

Quais contas de serviço estão roteando registros para meu bucket?

Para determinar se alguma conta de serviço tem permissões de IAM para rotear registros para o bucket, faça o seguinte:

1. No painel de navegação do console do Google Cloud, selecione IAM:

   Acessar o IAM

2. Na guia Permissões, visualize por Papéis. Você verá uma tabela com todos os papéis e principais do IAM associados ao seu projeto do Google Cloud.

3. No campoFiltro caixa de texto, digiteGravador de bucket de registros.

   Você verá todos os principais com o papel de Gravador de bucket de registros. Se um principal for uma conta de serviço, o ID conterá a string gserviceaccount.com.

4. Opcional: se quiser impedir que uma conta de serviço roteie registros para seu projeto do Google Cloud, marque a caixa de seleção para a conta de serviço e clique em Remover.

Por que vejo registros de um projeto do Google Cloud mesmo que eu os tenha excluído do coletor _Default?

É possível visualizar registros em um bucket de registros em um projeto centralizado do Google Cloud, que agrega registros de toda a organização.

Se você estiver usando a Análise de registros para acessar esses registros e ver os registros excluídos do coletor _Default, a visualização poderá estar no escopo do nível do projeto do Google Cloud.

Para corrigir esse problema, selecione Escopo por armazenamento no painel Refinar escopo e selecione o bucket _Default no projeto do Google Cloud. Você não verá mais os registros excluídos.