Resolver problemas de roteamento e armazenamento de registros

Se você tiver problemas ao rotear ou armazenar entradas de registro, use o console doGoogle Cloud para diagnosticar erros de configuração, inspecionar mensagens de erro e resolver registros ausentes.

Para saber como visualizar dados de registro depois que eles chegam a um destino, consulte Ver registros em destinos do coletor.

Resolver problemas de roteamento de registros

Nesta seção, descrevemos como resolver problemas comuns ao rotear entradas de registro.

A criação de um coletor falha com um erro de serviço desconhecido

Você tenta criar um coletor de registros, mas o comando falha com um erro INVALID_ARGUMENT (HTTP 400). A mensagem de erro inclui o seguinte:

Sink.destination with unknown service name: [SERVICE_DOMAIN]. Supported services are bigquery.googleapis.com,pubsub.googleapis.com,storage.googleapis.com,logging.googleapis.com

Para resolver esse erro, use o endpoint global de um dos serviços compatíveis. Um destino de coletor de registros não pode especificar um endpoint de serviço regional (REP, na sigla em inglês), como pubsub.LOCATION.rep.googleapis.com.

A mensagem de erro de configuração do coletor informa que uma região de tópico não é permitida

Ocorre uma das seguintes situações:

  • Você recebe um e-mail com o assunto [ACTION REQUIRED] Cloud Logging sink configuration error in [PROJECT_ID] e o código do erro topic_region_not_allowed. O e-mail inclui uma mensagem semelhante a esta:

    A política de armazenamento de mensagens do tópico exige a aplicação em trânsito, mas a solicitação de publicação foi recebida por um servidor do Pub/Sub em uma região não permitida. Publique usando um endpoint regional do Cloud Logging correspondente a uma região permitida ou atualize a política de armazenamento de mensagens do tópico.

  • Você percebe entradas de registro com um nível de gravidade de ERROR, um código do erro de "topic_region_not_allowed" e um payload de texto semelhante ao seguinte:

    Cloud Logging sink configuration error in [PROJECT_ID], sink [SINK_NAME]: topic_region_not_allowed ()

Essas mensagens indicam que o destino do coletor é um tópico do Pub/Sub que aplica restrições em trânsito e que o Logging roteou entradas de registro de uma região não permitida pela política do tópico. As restrições em trânsito podem ser configuradas na política de armazenamento de mensagens de um tópico individual ou aplicadas em toda a organização usando a restrição de política da organização constraints/pubsub.enforceInTransitRegions.

Para resolver essas falhas, siga um destes procedimentos:

  • Atualize a política de armazenamento de mensagens do tópico de destino do Pub/Sub para desativar a aplicação em trânsito ou expandir as regiões de persistência permitidas.
  • Se as restrições em trânsito forem aplicadas por uma política da organização, atualize-a ou solicite uma isenção para o projeto.
  • Atualize o coletor para encaminhar entradas de registro para um destino diferente.

O destino contém entradas de registro indesejadas

Você está visualizando as entradas de registro roteadas para um destino e determina que ele contém entradas de registro indesejadas.

Para resolver essa condição, atualize os filtros de exclusão dos coletores que encaminham entradas de registro para o destino. Os filtros de exclusão permitem impedir que as entradas de registro selecionadas sejam roteadas para um destino.

Por exemplo, suponha que você crie um coletor agregado para rotear entradas de registro em uma organização para um destino. Para impedir que as entradas de registro de um projeto específico sejam roteadas para o destino, adicione o seguinte filtro de exclusão ao coletor:

logName:projects/PROJECT_ID

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

O destino não tem entradas de registro

Talvez o problema mais comum relacionado ao coletor seja que as entradas de registro parecem estar ausentes do destino de um coletor.

Em alguns casos, um erro não é gerado, mas você pode notar que as entradas de registro não estão disponíveis quando tenta acessá-las no destino. Se você suspeitar que o coletor não está roteando corretamente as entradas de registro, verifique as métricas com base em registros do sistema do coletor:

  • 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 de coletor e nome de destino e informam se o coletor está roteando entradas de registro com êxito ou falha.

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. Somente novas entradas de registro são roteadas.

    Tente aguardar uma hora e verifique o destino novamente.

  • As entradas de registro correspondentes estão atrasadas.

    Pode haver um atraso antes de você visualizar as entradas de registro no destino. Aguarde algumas horas e verifique o destino novamente.

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

  • O escopo que você está usando para visualizar as entradas de registro armazenadas em um bucket de registros está incorreto.

    Defina o escopo da pesquisa para uma ou mais visualizações de registro 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 flag --view=AllLogs.

  • O período que você está usando para selecionar e visualizar dados no destino do coletor é muito restrito.

    Tente ampliar o período que você está usando ao selecionar dados no destino do coletor.

