Neste documento, explicamos problemas comuns de roteamento e armazenamento e como usar o console do Google Cloud para conferir e resolver 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 resolver 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 encaminham registros para o destino. Os filtros de exclusão permitem que você impeça que os registros selecionados sejam roteados para um destino.
Por exemplo, suponha que você crie um coletor agregado para encaminhar os registros de uma organização a 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 combinar 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.
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 registros corretamente, 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 do coletor e pelo nome do destino e informam se o coletor está roteando dados de registros com sucesso ou não. Para saber como visualizar métricas, consulte Visão geral das métricas com base em registros.
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 seu 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 até que você possa ver seus registros no destino. Registros de chegada tardia são especialmente comuns para coletores que configuraram buckets do Cloud Storage como destinos. Tente aguardar algumas horas e verifique o destino novamente.
O escopo/filtro de visualização está incorreto
O escopo que você está usando para visualizar registros nos destinos do bucket de registro está incorreto.
Defina o escopo da pesquisa em uma ou mais visualizações de armazenamento da seguinte maneira:
Se você estiver usando o Explorador de registros, use o botão Refine scope.
Se você estiver usando a CLI gcloud, use o comando
gcloud logging reade adicione uma flag--view=AllLogs.
O período que você está usando para [selecionar e visualizar dados no destino do coletor][export-log-bucket é muito curto.
Amplie o período que você está usando ao selecionar dados no destino de coletor.
Erro no filtro de sumidouro
O filtro do coletor está incorreto e não está capturando os registros que você esperava encontrar no seu 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 o Explorador 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. O remetente deste e-mail
é
logging-noreply@google.com.
Registros de erro
O método recomendado para inspecionar detalhes relacionados ao coletor é visualizar as entradas de registro de erros geradas pelo coletor. Para saber como visualizar registros, consulte Ver registros usando o Explorador de registros.
Use a consulta a seguir no painel do editor de consultas no Explorador de registros para analisar os registros de erro 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. Encontre 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="SINK_NAME"
Por exemplo, se o nome do coletor for my-sink-123, a entrada de registro poderá 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 de 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 a sink. Por exemplo, você pode editar o coletor usando a página Roteador de registros:
Acessar o roteador de registros
Notificações por e-mail
O Essential Contacts envia notificações por e-mail sobre erros 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.
Se o recurso não tiver um contato configurado para notificações técnicas,
os usuários listados como proprietários do projeto do IAM roles/owner para o
recurso vão receber 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,
pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID - Código do erro: é uma descrição abreviada da categoria de 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.
Para conferir e gerenciar os 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.
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 encontrou um erro de configuração dizendo que o destino não pôde ser encontrado quando o Logging tentou rotear registros, confira 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 sua sink]]export-manage-sink. Por exemplo, é possível editar o coletor usando a página 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 sink para interromper o armazenamento de registros em um bucket, mas ainda vê registros sendo roteados, aguarde alguns minutos para que as mudanças sejam aplicadas ao sink.
Problemas de permissões.
Quando um coletor tenta encaminhar uma entrada de registro, mas não tem as permissões do IAM apropriadas para o destino do coletor, o coletor informa um erro, que pode ser visualizado, e ignora 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 normalmente vai atribuir essas permissões automaticamente. No entanto, se você criar o coletor em um projeto do Google Cloud diferente 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 do 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 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 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 e remova as restrições que bloqueiam o coletor das entradas de registro de roteamento. Isso pressupõe que você tenha as permissões adequadas para atualizar a política da organização.
É possível examinar se uma restrição de local de recursos (
constraints/gcp.resourceLocations) existe. Essa restrição determina os locais em que os dados podem ser armazenados. Além disso, alguns serviços oferecem suporte a 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 conferir uma lista de possíveis restrições, consulte Restrições da política da organização.Para instruções, consulte Criar e editar políticas.
Se não for possível atualizar a política da organização, atualize o coletor na página do Roteador de registros para usar um destino compatível.
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, você poderá encontrar erros relacionados. Confira 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 válida vinculada ao projeto do Google Cloud que contém a chave. Se uma conta de faturamento não estiver vinculada ao projeto do Google Cloud, ative o faturamento dele 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 do Cloud KMS válida de um projeto 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 localizado 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 em 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
writerIdentitydo 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 de destino se aplicam 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:
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:
- Verifique se a conta de serviço do coletor de registros tem as permissões corretas. Para mais informações, consulte a seção Problemas de permissões deste documento.
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 tentar encaminhar entradas de registro com diferentes tipos de dados, 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 erros e como evitar incompatibilidades de tipo de campo no futuro, 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 corretas da conta de serviço, 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 o destino do coletor.
Verifique se há uma conta de faturamento vinculada ao projeto do Google Cloud. Se uma conta de faturamento não estiver vinculada ao projeto do Google Cloud do destino do coletor, ative o faturamento para esse projeto do Google Cloud ou atualize o destino do coletor para que ele esteja localizado em um projeto do Google Cloud com 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 no streaming de registros para o BigQuery, inclusive devido a novas tentativas ou configurações incorretas. O Cloud Logging elimina entradas de registro com o mesmo
timestampeinsertIdno 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 DISTINCTna 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 a consulta no projeto do Google Cloud que gerou os registros.
Para corrigir isso, execute a 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 no Explorador de registros, é possível refinar o escopo da pesquisa para o bucket ou o projeto do Google Cloud de origem.
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 conferir 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.
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
deleteem 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étodoprojects.locations.buckets.links.listda API.
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:
-
No console do Google Cloud, abra a página IAM.
Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.
Na guia Permissões, visualize por Papéis. Você vai encontrar uma tabela com todos os papéis e principais do IAM associados ao seu projeto do Google Cloud.
No campoFiltro caixa de texto filter_list, 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.Opcional: se quiser remover uma conta de serviço para que ela não possa rotear registros para o projeto do Google Cloud, marque a caixa de seleção check_box_outline_blank da conta de serviço e clique em Remover.
Por que vejo registros de um projeto do Google Cloud mesmo após excluí-los do meu 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 o Explorador de registros para acessar esses registros e conferir os registros que você
excluiu do coletor _Default, talvez sua visualização esteja definida no
nível do projeto do Google Cloud.
Para corrigir esse problema, selecione Visualização de registro no menu Refinar escopo e, em seguida, selecione a visualização de registro associada ao bucket _Default no seu projeto do Google Cloud. Você não verá mais os registros excluídos.