Como exportar com o visualizador de registros

Nesta página, você verá como exportar entradas de registro usando o Console do Cloud. Também é possível exportar entradas de registro usando a API Cloud Logging ou a ferramenta de linha de comando gcloud logging.

Para uma visão geral conceitual sobre como exportar registros no Logging, consulte esta página. Em resumo, você exporta registros criando um ou mais coletores que incluem uma consulta de registros e um destino de exportação. Conforme o Cloud Logging recebe novas entradas de registro, elas são comparadas em cada coletor. Se uma entrada de registro corresponder à consulta de um coletor, uma cópia da entrada de registro será gravada no destino da exportação.

Os destinos compatíveis com entradas de registro exportadas são Cloud Storage, BigQuery e Pub/Sub.

Para saber como os registros exportados são formatados e organizados, além de saber como visualizá-los, acesse Como usar registros exportados.

Antes de começar

  • Projeto: você precisa ter um projeto do Google Cloud com registros que possa ver no visualizador de registros.

    Também é necessário ter os papéis de proprietário ou gravador de configurações de registros/Logging do Cloud IAM no projeto para criar, excluir ou modificar um coletor. Acesse Permissões e papéis para mais informações.

  • Serviço de destino: para exportar registros, você precisa se inscrever no serviço do Google Cloud em que seus registros serão gravados: Cloud Storage, BigQuery ou Pub/Sub.

Primeiros passos

  1. Acesse Cloud Logging > Roteador de registros no Console do Cloud:

    Acessar o roteador de registros

  2. Selecione um projeto atual do Google Cloud na parte superior da página.

A captura de tela a seguir mostra um exemplo da página Roteador de registros, em que vários coletores de registro já estão configurados:

A interface do usuário mostrando a lista de exportações.

Se você ainda não tiver configurado nenhum coletor de registro, a mensagem Nenhum coletor de registro está configurado será exibida.

Interface do usuário do Roteador de registros

A interface Roteador de registros contém um resumo da tabela de exportações. Cada linha da tabela contém informações correspondentes a algumas das propriedades do coletor descritas nas exportações de registro:

  • Nome do coletor: o identificador do coletor no projeto atual.
  • Destino: o local que recebe as entradas de registro exportadas.
  • Identidade de gravador: a conta de serviço que o Logging usa para gravar entradas de registro no destino. Essa conta de serviço precisa ter permissão para gravar no destino do coletor.

Cada linha da tabela tem um menu à direita e apresenta as seguintes opções:

  • Editar coletor: abre um painel Editar coletor em que é possível alterar os parâmetros do coletor.
  • Excluir coletor: permite excluir o coletor e interromper a exportação de registros.
  • Visualizar detalhes do coletor: exibe a consulta do coletor. Clicar em Editar permite alterar as propriedades ou a consulta do coletor.

A caixa de pesquisa acima da tabela permite consultar seus coletores por pesquisa de texto ou por estas propriedades de coletor: Nome do coletor, Destino e Identidade do gravador. Por exemplo, a captura de tela a seguir mostra uma pesquisa em Destino bigquery e opções para relacionar outras propriedades do coletor ao argumento por OR (AND é o padrão):

A interface do usuário mostrando uma consulta de pesquisa.

Além disso, clicar em qualquer um dos nomes das colunas permite organizar os dados em ordem crescente ou decrescente. Na parte inferior da tabela, também é possível selecionar o número de linhas que você quer que sejam exibidas.

Como criar coletores

Para criar um coletor de exportação, clique em Criar coletor na parte superior da página Roteador de registros. Também é possível fazer isso na parte superior da página do visualizador de registros.

Se sua conta de serviço não tiver permissão para criar exportações para o projeto, essa opção não estará disponível. Analise a seção Antes de começar acima para mais informações.

A captura de tela a seguir mostra o painel Editar coletor com alguns campos preenchidos:

A interface do usuário mostrando o painel de edição da exportação.