Erro no filtro do coletor

  • O filtro do coletor está incorreto e não está capturando as entradas de registro que você esperava ver 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 seus 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:

Registros de erro

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 entradas de registro, consulte Ver registros usando a Análise de registros.

Use a consulta a seguir no painel do editor de consultas na Análise de registros para analisar 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 problemas. O nome do coletor está disponível na página Roteador de registros no console do Google Cloud .

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

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

{
   errorGroups: [
   0: {
   id: "COXu96aNws6BiQE"
   }]
   insertId: "170up6jan"
   labels: {
      activity_type_name: "LoggingSinkConfigErrorV2"
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      error_code: "topic_not_found"
      error_detail: ""
      sink_id: "my-sink-123"
   }
   logName: "projects/my-project/logs/logging.googleapis.com%2Fsink_error"
   receiveTimestamp: "2024-07-11T14:41:42.578823830Z"
   resource: {
   labels: {
      destination: "pubsub.googleapis.com/projects/my-project/topics/my-topic"
      name: "my-sink-123"
      project_id: "my-project"
   }
   type: "logging_sink"
   }
   severity: "ERROR"
   textPayload: "Cloud Logging sink configuration error in my-project, sink my-sink-123: topic_not_found ()"
   timestamp: "2024-07-11T14:41:41.296157014Z"
}

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

Para resolver essa falha, edite o coletor. Por exemplo, é possível editar o coletor usando a página Roteador de registros:

Acessar o roteador de registros

Notificações por e-mail

Os Contatos essenciais enviam notificações por e-mail de erro de configuração do coletor para os contatos atribuídos à categoria de notificação técnica de um projeto do Google Cloud ou do recurso pai dele. Se o recurso não tiver um contato configurado para notificações técnicas, os usuários listados como Proprietário do projeto do IAM roles/owner para o recurso vão receber a notificação por e-mail.

Para cada combinação de nome do coletor de registros e erro, o sistema envia uma notificação por dia.

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 doGoogle 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, pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID.
  • Código do erro: descrição abreviada da categoria do erro, por exemplo, topic_not_found.
  • Detalhes do erro: informações detalhadas sobre o erro, incluindo recomendações para resolver o problema.

O remetente deste e-mail é logging-noreply@google.com.

O assunto é semelhante a: Subject: [ACTION REQUIRED] Cloud Logging sink configuration error in my-project

Para visualizar e gerenciar seus coletores, use a página 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.

Destino do coletor incorreto

Se você configurar um coletor, mas receber um erro de configuração informando que o destino não foi encontrado quando o Logging tentou rotear entradas de registro, veja alguns possíveis motivos:

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

Para resolver esses tipos de falha, edite o coletor. Por exemplo, é possível editar o coletor usando a página Roteador de registros:

Acessar o roteador de registros

O coletor começa a rotear entradas de registro quando o destino é encontrado e novas entradas de registro que correspondem ao filtro são recebidas pelo Logging.

Problemas de coletor desativado

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

Problemas de permissão com coletores

Quando um coletor tenta rotear uma entrada de registro, mas não tem as permissões do IAM adequadas para o destino, ele informa um erro, que pode ser visualizado, e ignora a entrada de registro.

Ao criar um coletor, a conta de serviço dele precisa receber as permissões de destino adequadas. Se você criar o coletor no console do Google Cloud no mesmo projeto doGoogle Cloud , o console do Google Cloud normalmente vai atribuir essas permissões de forma automática. No entanto, se você criar o coletor em umGoogle Cloud projeto diferente ou usando a CLI gcloud ou a API Logging, será necessário configurar as permissões manualmente.

Se você estiver vendo erros relacionados a permissões no coletor, adicione as permissões necessárias 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 entradas de registro quando as permissões são corrigidas e novas entradas de registro que correspondem ao filtro são recebidas pelo Logging.

