Encaminhar entradas de registro

É possível usar o Cloud Logging para rotear entradas de registro de serviços do Google Cloud , dos seus aplicativos e de outros provedores de nuvem para destinos de armazenamento, análise e exportação de terceiros.

Por padrão, o Cloud Logging encaminha todas as entradas de registro para buckets de registro no projeto, na pasta ou na organização de origem. No entanto, é possível configurar coletores de registros para rotear dados de registro para buckets personalizados, Cloud Storage, BigQuery ou Pub/Sub. Serviços como o Cloud Storage e o Pub/Sub são compatíveis com a exportação de dados de registro para ferramentas de terceiros.

De modo geral, é assim que o Cloud Logging roteia e armazena entradas de registro:

Diagrama que ilustra como o Cloud Logging roteia entradas de registro.
Figura 1. Diagrama que ilustra como o Cloud Logging roteia entradas de registro.

A figura anterior se aplica a buckets de registros que estão em um projeto. Não é possível criar buckets de registros definidos pelo usuário em pastas ou organizações. Além disso, não é possível estender o período de armazenamento de nenhum bucket de registros que esteja em uma pasta ou organização.

Como rotear e exportar entradas de registro

Roteamento é o processo de mover entradas de registro recebidas por um projeto, uma pasta ou uma organização do Google Cloud para um destino. Um destino é um serviço que processa as entradas de registro recebidas e executa uma ação. Por exemplo, é possível encaminhar entradas de registro para um bucket de registros. Esse destino verifica as entradas de registro em busca de informações de erro e as grava no armazenamento.

Exportar é o processo de mover entradas de registro do Google Cloud para um local externo. Por exemplo, é possível rotear entradas de registro para o Pub/Sub e exportá-las para ferramentas de terceiros.

O Cloud Logging usa coletores de registros para rotear entradas de registro para destinos. Por padrão, as entradas de registro são roteadas para um dos dois buckets de registro no Google Cloud projeto, na pasta ou na organização. É possível criar coletores de registros para rotear seus dados de registro para outros destinos. Também é possível modificar um dos coletores de registros criados pelo sistema. Este documento descreve essas opções.

A Análise de Registros permite baixar entradas de registro armazenadas em buckets de registro para o armazenamento local. No entanto, a opção de download é limitada a 10.000 entradas de registro. Para exportar as entradas de registro do Google Cloud, considere estas opções:

  • Configure um coletor de registros para rotear as entradas de registro recebidas para o Pub/Sub e exporte esses dados do Google Cloud.

  • Copie as entradas de registro de um bucket de registros para o Cloud Storage e exporte os dados do Google Cloud. Para saber como copiar registros, consulte Agrupar e rotear registros retroativamente.

Sobre os roteadores de registros

Cada projeto, conta de faturamento, pasta e organização do Google Cloud tem um roteador de registros, que gerencia o fluxo de entradas de registro por meio de coletores no nível do recurso. Um roteador de registros também gerencia o fluxo de uma entrada de registro por meio de coletores que estão na hierarquia de recursos da entrada. Os coletores controlam como as entradas de registro são roteadas para os destinos.

Um roteador de registros armazena uma entrada de registro temporariamente. Esse comportamento protege contra interrupções temporárias e falhas que podem ocorrer quando uma entrada de registro flui pelos coletores. O armazenamento temporário não protege contra erros de configuração.

O armazenamento temporário de um roteador de registros é diferente do armazenamento de longo prazo fornecido pelos buckets do Logging.

As entradas de registro recebidas com carimbos de data/hora que excedem o período de armazenamento de registros no passado ou que excedem 24 horas no futuro são descartadas.

Sobre coletores de registros

Quando um coletor de registros recebe uma entrada de registro, ele determina se deve ignorar ou rotear a entrada para o destino do coletor. O coletor de registros compara a entrada de registro com os filtros para tomar essa decisão. O destino de um coletor pode ser um projeto, um local de armazenamento ou um serviço como o Pub/Sub. Por exemplo, um coletor pode rotear entradas de registro para um bucket de registros.

Os coletores de registros pertencem a um determinado recurso do Google Cloud : Google Cloud projetos, contas de faturamento, pastas e organizações. Esses recursos também contêm vários coletores de registros. Quando um recurso recebe uma entrada de registro, cada coletor de registros nesse recurso a avalia de forma independente. Como resultado, vários coletores de registros podem rotear a mesma entrada de registro.