Para criar um coletor, preencha o painel Editar coletor da seguinte maneira:

  1. (filtro): insira uma consulta de registros avançada. Você não precisa de aspas ao redor da consulta e é possível usar várias linhas. A consulta inicial é determinada pelas entradas de registro que são exibidas quando você clica em Criar exportação.

    Sempre que você editar a consulta, clique em Enviar consulta para exibir as entradas de registro correspondentes. Clique em Ir para os registros mais recentes para buscar os mais atuais.

    Se você quer usar a interface de visualização básica para selecionar os registros, use o menu suspenso na caixa de pesquisa.

  2. Nome do coletor: insira o identificador que será atribuído ao coletor.

  3. Serviço do coletor: selecione um serviço de destino: Cloud Storage, Pub/Sub, BigQuery ou Destino personalizado.

    Um destino de exportação personalizado precisa estar no Cloud Storage, no BigQuery ou no Pub/Sub, mas permite enviar registros a um coletor em um projeto diferente do Google Cloud. A origem e o destino do coletor não precisam estar na mesma organização do Google Cloud.

  4. Destino do coletor:

    1. Cloud Storage: selecione ou crie o intervalo específico para receber os registros exportados.
    2. Pub/Sub: selecione ou crie o tópico específico para receber os registros exportados.
    3. BigQuery: selecione ou crie o conjunto de dados específico para receber os registros exportados. Você também tem a opção de usar tabelas particionadas.
    4. Destino personalizado: inclua o projeto do Cloud Storage, Pub/Sub ou BigQuery como uma string. Para informações sobre a formatação do nome do projeto, leia Propriedades de coletor.
  5. Clique em Atualizar coletor para criar o coletor.

    Como parte da criação do coletor, o Logging tenta conceder a permissão de identidade de gravador do coletor para gravar no destino. Se você estiver exportando para um destino em um projeto diferente daquele em que estão os registros, um administrador do novo destino precisará conceder permissão. Você precisa enviar ao administrador a identidade do escritor do coletor, que é listada com o coletor na página Roteador.

Novas entradas de registro que correspondem ao seu coletor começarão a ser exportadas. As entradas de registro no BigQuery ou no Pub/Sub são transmitidas imediatamente para esses destinos de exportação. As entradas de registro no Cloud Storage são gravadas em lote e enviadas aproximadamente a cada hora. Para mais informações, acesse Como usar registros exportados.

Se o Logging encontrar erros ao tentar exportar registros para o destino, os erros serão exibidos no Stream de atividades do projeto. Selecione Atividade na parte superior da página inicial do projeto no Console do Google Cloud. Para diagnosticar erros comuns, acesse Como solucionar problemas abaixo.

Como atualizar coletores

Para atualizar um coletor, selecione o comando Editar coletor no menu à direita do nome do coletor. É possível alterar qualquer um destes parâmetros:

  • Destino
  • Consulta

Para alterar outros parâmetros dos coletores, use o método projects.sinks.update da API.

Como excluir coletores

Para excluir um coletor, selecione o coletor na página Roteador e clique em Excluir na parte superior da página. Como alternativa, selecione Excluir coletor do menu à direita do nome do coletor.

Permissões de destino

Nesta seção, você verá como é possível conceder ao Logging as permissões do Cloud Identity and Access Management para gravar os registros exportados no destino de exportação do seu coletor.

Quando você cria um coletor, o Logging cria uma nova conta de serviço para ele, chamada de identidade única de gravador. Não é possível gerenciar essa conta de serviço diretamente, porque ela é de propriedade e gerenciada pelo Cloud Logging. A conta de serviço será excluída se o coletor for excluído.

