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.

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 um filtro de registros e um destino de exportação. Conforme o Cloud Logging recebe novas entradas de registro, elas são comparadas com cada coletor. Se uma entrada de registro corresponder ao filtro de um coletor, uma cópia dela será gravada no destino.

Os destinos aceitos para entradas de registro exportadas são Cloud Storage, BigQuery, Pub/Sub e Buckets de registros no Cloud Logging.

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.

    Neste projeto, é necessário que você tenha o papel de IAM Proprietário ou Gravador de configuração de registros 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 onde seus registros serão gravados: Cloud Storage, BigQuery ou Pub/Sub.

Primeiros passos

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

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

Interface do usuário do roteador de registros

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

  • Nome: o identificador do coletor no projeto atual.
  • Destino: o local que recebe as entradas de registro exportadas.
  • Estado: indica se o coletor está ativado ou desativado.

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

  • Visualizar detalhes do coletor: exibe o filtro do coletor. Clicar em Editar permite alterar as propriedades ou o filtro do coletor.
  • Editar coletor: abre um painel Editar coletor em que é possível alterar os parâmetros do coletor.
  • Desativar coletor: permite desativar o coletor e parar de rotear os registros para o destino do coletor.
  • Ativar coletor: permite que você ative um coletor desativado e reinicie os registros de roteamento para o destino do coletor.
  • Excluir coletor: permite excluir o coletor e parar de rotear os registros para o destino do coletor. Os coletores _Default e _Required não podem ser excluídos, mas o coletor _Default pode ser desativado para interromper o roteamento de registros para o bucket de registros _Default.

Ao clicar em qualquer um dos nomes de coluna, você organiza 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

É possível criar um coletor usando o Visualizador de registros ou o Roteador de registros.

Como criar um coletor usando o Visualizador de registros (Clássico)

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 bucket 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 que contém os registros, um administrador do novo destino precisará conceder permissão. Você precisa enviar ao administrador a identidade do gravador 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 direcionadas ao destino do coletor. 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 seu projeto no Console do Google Cloud. Para diagnosticar erros comuns, acesse Como solucionar problemas abaixo.

Como criar um coletor usando o roteador de registros

Para rotear registros para um intervalo de registros ou um destino personalizado, conclua as etapas a seguir.

GCLOUD

Para criar um coletor para um destino, execute o comando gcloud alpha logging sinks create:

 gcloud alpha logging sinks create SINK_NAME SINK_LOCATION OPTIONAL_FLAGS

Por exemplo, para criar um coletor para um intervalo de registros do Cloud Logging:

 gcloud alpha logging sinks create my-sink logging.googleapis.com/projects/myproject123/locations/global/buckets/my-bucket --log-filter='logName="projects/myproject123/logs/matched"' --description="My first sink"

CONSOLE

Para criar um coletor para um destino, siga estas etapas:

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. Clique em Criar coletor.

  3. No painel Selecionar serviço do coletor, selecione o destino.

  4. Insira um Nome e uma Descrição para o coletor.

  5. Clique em Próximo.

  6. Em Selecionar destino do coletor, selecione o bucket em que você quer enviar os registros.

  7. Clique em Próximo.

  8. Crie um filtro de inclusão para especificar quais registros serão roteados para o bucket. Ao criar o filtro, clique em Visualizar registros para verificar se você está incluindo os registros corretos.

    Um filtro que talvez você queira criar é um filtro para rotear todos os registros de acesso aos dados para um único bucket. Esse filtro tem a seguinte aparência:

    LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
    

  9. Quando terminar, clique em Próxima.

  10. Outra opção é criar um filtro de exclusão para especificar quais registros excluir do bucket.

    Para mais informações sobre filtros, consulte Como usar filtros de exclusão e Filtros em casos de uso comuns.

  11. Quando terminar, clique em Criar coletor. O novo coletor aparecerá na lista Coletores de roteamento de registros.

Como rotear registros de um projeto para um bucket em um projeto diferente

Para rotear os registros do projeto atual para um bucket em um projeto diferente, siga as etapas a seguir.

Os coletores de bucket entre projetos exigem a adição das permissões de gerenciamento de identidade e acesso apropriadas à conta de serviço que o Logging cria para esses coletores.

GCLOUD

  1. Se você não tiver feito isso, crie um bucket no outro projeto:

    gcloud alpha logging buckets create BUCKET_ID --project=DESTINATION_PROJECT_ID
  2. Crie um coletor para rotear os registros para o outro bucket:

    gcloud alpha logging sinks create SINK_NAME \
    logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/global/buckets/BUCKET_ID \
    --log-filter='FILTER_CONDITIONS'
  3. Consiga a conta de serviço do campo writerIdentity no seu coletor:

    gcloud alpha logging sinks describe SINK_NAME

    A conta de serviço é semelhante a esta:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
  4. Conceda o papel roles/logging.bucketWriter à conta de serviço.

    1. Receba a política de gerenciamento de identidade e acesso do projeto de destino e grave-a em um arquivo local no formato JSON:

      gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json
    2. Adicione uma condição do IAM que permita à conta de serviço gravar apenas no bucket criado. Exemplo:

      {
      "bindings": [
       {
         "members": [
           "user:username@gmail.com"
         ],
         "role": "roles/owner"
       },
      {
         "members": [
           "[SERVICE_ACCOUNT]"
         ],
         "role": "roles/logging.bucketWriter",
         "condition": {
             "title": "Bucket writer condition example",
             "description": "Grants logging.bucketWriter role to service account [SERVICE_ACCOUNT] used by log sink [SINK_NAME]",
             "expression":
               "resource.name.endsWith(\"locations/global/buckets/[BUCKET_ID]\")"
         }
       }
      ],
      "etag": "BwWd_6eERR4=",
      "version": 3
      }
    3. Atualize a política do IAM:

      gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json