Por padrão, os dados de registro são armazenados no projeto em que os dados se originam. No entanto, há vários motivos para mudar essa configuração:

  • Centralizar o armazenamento dos dados de registro.
  • Para mesclar seus dados de registro com dados da empresa.
  • Para organizar os dados de registro de uma forma que seja útil para você.
  • Para transmitir os registros para outros aplicativos, outros repositórios ou terceiros. Por exemplo, talvez você queira exportar os registros do Google Cloud para visualizá-los em uma plataforma de terceiros. Para exportar as entradas de registro, crie um coletor de registros que as encaminhe para o Pub/Sub.

Um coletor de registros configurado incorretamente não encaminha entradas de registro. Quando um coletor é configurado incorretamente, as entradas de registro que informam os detalhes do erro são gravadas. Além disso, um e-mail é enviado aos Contatos Essenciais do recurso. Para mais informações, consulte Resolver problemas: ver erros.

Os coletores de registros não podem encaminhar entradas de registro retroativamente. Ou seja, um coletor de registros não pode encaminhar uma entrada de registro recebida antes da criação do coletor. Da mesma forma, se um coletor estiver configurado incorretamente, ele só vai rotear as entradas de registro que chegarem depois que o erro de configuração for resolvido. No entanto, é possível copiar retroativamente os dados de registro de um bucket de registros para o Cloud Storage. Para mais informações, consulte Copiar registros.

Suporte para organizações e pastas

Para ajudar a gerenciar os dados de registro em uma organização ou pasta, faça o seguinte:

  • É possível criar coletores agregados, que encaminham entradas de registro de uma organização ou pasta e os filhos delas para o destino especificado pelo coletor. Há dois tipos de coletores agregados:

    • Coletores agregados sem interceptação
    • Como interceptar coletores agregados

    Os coletores de interceptação podem substituir o comportamento de roteamento de recursos mais baixos na hierarquia. Os coletores que não interceptam não afetam o roteamento de outros recursos. Quando um coletor de interceptação em um recurso corresponde a uma entrada de registro, ela não é enviada aos coletores em recursos filhos, exceto se a entrada de registro for sempre enviada ao coletor de registros _Required no recurso em que a entrada de registro se origina.

  • É possível definir as configurações de recursos padrão do Cloud Logging para especificar a configuração do coletor _Default criado pelo sistema para novos recursos em uma organização ou pasta. Por exemplo, é possível usar essas configurações para desativar o coletor _Default ou especificar os filtros nele.

Exemplos de roteamento

Nesta seção, mostramos como uma entrada de registro que se origina em um projeto pode fluir pelos coletores na hierarquia de recursos.

Exemplo: não há coletores agregados

Quando não há coletores agregados na hierarquia de recursos da entrada de registro, ela é enviada para os coletores de registros no projeto em que a entrada de registro é originada. Um coletor no nível do projeto encaminha a entrada de registro para o destino do coletor quando ela corresponde ao filtro de inclusão do coletor, mas não corresponde a nenhum dos filtros de exclusão do coletor.

Exemplo: existe um coletor agregado sem interceptação

Suponha que exista um coletor agregado não interceptador na hierarquia de recursos para uma entrada de registro. Depois que o roteador de registros envia a entrada de registro para o coletor agregado sem interceptação, ocorre o seguinte:

  1. O coletor agregado sem interceptação encaminha a entrada de registro para o destino do coletor quando ela corresponde ao filtro de inclusão, mas não corresponde a nenhum filtro de exclusão.

  2. O roteador de registros envia a entrada de registro para os coletores de registros no projeto em que a entrada de registro foi originada.

    Um coletor no nível do projeto encaminha a entrada de registro para o destino do coletor quando ela corresponde ao filtro de inclusão do coletor, mas não corresponde a nenhum dos filtros de exclusão do coletor.

Exemplo: há um coletor agregado de interceptação