Essa conta de serviço precisa ter permissão do destino de exportação para gravar entradas de registro. Para configurar essa permissão, siga estas etapas:

  1. Crie o novo coletor no Console do Cloud, na interface da linha de comando gcloud logging ou na API do Logging.

  2. Se você tiver criado seu coletor no Console do Cloud e tiver acesso Proprietário ao destino, o Cloud Logging terá configurado as permissões necessárias em seu nome. Se ele fez isso, está tudo pronto. Caso contrário, continue.

  3. Consiga a identidade de gravador do coletor (um endereço de e-mail) com o novo coletor:

    • Se você estiver usando o Console do Cloud, a identidade do gravador aparecerá na listagem do coletor na página Roteador.
    • Se você estiver usando a API do Logging, poderá conseguir a identidade do gravador a partir do objeto LogSink.
    • Se você estiver usando gcloud logging, as identidades do gravador serão exibidas quando você listar seus coletores.
  4. Caso você tenha acesso de Proprietário ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor ao intervalo e conceda o papel de criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor ao conjunto de dados e conceda o papel de editor de dados do BigQuery.
    • Para o Pub/Sub, adicione a identidade do gravador do coletor ao seu tópico e atribua a ele o papel de editor do Pub/Sub.

    Isso conclui a autorização.

  5. Se você não tiver acesso de Proprietário ao destino de exportação, envie o nome da conta de serviço da identidade de gravador para alguém que tenha. Essa pessoa precisa seguir as instruções contidas na etapa anterior para adicionar a identidade de gravador ao destino de exportação.

Atrasos de autorização

Se um coletor tentar exportar uma entrada de registro, mas não tiver a permissão apropriada do Cloud IAM para o destino de exportação, o coletor informará um erro e ignorará a entrada de registro. Isso continua até que a permissão seja concedida, quando o coletor começará a exportar novas entradas de registro.

Há uma espera 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. Durante as primeiras 24 horas após a criação do coletor, será possível ver mensagens de erro relacionadas à permissão do coletor na página Atividade do projeto, mas ignore-as.

Vantagens e limitações

O Console do Cloud tem as seguintes vantagens sobre o uso da API do Logging:

  • O Console do Cloud mostra todos os seus coletores em um só lugar.
  • O Console do Cloud mostra quais entradas de registro correspondem à consulta do coletor antes de criar um.
  • O Console do Cloud pode criar e autorizar destinos de exportação para seus coletores.

No entanto, o Console do Cloud só pode criar ou visualizar coletores em projetos. Para criar coletores em organizações, pastas ou contas de faturamento, leia Exportações agregadas.

Solução de problemas

Veja alguns problemas comuns que podem ser encontrados ao exportar registros e o que fazer com eles:

  • Erros do destino: verifique a especificação do destino de exportação no coletor. Use projects.sinks.get para encontrar a identidade do gravador do coletor e confirme se a identidade tem permissão para gravar no destino de exportação.

  • Nenhum registro está sendo exportado: estes são alguns motivos possíveis:

    • Sua consulta está incorreta. Verifique sua consulta de exportação para confirmar se as entradas de registro correspondentes à sua consulta chegaram recentemente ao Logging e corrija erros de formatação ou de ortografia.

    • Nenhuma entrada de registro correspondente foi recebida desde que você criou ou atualizou seu coletor. Somente novas entradas de registro são exportadas.

      Há uma espera para que seja possível visualizar seus registros exportados no destino. Esse é o caso específico dos destinos do Cloud Storage. Para mais detalhes, acesse Disponibilidade de registros exportados.

      Também é possível verificar as métricas do sistema de exportação. Elas podem informar quantas entradas de registro são exportadas e quantas são descartadas devido a erros.

O coletor começa a exportar registros quando algum erro é solucionado.

Para visualizar os erros de coletor usando o visualizador de registros, faça o seguinte:

  1. Acesse o stream de atividades para o projeto ou outro recurso em que o coletor foi criado:

    Acessar stream de atividades

  2. No painel Filtros, selecione Tipos de atividade > Configuração e Tipo de recurso > Coletor de exportação do Cloud Logging.

  3. Ajuste Data/hora para visualizar erros de coletor no período apropriado.

    Os erros de coletor aparecerão.

Nas próximas seções, você verá uma lista de alguns erros e resultados inesperados específicos do serviço e a explicação do que fazer com eles.

Erros ao exportar para o Cloud Storage

A tabela a seguir mostra a lista dos erros mais comuns ao exportar registros para o Cloud Storage:

Erro Causa Solução
As permissões no intervalo [YOUR_BUCKET] não autorizam o grupo de registros a criar novos objetos. A identidade do gravador do coletor não tem as permissões corretas para o intervalo. Adicione as permissões necessárias ao intervalo ou atualize o coletor para usar um intervalo diferente. Veja as permissões de destino.
Não existe nenhum intervalo com o nome: [YOUR_BUCKET]. Pode haver um erro no nome do intervalo ou o intervalo pode ter sido excluído. Atualize o coletor com o destino de intervalo correto.
Coletor criado com sucesso. No entanto, não foi possível conceder permissões corretas ao destino. O modelo de controle de acesso do intervalo foi definido como uniforme quando o intervalo foi criado.

Essa mensagem de erro continua a ser exibida após a inclusão da conta de serviço.
Selecione o modelo de controle de acesso Detalhado durante a criação do intervalo. Para os intervalos atuais, é possível alterar o modelo de controle de acesso para os primeiros 90 dias após a criação do intervalo usando a guia Permissões.

Erros ao exportar para o BigQuery

A tabela a seguir mostra a lista dos erros mais comuns ao exportar registros para o BigQuery:

Erro Causa Solução
As permissões no conjunto de dados [YOUR_DATASET] não autorizam o grupo de registros a criar novas tabelas. A identidade do gravador do coletor não tem permissões suficientes para o conjunto de dados. Adicione a permissão ao conjunto de dados. Veja as permissões de destino.
Não existe nenhum conjunto de dados com o nome: [YOUR_DATASET]. Pode haver um erro no destino do coletor ou alguém pode ter excluído o conjunto de dados. Recrie o conjunto de dados ou atualize o coletor de exportação para usar um conjunto de dados diferente.
Os registros enviados para a tabela [YOUR_TABLE] no conjunto de dados [YOUR_DATASET] não correspondem ao esquema da tabela. Você está tentando exportar registros que são incompatíveis com o esquema da tabela atual. Verifique se as entradas de registro correspondem ao esquema da tabela. Um dos problemas comuns é o envio de entradas de registro com tipos diferentes de dados. Por exemplo, um dos campos na entrada de registro é um número inteiro, enquanto uma coluna correspondente no esquema tem um tipo de string. O stream de atividades contém um link para uma das entradas de registro inválidas. Depois de corrigir a origem do erro, é possível renomear a tabela atual e permitir que o Logging crie a tabela novamente.
A cota de inserção de streaming por tabela foi excedida para a tabela [YOUR_TABLE] no conjunto de dados [YOUR_DATASET]. Você está exportando um número excessivo de entradas de registro muito rapidamente. Veja os limites de cota padrão do BigQuery, que se aplicam ao streaming de registros. Diminua a quantidade de dados de registro que o coletor gera. É possível atualizar a consulta do coletor para corresponder a menos entradas de registro ou usar a função sample().
Os registros transmitidos para a tabela particionada [YOUR_TABLE] estão fora dos limites de tempo permitidos. O BigQuery não é compatível com registros muito antigos ou futuros. Os registros fora dos limites de tempo permitidos não podem ser exportados com coletores. Exporte esses registros para o Cloud Storage e use um job de carga do BigQuery em seu lugar. Para mais informações, consulte a documentação do BigQuery.
Os registros não podem ser transmitidos para o conjunto de dados [YOUR_DATASET] porque essa operação é proibida por uma política da organização. Há uma política de organização que impede gravações no conjunto de dados selecionado. Consulte a documentação para mais detalhes sobre políticas da organização. Modifique seu coletor de exportação para usar um conjunto de dados compatível.

Erros ao exportar registros para o Pub/Sub

A tabela a seguir mostra a lista dos erros mais comuns ao exportar registros para Pub/Sub:

Erro Causa Solução
[ACCOUNT] precisa ter permissão de edição em [PROJECT] para publicar em [TOPIC]. A identidade do gravador do coletor não tem as permissões corretas para o tópico. Adicione as permissões necessárias ao projeto. Veja as permissões de destino.
O tópico [TOPIC] não existe. Você talvez tenha excluído o tópico configurado para receber os registros exportados. Recrie o tópico com o mesmo nome ou altere a configuração de exportação para usar um tópico diferente.

A seguir