Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como exportar registros com o Console do Google Cloud

Nesta página, explicamos como exportar entradas de registro usando o Console do Cloud e a ferramenta de linha de comando gcloud.

Também é possível exportar entradas de registro usando a API Cloud Logging.

Para ter uma visão geral conceitual sobre como exportar registros, consulte Visão geral das exportações de registros. 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.

É possível exportar registros para os seguintes destinos:

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

Como criar e gerenciar coletores com o Explorador de registros e o roteador de registros

Usando o Console do Cloud, você pode:

  • Visualizar todos os coletores em um só lugar.
  • Veja quais entradas de registro correspondem ao filtro do seu coletor antes de criar um.
  • 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 usando a ferramenta de linha de comando gcloud ou a API do Cloud Logging, consulte Coletores agregados.

Antes de criar um coletor, verifique o seguinte:

  • Você tem um projeto do Google Cloud com registros que podem ser vistos no Explorador de registros.

  • Você tem os papéis de IAM Proprietário ou Gravador de configuração de registros no projeto do Cloud para criar, excluir ou modificar um coletor. Acesse Permissões e papéis para mais informações.

  • Você tem um serviço de destino ou pode criar um serviço de destino.

Como criar um coletor

  1. Para criar um coletor na página Roteador de registros, selecione Criar coletor.

    Selecione "Criar coletor" no roteador de registros

    Para criar um coletor na página Explorador de registros, selecione Ações > Criar coletor.

    Menu mostrando a opção "Criar coletor".

    Depois de selecionar Criar coletor em uma das páginas, conclua as etapas a seguir no painel Criar coletor de roteamento de registros.

  2. Insira os detalhes do coletor:

    • Nome do coletor: forneça um identificador para o coletor.

    • Descrição do coletor (opcional): descreva a finalidade ou o caso de uso do coletor.

  3. Insira o destino do coletor:

    • Selecione o serviço do coletor: selecione o serviço em que você quer rotear seus registros.

    Os serviços e destinos a seguir estão disponíveis:

    • bucket de registro do Cloud Logging: selecione ou crie um bucket de registros.
    • 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.
    • Cloud Storage: selecione ou crie o bucket específico do Cloud Storage para receber os registros exportados.
    • Pub/Sub: selecione ou crie o tópico específico para receber os registros exportados.
    • Splunk: selecione o tópico do Pub/Sub do serviço Splunk.
    • Outro projeto: adicione o serviço e o destino do Google Cloud no seguinte formato:

      SERVICE.googleapis.com/projects/PROJECT_ID/DESTINATION/DESTINATION_ID
      

      Por exemplo, se o destino da exportação for um conjunto de dados do BigQuery, o destino do coletor será o seguinte:

      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
      

  4. Escolha os registros a serem incluídos no coletor:

    • Crie um filtro de inclusão: insira um filtro para selecionar os registros que você quer rotear para o destino do coletor.

    Um filtro que você pode criar é um filtro para rotear todos os registros de acesso a 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")
    

    Para conferir se você inseriu o filtro correto, selecione Visualizar registros. Isso abre o Explorador de registros em uma nova guia com o filtro pré-preenchido. Para mais informações sobre como criar um filtro, consulte Linguagem de consulta do Logging.

  5. Escolha registros para excluir do coletor (opcional):

    • Crie um filtro de exclusão: selecione Adicionar exclusão e insira um filtro para selecionar os registros que você não quer que sejam roteados para o destino do coletor.

    • Nome do filtro de exclusão: informe um identificador para o filtro de exclusão.

    • Taxa de filtro de exclusão: forneça um número inteiro entre 0 e 100. Os registros de entrada que correspondem ao filtro de exclusão são amostrados de acordo com esse valor.

      Um valor de 0% de amostras 0 dos registros correspondentes ao filtro, portanto, 0 é equivalente à desativação do filtro de exclusão. Um valor de 100% de amostras 100 de todos os registros. Portanto, todos os registros correspondentes ao filtro de exclusão são excluídos do destino. Um valor de 50 de amostras 50% dos registros que correspondem ao filtro de exclusão. Portanto, 50% dos registros que correspondem à exclusão são excluídos, enquantos o outros 50% são roteados para o destino.

      É possível criar até 50 filtros de exclusão por coletor.

  6. Selecione Criar coletor.