Suponha que exista um coletor agregado de interceptação na hierarquia de recursos para uma entrada de registro. Depois que o roteador de registros envia a entrada de registro para o coletor agregado de interceptação, ocorre uma das seguintes situações:

  • A entrada de registro corresponde ao filtro de inclusão, mas não corresponde a nenhum filtro de exclusão:

    1. A entrada de registro é roteada para o destino do coletor agregado de interceptação.
    2. A entrada de registro é enviada para o coletor _Required no projeto em que a entrada de registro foi originada.

  • A entrada de registro não corresponde ao filtro de inclusão ou corresponde a pelo menos um filtro de exclusão:

    1. A entrada de registro não é roteada pelo coletor agregado de interceptação.

    2. O roteador de registros envia a entrada de registro para os coletores de registros no projeto em que a entrada de registro foi originada.

      Um coletor no nível do projeto encaminha a entrada de registro para o destino do coletor quando ela corresponde ao filtro de inclusão do coletor, mas não corresponde a nenhum dos filtros de exclusão do coletor.

Filtros de coletor de registros

Cada coletor de registros contém um filtro de inclusão e pode conter vários filtros de exclusão. Esses filtros determinam se o coletor de registros encaminha uma entrada de registro para o destino do coletor. Se você não especificar nenhum filtro, todas as entrada de registro serão roteadas para o destino do coletor.

Uma entrada de registro é roteada por um coletor de registros com base nestas regras:

  • Se a entrada de registro não corresponder ao filtro de inclusão, ela não será roteada. Quando um coletor não especifica um filtro de inclusão, todas as entrada de registro correspondem a esse filtro.

  • Se a entrada de registro corresponder ao filtro de inclusão e a pelo menos um filtro de exclusão, ela não será roteada.

  • Se a entrada de registro corresponder ao filtro de inclusão e não corresponder a nenhum filtro de exclusão, ela será roteada para o destino do coletor.

Os filtros em um coletor de registros são especificados usando a linguagem de consulta do Logging.

Não é possível usar filtros de exclusão para reduzir o consumo da cota da API entries.write ou o número de chamadas de API entries.write. Os filtros de exclusão são aplicados depois que as entradas de registro são recebidas pela API Logging ou pela API Telemetry.

Coletores de registros criados pelo sistema

Para cada projeto, conta de faturamento, pasta e organização do Google Cloud , o Cloud Logging cria dois coletores de registros, um chamado _Required e o outro chamado _Default. Os filtros de inclusão e exclusão desses coletores garantem que cada entrada de registro originada no recurso seja roteada por um desses coletores. Os dois coletores encaminham dados de registro para um bucket de registros que está no mesmo recurso que o coletor de registros.

O restante desta seção fornece informações sobre os filtros e destinos dos coletores de registros criados pelo sistema.

Coletor de registros _Required

O coletor de registros _Required em um recurso encaminha um subconjunto de registros de auditoria para o bucket de registros _Required do recurso. Esse coletor não especifica filtros de exclusão, e o filtro de inclusão é mostrado abaixo:

LOG_ID("cloudaudit.googleapis.com/activity") OR
LOG_ID("externalaudit.googleapis.com/activity") OR
LOG_ID("cloudaudit.googleapis.com/system_event") OR
LOG_ID("externalaudit.googleapis.com/system_event") OR
LOG_ID("cloudaudit.googleapis.com/access_transparency") OR
LOG_ID("externalaudit.googleapis.com/access_transparency")

O coletor de registros _Required só corresponde às entradas de registro que se originam no recurso em que o coletor de registros _Required está definido. Por exemplo, suponha que um coletor de registros encaminhe uma entrada de registro de atividade do projeto A para o projeto B. Como a entrada de registro não se originou no projeto B, o coletor de registros _Required no projeto B não encaminha essa entrada para o bucket de registros _Required.

Não é possível modificar ou excluir o coletor de registros _Required.

Coletor de registros _Default

O coletor de registros _Default em um recurso encaminha as entradas de registro para o bucket de registros _Default do recurso. Como o filtro de inclusão desse coletor está vazio, ele corresponde a todas as entradas de registro. No entanto, o filtro de exclusão é configurado da seguinte maneira:

NOT LOG_ID("cloudaudit.googleapis.com/activity") AND
NOT LOG_ID("externalaudit.googleapis.com/activity") AND
NOT LOG_ID("cloudaudit.googleapis.com/system_event") AND
NOT LOG_ID("externalaudit.googleapis.com/system_event") AND
NOT LOG_ID("cloudaudit.googleapis.com/access_transparency") AND
NOT LOG_ID("externalaudit.googleapis.com/access_transparency")