CONSOLE

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. Clique em Criar coletor.

  3. Na janela Selecionar serviço de coletor, selecione o destino e clique em Avançar.

  4. Na seção Detalhes do coletor, insira Sink name e Sink description.

  5. Clique em Próximo.

  6. No campo Destino do coletor, insira o local do bucket do projeto de destino.

    logging.googleapis.com/projects/[DESTINATION_PROJECT_ID]/locations/global/buckets/[BUCKET_ID]
    
  7. Crie um filtro de inclusão para especificar quais registros serão roteados para o bucket. Ao criar o filtro, clique em Visualizar registros para verificar se você está incluindo os registros corretos.

    Um filtro que talvez você queira criar é um filtro para rotear todos os registros de acesso aos dados para um único bucket. Esse filtro tem a seguinte aparência:

    LOG_ID("cloudaudit.googleapis.com/data_access") OR LOG_ID("externalaudit.googleapis.com/data_access")
    

  8. Quando terminar de criar o filtro, clique em Próxima.

  9. Opcional: especifique quais entradas de registro excluir do bucket.

    Para mais informações sobre filtros, consulte Como usar filtros de exclusão e Filtros em casos de uso comuns.

  10. Quando terminar, clique em Criar coletor. O novo coletor aparecerá na lista Coletores de roteamento de registros.

  11. Consiga a conta de serviço do campo writerIdentity no seu coletor:

    gcloud alpha logging sinks describe SINK_NAME

    A conta de serviço é semelhante a esta:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
  12. Conceda o papel roles/logging.bucketWriter à conta de serviço.

    1. Receba a política de gerenciamento de identidade e acesso do projeto de destino e grave-a em um arquivo local no formato JSON:

      gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json
    2. Adicione uma condição do IAM que permita à conta de serviço gravar apenas no bucket criado. Exemplo:

      {
      "bindings": [
       {
         "members": [
           "user:username@gmail.com"
         ],
         "role": "roles/owner"
       },
      {
         "members": [
           "[SERVICE_ACCOUNT]"
         ],
         "role": "roles/logging.bucketWriter",
         "condition": {
             "title": "Bucket writer condition example",
             "description": "Grants logging.bucketWriter role to service account [SERVICE_ACCOUNT] used by log sink [SINK_NAME]",
             "expression":
               "resource.name.endsWith(\"locations/global/buckets/[BUCKET_ID]\")"
         }
       }
      ],
      "etag": "BwWd_6eERR4=",
      "version": 3
      }
    3. Atualize a política do IAM:

      gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json

Como atualizar coletores

Atualizar um coletor no Visualizador de registros (Clássico)

Para atualizar um coletor, selecione o comando Editar coletor no menu à direita do nome do coletor. Você pode alterar qualquer um destes parâmetros:

  • Destino
  • Consulta

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

Atualizar um coletor no roteador de registros

Para editar os coletores existentes usando o roteador de registros, conclua as etapas a seguir.

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. No coletor que você quer visualizar, clique em Mais .

  3. Clique em Editar coletor.

  4. Edite o coletor conforme necessário.

  5. Quando terminar, clique em Atualizar coletor.

Como excluir coletores

A exclusão de um coletor o remove do Cloud Logging e impede que registros futuros sejam roteados para o destino.

Como excluir um coletor no Visualizador de registros (clássico)

Para excluir um coletor, selecione-o 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.

Como excluir um coletor no roteador de registros

Para excluir o coletor, conclua os passos a seguir.

CONSOLE

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. No coletor que você quer excluir, clique em Mais .

  3. Selecione Excluir coletor.

  4. No painel de confirmação, clique em Excluir.

  5. O coletor foi excluído.

Como desativar coletores

Desativar um coletor impede que registros futuros sejam encaminhados para o destino, mas não remove o coletor do Cloud Logging.

Como desativar o coletor usando o roteador de registros

Para desativar o coletor, conclua as etapas a seguir.

CONSOLE

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. No coletor que você quer desativar, clique em Mais .

  3. Selecione Desativar coletor.

  4. No painel de confirmação, clique em Desativar.

  5. O estado do coletor muda para Desativado.

Como ativar coletores

A ativação de um coletor reinicia um coletor desativado e retoma os registros de roteamento para o destino.

Como ativar o coletor desativado

Para ativar o coletor desativado, conclua as etapas a seguir.

CONSOLE

  1. No menu do Logging, selecione Roteador de registros.

    Acessar o roteador de registros

  2. No coletor que você quer ativar, clique em Mais .

  3. Selecione Ativar coletor.

  4. No painel de confirmação, clique em Ativar.

  5. O estado do coletor muda para Ativado.

Permissões de destino

Esta seção descreve como você pode conceder ao Logging as permissões de Gerenciamento de identidade e acesso para gravar 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 é gerenciada e pertence ao 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 o coletor no Console do Cloud e tiver acesso Proprietário ao destino, o registro do 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 estiver usando a API do Logging, será possível conseguir a identidade do gravador 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 bucket 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 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 precisará seguir as instruções contidas no passo 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 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 seu 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 Coletores agregadores.

Resolver 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 corrigir 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 Filters, 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 bucket [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 bucket. Adicione as permissões necessárias ao bucket ou atualize o coletor para usar um bucket diferente. Veja as permissões de destino.
Não existe nenhum bucket com o nome: [YOUR_BUCKET]. Pode haver um erro no nome do bucket ou o bucket pode ter sido excluído. Atualize o coletor com o destino de bucket 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 bucket foi definido como uniforme quando o bucket 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 bucket. Para os buckets atuais, é 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.

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ê pode ter 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