Novas entradas de registro que correspondem ao filtro do seu coletor são roteadas para o destino do coletor. As entradas de registro que registrarão buckets de registro, BigQuery ou Pub/Sub serão transmitidas imediatamente. As entradas de registro para o Cloud Storage são gravadas em lote e enviadas aproximadamente a cada hora. Para informações sobre como visualizar registros nos destinos exportados, acesse Como usar registros exportados.

Depois de criar o coletor, veja o número e o volume das entradas de registro recebidas usando as métricas logging.googleapis.com/exports/.

Se o Logging encontrar erros ao tentar exportar registros para os destinos de exportação, 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 exportar registros para outro projeto do Google Cloud

É possível exportar registros para um destino em um projeto do Cloud diferente daquele em que o coletor é criado.

Para isso, siga um destes procedimentos:

  • Tenha uma das seguintes permissões do IAM no projeto do Cloud para onde os registros serão enviados:

    • Proprietário (roles/owner)
    • Administrador do Logging (roles/logging.admin)
    • Gravador de configuração de registros (roles/logging.configWriter)
  • Atribua à conta de serviço do coletor o papel roles/logging.logWriter para gravar no destino.

Para mais instruções sobre como fornecer as permissões corretas à conta de serviço do coletor, consulte Permissões de destino. Para a lista de papéis e permissões do Logging, consulte Controle de acesso.

Como gerenciar coletores

Depois que o coletor é criado, é possível visualizá-lo na página Roteador de registros, onde é possível executar as seguintes ações:

  • Visualizar os detalhes do coletor
  • Editar o coletor
  • Desativar o coletor
  • Excluir o coletor

Para acessar a página "Roteador de registros" no menu do Logging, selecione Roteador de registros.

Acessar o 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:

  • Tipo: o tipo de destino do coletor.
  • Nome: o identificador do coletor no projeto atual.
  • Descrição: a descrição do coletor.
  • Destino: nome completo para onde irão 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 nome, a descrição, o serviço, o destino e os filtros de inclusão e exclusão do coletor. Ao selecionar Editar, é possível alterar as propriedades do coletor.
  • Editar coletor: abre o 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 os registros de roteamento 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 e gerenciar coletores com a ferramenta de linha de comando gcloud

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

gcloud logging sinks create SINK_NAME SINK_LOCATION OPTIONAL_FLAGS

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

gcloud 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"

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. Você também precisa ativar o faturamento no projeto do Google Cloud do bucket de destino.

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

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

     gcloud 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 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
      

Como interromper o processamento de registros

Quando você desativa o processamento de registros para o bucket _Default desativando o coletor _Default e outros roteamentos de coletor para o bucket _Default, o Cloud Logging interrompe a ingestão e o armazenamento dos dados de registros no bucket _Default. O bucket _Default conterá registros até que as duas situações a seguir sejam atendidas:

  • Nenhum coletor roteie para o bucket _Default.

  • O período de armazenamento no bucket expirou.

Depois de desativar todos os coletores que enviam registros para o bucket _Default, o Cloud Logging não cobrará mais pelo processamento de novos registros no bucket.

Para desativar o processamento de registros, siga estas etapas:

  1. Acesse o roteador de registros.

    Acessar o roteador de registros

  2. Para encontrar todos os coletores que direcionam registros para o bucket _Default, filtre os coletores por destino e insira _Default.

    Encontrar todos os coletores que encaminham registros para o bucket padrão

  3. Para cada coletor, selecione Menu e, em seguida, selecione Desativar coletor.

    O coletor padrão está desativado

Os coletores agora estão desativados e o Cloud Logging não encaminha mais registros para o bucket _Default.

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, acesse a página Roteador de registros e selecione menu > Exibir detalhes do coletor. A identidade do gravador é exibida no painel Detalhes do coletor.
    • Se você estiver usando gcloud logging, as identidades do gravador serão exibidas quando você listar seus coletores.
    • Se estiver usando a API Logging, você poderá conseguir a identidade do gravador do objeto LogSink.
  4. Caso você tenha acesso 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.
    • Para destinos de buckets de registro, adicione a identidade do gravador do coletor ao bucket de registros para conceder a permissão roles/logging.bucketWriter.
  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 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.

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:

    • O filtro está incorreto. Verifique o filtro para confirmar se as entradas de registro correspondentes ao filtro chegaram recentemente ao Logging. corrigir erros de ortografia ou de formatação.

    • 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 legado, 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.
Ou erro: table_invalid_schema.
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. Para mais instruções, consulte Esquema do BigQuery para registros exportados.
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. Você pode atualizar o filtro do coletor para corresponder a menos entradas de registros 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 aceita registros muito distantes no passado ou no futuro. 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