É possível modificar e desativar o coletor de registros _Default. Por exemplo, é possível editar o coletor de registros _Default e alterar o destino. Também é possível modificar qualquer filtro atual e adicionar filtros de exclusão.

Destinos do coletor

O destino de um coletor pode estar em um recurso diferente do coletor. Por exemplo, é possível usar um coletor de registros para rotear entradas de registro de um projeto para um bucket de registros armazenado em um projeto diferente.

Os seguintes destinos são compatíveis:

Projeto doGoogle Cloud

Selecione esse destino quando quiser que os coletores de registros no projeto de destino redirecionem as entradas de registro ou quando tiver criado um coletor agregado de interceptação. Os coletores de registros no projeto de destino podem redirecionar as entradas de registro para qualquer destino compatível, exceto um projeto.

Os coletores de registros criados pelo sistema no projeto de destino excluem as entradas de registro roteadas para o bucket de registros _Required no projeto de origem. Por exemplo, se você rotear registros de atividade do administrador para outro projeto, os coletores de registros _Required e _Default no projeto de destino vão excluir essas entradas de registro. Para armazenar essas entradas de registro, no projeto de destino, atualize o coletor de registros _Default ou crie um coletor de registros personalizado.

Bucket de registros

Selecione esse destino quando quiser armazenar os dados de registro em recursos gerenciados pelo Cloud Logging. Os dados de registro armazenados em buckets de registro podem ser visualizados e analisados usando serviços como a Análise de registros e a Análise de observabilidade.

Se você quiser mesclar os dados de registro com outros dados da empresa, armazene-os em um bucket de registros e crie um conjunto de dados vinculado do BigQuery. Um conjunto de dados vinculado do BigQuery é somente leitura, mas pode ser consultado como qualquer outro conjunto de dados do BigQuery.

Conjunto de dados do BigQuery
Selecione esse destino quando quiser mesclar os dados de registro com outros dados da empresa. O conjunto de dados especificado precisa ter a gravação ativada. Não defina o destino de um coletor como um conjunto de dados vinculado do BigQuery. Os conjuntos de dados vinculados do BigQuery são somente leitura.
Bucket do Cloud Storage, exceto para o Rapid Storage
Selecione esse destino quando quiser armazenar os dados de registro por um longo período. O bucket do Cloud Storage pode estar no projeto de origem das entradas de registro ou em um projeto diferente. As entradas de registro são armazenadas na forma de arquivos JSON.
Tópico do Pub/Sub
Selecione esse destino quando quiser exportar os dados de registro do Google Cloud e usar integrações de terceiros, como Splunk ou Datadog. As entradas de registro são formatadas como JSON e roteadas para um tópico do Pub/Sub.

Limitações de destino