Problemas de política da organização com coletores

Se você estiver tentando rotear uma entrada de registro, mas encontrar uma política da organização que restringe o Logging de gravar no destino do coletor, o coletor não poderá rotear para o destino selecionado e informará 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 para o 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.

    Verifique se há uma restrição de local de recurso (constraints/gcp.resourceLocations). Essa restrição determina os locais em que os dados podem ser armazenados. Além disso, alguns serviços são compatíveis com restrições que podem afetar um coletor de registros. Por exemplo, há várias restrições que podem ser aplicadas quando um destino do Pub/Sub é selecionado. Para ver uma lista de possíveis restrições, consulte Restrições de políticas 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.

    Acessar o roteador de registros

O coletor começa a rotear entradas de registro quando a política da organização não bloqueia mais a gravação no destino e novas entradas de registro que correspondem ao filtro são recebidas pelo Logging.

Problemas de chave de criptografia com coletores

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 veja erros relacionados. Confira alguns problemas possíveis e como corrigi-los:

  • 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 Google Cloud atual.

  • 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 localizado em uma região diferente da região do destino, a criptografia vai falhar e o coletor não poderá rotear dados para esse destino.

    • Use uma chave do Cloud KMS contida em um projeto do Google Cloud cuja região 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 de criptografador/descriptografador de CryptoKey do Cloud KMS à 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 com coletores

Quando os coletores gravam entradas de registro, as cotas de exportação e destino são aplicadas. Dependendo do destino, as cotas são aplicadas ao recurso em que o coletor foi criado, como no Pub/Sub, ou ao próprio destino, como no BigQuery. Se a cota for esgotada, o coletor vai parar de rotear entradas de registro para o destino.

  • Os coletores que encaminham entradas de registro para um tópico do Pub/Sub são restritos a 60 GB/min. Se o volume de entradas de registro exceder a cota de taxa de exportação, uma entrada de registro com um código do erro topic_over_quota será gravada.

As cotas também se aplicam a coletores agregados. Esses coletores encaminham entradas de registro para a pasta ou organização em que foram criados e para recursos filhos.

Para corrigir os problemas de esgotamento de cota, tente o seguinte:

  • Diminua a quantidade de dados de registro roteados atualizando o filtro do coletor para corresponder a menos entradas de registro. Use a função sample no filtro para selecionar uma fração do número total de entradas de registro.

  • Envie uma solicitação de suporte para aumentar sua cota.

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

Erros ao rotear para buckets do Cloud Logging

Talvez você encontre uma situação em que é possível ver entradas de registro na Análise de registros que foram excluídas com o coletor. Ainda será possível ver essas entradas de registro se alguma das seguintes condições for verdadeira:

  • Você está executando a consulta no projeto Google Cloud que gerou as entradas de registro.

    Para corrigir isso, verifique se você está executando a consulta no projeto correto doGoogle Cloud .

  • As entradas de registro excluídas foram enviadas para vários buckets de registro. Você está vendo uma cópia do mesmo registro que queria excluir.

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

  • Você tem acesso às visualizações no bucket de registros para onde as entradas de registro foram enviadas. Nesse caso, é possível ver essas entradas de registro por padrão.

    Para evitar que essas entradas de registro apareçam na Análise de Registros, refine o escopo da pesquisa para o projeto ou bucket de origem do Google Cloud .

Resolver problemas de 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 ver a lista de 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.

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 console do Google Cloud , acesse a página IAM:

    Acesse o IAM

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.

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

  4. Opcional: se você quiser remover uma conta de serviço para que ela não possa rotear registros para seu projeto do Google Cloud , marque a caixa de seleção da conta de serviço e clique em Remover.

Por que vejo registros de um projeto do Google Cloud mesmo que eles tenham sido excluídos do meu coletor do _Default?

Talvez você esteja visualizando registros em um bucket de registros em um projeto Google Cloud centralizado, que agrega registros de toda a organização.

Se você estiver usando a Análise de Registros para acessar esses registros e encontrar registros que foram excluídos do coletor _Default, talvez sua visualização esteja definida como o nível do projetoGoogle Cloud .

Para corrigir esse problema, selecione Visualização de registros no menu Refinar escopo e, em seguida, selecione a visualização de registros associada ao bucket _Default no seu projetoGoogle Cloud . Você não verá mais os registros excluídos.