Nesta seção, descrevemos as limitações específicas do destino:

  • Ao configurar um destino de coletor, forneça o caminho totalmente qualificado e use o endpoint global do serviço. Os endpoints de serviço regionais (REPs, na sigla em inglês), como pubsub.LOCATION.rep.googleapis.com, não são compatíveis.
  • Se você rotear entradas de registro para um bucket de registros em um projeto do Google Cloud diferente, o Error Reporting não vai analisar essas entradas. Para mais informações, consulte Visão geral do Error Reporting.

  • As seguintes limitações se aplicam quando o destino de um coletor de registros é um conjunto de dados do BigQuery:

    • O conjunto de dados do BigQuery precisa estar ativado para gravação. Não defina o destino como um conjunto de dados vinculado do BigQuery. Os conjuntos de dados vinculados são somente leitura.
    • O Logging cria uma tabela dentro do conjunto de dados para cada nome de registro. Não é possível renomear uma tabela enquanto um coletor está transmitindo dados para ela.

  • Não é possível rotear entradas de registro para buckets do Cloud Storage configurados para o Rapid Storage.

  • Novos coletores que roteiam entradas de registro para buckets do Cloud Storage podem levar várias horas para começar a rotear entradas de registro. Esses coletores são processados de hora em hora.

  • Não é possível rotear registros para um tópico do Pub/Sub que aplica restrições em trânsito. O Logging não pode garantir que as solicitações de publicação sejam originadas de uma região permitida, o que causa erros de configuração do topic_region_not_allowed e registros descartados.

  • As limitações a seguir se aplicam quando o destino de um coletor de registros é um projeto do Google Cloud :

    • Há um limite de um salto.
    • O coletor de registros _Required no projeto de destino encaminha as entradas de registro para o bucket de registros _Required do projeto quando as entradas de registro correspondem ao filtro do coletor e são originadas no projeto de destino.
    • O coletor de registros _Default no projeto de destino roteia as entradas de registro que correspondem ao filtro de inclusão e não correspondem a nenhum filtro de exclusão. O coletor de registros _Default exclui algumas entradas de registro. Por exemplo, esse coletor não encaminha entradas de registro de atividades do administrador e de eventos do sistema. É possível modificar esse coletor.
    • Somente os coletores agregados que estão na hierarquia de recursos de uma entrada de registro processam a entrada.

    Por exemplo, suponha que o destino de um coletor de registros no projeto A seja o projeto B. Nesse caso, as seguintes regras se aplicam:

    • Devido ao limite de um salto, os coletores de registros no projeto B não podem redirecionar entradas de registro para outro projeto do Google Cloud .
    • O bucket de registros _Required do projeto B armazena apenas entradas de registro que se originam no projeto B. Esse bucket de registros não armazena entradas de registro originadas em nenhum outro recurso, incluindo aquelas originadas no projeto A.
    • Se o projeto A e o projeto B tiverem hierarquias de recursos diferentes, uma entrada de registro que um coletor de registros no projeto A encaminha para o projeto B não será enviada para os coletores agregados na hierarquia de recursos do projeto B.
    • Se o projeto A e o projeto B tiverem a mesma hierarquia de recursos, as entradas de registro serão enviadas para os coletores agregados nessa hierarquia. Se uma entrada de registro não for interceptada por um coletor agregado, o roteador de registros vai enviar a entrada para os coletores no projeto A.

Como o roteamento de entradas de registro afeta as métricas com base em registros

As métricas com base em registros são métricas do Cloud Monitoring derivadas do conteúdo das entradas de registro. Por exemplo, é possível usar uma métrica com base em registros para contar o número de entradas de registro que contêm uma mensagem específica ou para extrair informações de latência registradas em entradas de registro. É possível exibir métricas com base em registros em gráficos do Cloud Monitoring, e as políticas de alertas podem monitorar essas métricas.

As métricas com base em registros definidas pelo sistema são aplicadas a projetos. As métricas com base em registros definidas pelo usuário podem ser aplicadas no nível do projeto ou do bucket de registros. As métricas com base em registros com escopo de bucket são úteis quando você usa coletores agregados para rotear entradas de registro para um bucket de registros e quando você roteia entradas de registro de um projeto para um bucket de registros em outro projeto.

Métricas com base em registros definidas pelo sistema
O roteador de registros conta uma entrada de registro quando todas as seguintes condições são verdadeiras:
  • A entrada de registro passa pelos coletores de registros do projeto em que a métrica com base em registros está definida.

  • A entrada de registro é armazenada em um bucket de registros. O bucket de registros pode estar em qualquer projeto.

    Por exemplo, suponha que o projeto A tenha um coletor de registros com o projeto B como destino. Suponha também que os coletores de registros no projeto B encaminhem as entradas de registro para um bucket de registros. Nesse cenário, as entradas de registro roteadas do projeto A para o projeto B contribuem para as métricas com base em registros definidas pelo sistema do projeto A. Essas entradas de registro também contribuem para as métricas com base em registros definidas pelo sistema do projeto B.

Métricas com base em registros definidas pelo usuário
O roteador de registros conta uma entrada de registro quando todas as seguintes condições são verdadeiras:
  • O faturamento está ativado no projeto em que a métrica com base em registros está definida.
  • Para métricas com escopo de bucket, a entrada de registro é armazenada no bucket de registros em que a métrica com base em registros é definida.
  • Para métricas com escopo de projeto, a entrada de registro passa pelos coletores de registros do projeto em que a métrica com base em registros é definida.

Para mais informações, consulte Visão geral das métricas com base em registros.

Práticas recomendadas

Gerencie os coletores de registros ao gerenciar o armazenamento de registros. Por exemplo, se você excluir o destino de um coletor de registros, exclua o coletor correspondente.

Para práticas recomendadas sobre o uso de roteamento para governança de dados ou para casos de uso comuns, consulte os seguintes documentos:

Exemplos: centralizar o armazenamento de registros

Nesta seção, descrevemos como configurar o armazenamento centralizado. O armazenamento centralizado oferece um único lugar para consultar dados de registro, o que simplifica as consultas quando você está procurando tendências ou investigando problemas. Do ponto de vista da segurança, você também tem um local de armazenamento, o que pode simplificar as tarefas dos analistas de segurança.

Se você centralizar o armazenamento de registros, considere colocar uma garantia no projeto que armazena os dados de registro. Uma garantia pode evitar a exclusão acidental de um projeto. Para saber mais, consulte Proteger projetos usando garantias.

Centralizar a geração de registros centralizada para projetos em uma pasta

Suponha que você gerencie uma pasta e queira centralizar o armazenamento das entradas de registro. Para esse caso de uso, faça o seguinte:

  1. Na pasta, crie um projeto chamado CentralStorage.
  2. Crie um coletor agregado de interceptação para sua pasta e configure-o para rotear todas as entradas de registro. Defina o destino do coletor como o projeto chamado CentralStorage.

Quando uma entrada de registro originada na pasta ou em um dos recursos filhos dela chega, ela é enviada ao coletor agregado de interceptação que você criou. Esse coletor encaminha entradas de registro para o projeto chamado CentralStorage. Os coletores de registros neste projeto processam as entradas de registro:

  • O coletor de registros _Default encaminha para o bucket de registros _Default todas as entradas de registro que correspondem ao filtro do coletor. Esse bucket de registros é seu local de armazenamento centralizado.

  • O coletor de registros _Required encaminha para o bucket de registros _Required as entradas de registro que correspondem aos filtros do coletor e que se originam no projeto CentralStorage. Esse bucket de registros não é um local de armazenamento centralizado. No entanto, é possível armazenar de forma centralizada todos os dados de registro. Para ver um exemplo, consulte Armazenar registros de auditoria em um local central.

Depois que o processamento do coletor agregado é concluído, a entrada de registro é enviada para o coletor de registros _Required no recurso em que a entrada de registro foi originada. Quando a entrada de registro corresponde ao filtro no coletor de registros _Required, ela é roteada para o bucket de registros _Required do recurso. Consequentemente, cada projeto do Google Cloud na pasta armazena entradas de registro no bucket de registros _Required.

Centralizar o armazenamento de registros para um conjunto de projetos

Também é possível armazenar entradas de registro em um único local quando você não tem uma organização ou uma pasta. Por exemplo, você pode fazer o seguinte:

  1. Crie um projeto chamado CentralStorage.
  2. Para cada projeto, exceto CentralStorage, edite o coletor de registros _Default e defina o destino como o projeto chamado CentralStorage.

Talvez você esteja se perguntando por que o exemplo anterior define o destino dos coletores de registros _Default como um projeto, em vez do bucket de registros _Default nesse projeto. Os principais motivos são simplicidade e consistência. Quando você encaminha entradas de registro para um projeto, os coletores de registros no projeto de destino controlam quais entradas de registro são armazenadas e onde elas são armazenadas. Ou seja, você centraliza a funcionalidade de filtro e destino. Se você quiser alterar quais entradas de registro são armazenadas ou onde elas são armazenadas, basta modificar os coletores de registros em um projeto.

Centralizar a geração de registros centralizada para registros de auditoria

É possível armazenar de forma centralizada as entradas de registro que correspondem ao coletor de registros do _Required. Para armazenar essas entradas de registro de maneira centralizada, siga um destes procedimentos:

  • Crie coletores de registros que encaminhem entradas de registro que correspondam ao coletor de registros _Required para um bucket de registros centralizado.

  • Configure os coletores de registros como nos dois exemplos anteriores e adicione um coletor de registros no projeto de destino que encaminhe as entradas de registro que correspondem ao coletor de registros _Required para um bucket de registros. Também é possível editar os filtros no coletor de registros _Default.

Antes de implementar essa estratégia, consulte as diretrizes de preços.

Preços

Para saber mais sobre os preços do Cloud Logging, consulte a página de preços do Google Cloud Observability.

A seguir

Para ajudar você a rotear e armazenar dados do Cloud Logging, consulte os seguintes documentos: