Agrupar e rotear registros no nível da organização para destinos compatíveis

Neste documento, você verá como criar coletores agregados. Para informações sobre como gerenciar coletores atuais, consulte Rotear registros para destinos compatíveis: gerenciar coletores.

Visão geral

Os coletores agregados combinam e roteiam entradas de registro dos recursos do Google Cloud contidos por uma organização ou pasta. Por exemplo, é possível agregar e rotear entradas de registro de auditoria de todas as pastas contidas por uma organização para um bucket do Cloud Storage.

Sem o recurso de coletor agregado, os coletores são limitados ao encaminhamento de entradas de registro do recurso exato em que o coletor foi criado: um projeto, uma organização, uma pasta ou uma conta de faturamento do Google Cloud.

É possível criar coletores agregados para pastas e organizações do Google Cloud. Como os projetos e as contas de faturamento do Google Cloud não contêm recursos filhos, não é possível criar coletores agregados para eles.

Destinos possíveis

Você pode usar coletores agregados para rotear registros dentro ou entre as mesmas organizações e pastas para os seguintes destinos:

  • Buckets de registros do Cloud Logging: fornece armazenamento no Cloud Logging. Um bucket de registros pode armazenar registros recebidos por vários projetos do Google Cloud. É possível combinar os dados do Cloud Logging com outros dados fazendo upgrade de um bucket de registros para usar a Análise de dados de registros e, em seguida, criando um conjunto de dados do BigQuery vinculado. Para informações sobre como visualizar registros armazenados em buckets de registros, consulte Visão geral de consulta e visualização de registros e Visualizar registros roteados para buckets do Cloud Logging.
  • Projetos do Google Cloud: roteie entradas de registro para outro projeto do Google Cloud. Quando você encaminha registros para um projeto diferente do Google Cloud, o roteador de registros do projeto de destino recebe e processa os registros. Os coletores no projeto de destino determinam como as entradas de registro recebidas são roteadas. As entradas de registro que são roteadas para um projeto diferente do Google Cloud por buckets de registros não podem ser analisadas pelo Error Reporting.
  • Tópicos do Pub/Sub: fornece suporte para integrações de terceiros, como Splunk. As entradas de registro são formatadas em JSON e roteadas para um tópico do Pub/Sub. Para informações sobre como visualizar registros roteados para o Pub/Sub, consulte Visualizar registros roteados para o Pub/Sub.
  • Conjuntos de dados do BigQuery: fornece armazenamento de entradas de registro nos conjuntos de dados do BigQuery. Você pode usar recursos de análise de Big Data nos registros armazenados. Para combinar os dados do Cloud Logging com outras fontes de dados, recomendamos fazer upgrade dos buckets de registros para usar a Análise de dados de registros e, em seguida, criar um conjunto de dados vinculado do BigQuery. Para mais informações sobre como visualizar registros roteados para o BigQuery, consulte Visualizar registros roteados para o BigQuery.
  • Buckets do Cloud Storage: armazenam dados de registro no Cloud Storage. As entradas de registro são armazenadas como arquivos JSON. Para mais informações sobre como visualizar registros roteados para o Cloud Storage, consulte Visualizar registros roteados para o Cloud Storage.

Coletores agregados e VPC Service Controls

As limitações a seguir se aplicam quando você usa coletores agregados e VPC Service Controls:

  • Os coletores agregados podem acessar dados de projetos dentro de um perímetro de serviço. Para impedir que os coletores agregados acessem dados dentro de um perímetro, recomendamos o uso do IAM para gerenciar as permissões do Logging.

  • O VPC Service Controls não oferece suporte à adição de recursos de pasta ou organização a perímetros de serviço. Portanto, não é possível usar o VPC Service Controls para proteger registros em nível de pasta e organização, incluindo registros agregados. Para gerenciar as permissões do Logging no nível da pasta ou da organização, recomendamos o uso do IAM.

  • Se você rotear registros usando um coletor no nível da pasta ou da organização para um recurso protegido por um perímetro de serviço, adicione uma regra de entrada ao perímetro de serviço. A regra de entrada precisa permitir o acesso ao recurso pela conta de serviço que o coletor agregado usa. Para mais informações, consulte as páginas a seguir:

  • Ao especificar uma política de entrada ou saída para um perímetro de serviço, não é possível usar ANY_SERVICE_ACCOUNT e ANY_USER_ACCOUNT como um tipo de identidade ao usar um coletor de registros para rotear registros para recursos do Cloud Storage. No entanto, você pode usar ANY_IDENTITY como o tipo de identidade.

Antes de começar

Antes de criar um coletor, verifique se:

  • Você tem uma pasta ou organização do Google Cloud com registros que podem ver no Explorador de registros.

  • Você tem um dos seguintes papéis do IAM para a organização ou pasta do Google Cloud a partir da qual está roteando registros.

    • Proprietário (roles/owner)
    • Administrador do Logging (roles/logging.admin)
    • Gravador de configuração de registros (roles/logging.configWriter)

    As permissões contidas nesses papéis permitem criar, excluir ou modificar coletores. Para informações sobre como definir papéis do IAM, consulte o Guia de controle de acesso do Logging.

  • Você tem um recurso em um destino compatível ou pode criar um.

    O destino de roteamento precisa ser criado antes do coletor por meio da Google Cloud CLI, do console do Google Cloud ou das APIs do Google Cloud. É possível criar o destino em qualquer projeto do Google Cloud em qualquer organização, mas você precisa garantir que a conta de serviço do coletor tenha permissões para gravar no destino.

Criar um coletor agregado

Para usar coletores agregados, crie um coletor em uma organização ou pasta do Google Cloud e defina o parâmetro includeChildren do coletor como True. Quando você define o parâmetro includeChildren, o coletor pode rotear entradas de registro da organização ou pasta e de maneira recursiva de qualquer pasta, conta de faturamento ou projeto do Google Cloud.

Para especificar as entradas de registro que você quer rotear para o destino, defina os filtros de inclusão e exclusão do coletor.

É possível criar até 200 coletores por pasta ou organização.

Para criar um coletor agregado para sua pasta ou organização, faça o seguinte:

Console

  1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

    Acessar o roteador de registros

  2. Selecione uma pasta ou organização existente.

  3. Selecione Criar coletor.

  4. No painel Detalhes do coletor, insira os seguintes detalhes:

    • Nome do coletor: forneça um identificador para o coletor. Depois de criar o coletor, não será possível renomeá-lo, mas será possível excluí-lo e criar um novo coletor.

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

  5. No painel Destino do coletor, selecione o serviço de coletor e o destino:

    • Selecionar serviço de coletor: selecione o serviço em que você quer os registros roteados.

    Com base no serviço selecionado, é possível selecionar os seguintes destinos:

    • Bucket do Cloud Logging: selecione ou crie um bucket do Logging. Se você criar um bucket de registros, ele precisará estar no nível do projeto. Não é possível criar um bucket de registros no nível da pasta ou da organização.
    • Tabela do BigQuery: selecione ou crie o conjunto de dados específico para receber os registros roteados. Você também tem a opção de usar tabelas particionadas.
    • Bucket do Cloud Storage: selecione ou crie o bucket específico do Cloud Storage para receber os registros roteados.
    • Tópico do Pub/Sub: selecione ou crie o tópico específico para receber os registros roteados.
    • Splunk: selecione o tópico do Pub/Sub do serviço Splunk.

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

      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID
      
  6. No painel Escolher registros a serem incluídos no coletor, faça o seguinte:

    1. Selecione Incluir registros ingeridos por este recurso e todos os recursos filhos, que cria um coletor agregado.

    2. No campo Criar inclusão de filtro, insira uma expressão de filtro que corresponda às entradas de registro que você quer incluir. Se você não definir um filtro, todos os registros do recurso selecionado serão roteados para o destino.

      Por exemplo, é possível criar um filtro para rotear todos os registros de auditoria de acesso a dados para um único bucket do Logging. Esse filtro tem a seguinte aparência:

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

      O comprimento de um filtro não pode exceder 20.000 caracteres.

    3. 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.

  7. (Opcional) No painel Escolher registros a serem excluídos do coletor, faça o seguinte:

    1. No campo Nome do filtro de exclusão, insira um nome.

    2. No campo Criar um filtro de exclusão, insira uma expressão de filtro que corresponda às entradas de registro que você quer excluir. Também é possível usar a função sample para selecionar uma parte das entradas de registro a serem excluídas.

      Por exemplo, para impedir que os registros de um projeto específico sejam roteados para o destino, adicione o seguinte filtro de exclusão:

      logName:projects/PROJECT_ID
      

      Para excluir registros de vários projetos, use o operador lógico OR para unir cláusulas logName.

    É possível criar até 50 filtros de exclusão por coletor. O comprimento de um filtro não pode exceder 20.000 caracteres.

  8. Selecione Criar coletor.

API

Para criar um coletor, use organizations.sinks.create ou folders.sinks.create na API Logging. Prepare os argumentos do método da seguinte maneira:

  1. Defina o parâmetro parent como a organização ou pasta do Google Cloud em que o coletor será criado. O pai precisa ser um dos seguintes parâmetros:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID
  2. No objeto LogSink no corpo da solicitação do método, faça o seguinte:

  3. Chame organizations.sinks.create ou folders.sinks.create para criar o coletor.

  4. Recupere o nome da conta de serviço no campo writer_identity retornado da resposta da API.

  5. Conceda a essa conta de serviço permissão para gravar no destino do coletor.

    Se você não tiver permissão para fazer essa alteração no destino do coletor, envie o nome da conta de serviço para alguém que possa fazer essa alteração.

    Para mais informações sobre a concessão de permissões de contas de serviço para recursos, consulte a seção definir permissões de destino.

gcloud

Para criar um coletor, use o comando logging sinks create.

  1. Forneça o nome do coletor, o destino do coletor, o filtro e o ID da pasta ou organização de onde você está roteando os registros:

    gcloud logging sinks create SINK_NAME \
      SINK_DESTINATION  --include-children \
      --folder=FOLDER_ID --log-filter="LOG_FILTER"
    

    Por exemplo, se você estiver criando um coletor agregado no nível da pasta e cujo destino for um conjunto de dados do BigQuery, o comando poderá ter a seguinte aparência:

    gcloud logging sinks create SINK_NAME \
      bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID --include-children \
      --folder=FOLDER_ID --log-filter="logName:activity"
    

    Observações:

    • Para criar um coletor no nível da organização, substitua --folder=FOLDER_ID por --organization=ORGANIZATION_ID.

    • Para que o coletor inclua todos os recursos da organização, a sinalização --include-children precisa ser definida, mesmo quando a sinalização --organization for passada para create. Quando for definido como false (padrão), um coletor encaminhará apenas registros do recurso host.

    • Para alguns exemplos de filtros úteis, consulte Criar filtros para coletores agregados.

  2. Recupere o nome da conta de serviço usado para criar o coletor com base na saída do comando.

  3. Conceda a essa conta de serviço permissão para gravar no destino do coletor.

    Se você não tiver permissão para fazer essa alteração no destino do coletor, envie o nome da conta de serviço para alguém que possa fazer essa alteração.

    Para mais informações sobre a concessão de permissões de contas de serviço para recursos, consulte a seção definir permissões de destino.

As alterações feitas em um coletor podem levar alguns minutos para serem aplicadas.

Criar filtros para coletores agregados

Como qualquer outro, o coletor agregado contém um filtro que seleciona entradas de registro individuais. Para exemplos de filtros que você pode usar para criar um coletor agregado, consulte Consultas de amostra usando o Explorador de registros.

Veja a seguir alguns exemplos de comparações de filtros que são úteis ao usar o recurso de coletores agregados. Alguns exemplos utilizam a seguinte notação:

  • :: é o operador de substring. Não substitua o operador =.
  • ... representa qualquer comparação de filtros adicional.
  • As variáveis são indicadas por texto colorido. As substitua por valores válidos.

O comprimento de um filtro não pode exceder 20.000 caracteres.

Para mais detalhes sobre a sintaxe da filtragem, consulte Linguagem de consulta do Logging.

Selecionar a origem do registro

Para um coletor agregado, para cada recurso filho da organização ou pasta, os filtros de inclusão e exclusão do coletor são aplicados a cada entrada de registro enviada ao recurso filho. Uma entrada de registro que corresponda ao filtro de inclusão e que não seja excluída será roteada.

Se você quiser que o coletor encaminhe registros de todos os recursos filhos, não especifique um projeto, uma pasta ou uma organização nos filtros de inclusão e exclusão do coletor. Por exemplo, suponha que você configure um coletor agregado para uma organização com o seguinte filtro:

resource.type="gce_instance"

Com o filtro anterior, os registros com um tipo de recurso de instâncias do Compute Engine gravados em qualquer filho dessa organização são roteados pelo coletor agregado para o destino.

No entanto, pode haver situações em que você queira usar um coletor agregado para rotear registros apenas de recursos filhos específicos. Por exemplo, para fins de conformidade, convém armazenar registros de auditoria de pastas ou projetos específicos no próprio bucket do Cloud Storage. Nessas situações, configure o filtro de inclusão para especificar cada recurso filho com registros que você quer rotear. Se você quiser rotear os registros de uma pasta e todos os projetos dentro dela, o filtro precisará listar a pasta e cada um dos projetos contidos nessa pasta, além de mesclar as instruções com uma cláusula OR.

Os filtros a seguir restringem os registros a projetos, pastas ou organizações específicos do Google Cloud:

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ... 

Por exemplo, para rotear apenas registros gravados nas instâncias do Compute Engine que foram gravados na pasta my-folder, use o seguinte filtro:

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

Com o filtro anterior, os registros gravados em qualquer recurso diferente de my-folder, incluindo os registros gravados em projetos do Google Cloud filhos de my-folder, não são roteados para o destino.

Selecione o recurso monitorado.

Para rotear registros apenas de um recurso monitorado específico em um projeto do Google Cloud, use várias comparações para especificar o recurso exatamente:

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

Para uma lista de tipos de recursos, consulte Tipos de recursos monitorados.

Selecione uma amostra de entradas de registro

Para encaminhar uma amostra aleatória de entradas de registro, adicione a função incorporada sample. Por exemplo, para rotear somente 10% das entradas de registro correspondentes ao seu filtro atual, use esta adição:

sample(insertId, 0.10) AND ...

Para mais informações, consulte a função sample.

Para mais informações sobre os filtros do Cloud Logging, consulte Linguagem de consulta do Logging.

Definir permissões de destino

Nesta seção, descrevemos como conceder permissões de gerenciamento de identidade e acesso ao Logging para gravar registros no destino do coletor. Para a lista de papéis e permissões do Logging, consulte Controle de acesso.

Quando você cria ou atualiza um coletor que roteia registros para qualquer destino que não seja um bucket de registros no projeto atual, é necessária uma conta de serviço para esse coletor. O Logging cria e gerencia automaticamente a conta de serviço para você:

  • Desde 22 de maio de 2023, quando você cria um coletor e não há uma conta de serviço para o recurso subjacente, o Logging a cria. O Logging usa a mesma conta de serviço para todos os coletores no recurso subjacente. Os recursos podem ser um projeto do Google Cloud, uma organização, uma pasta ou uma conta de faturamento.
  • Antes de 22 de maio de 2023, o Logging criava uma conta de serviço para cada coletor. Desde 22 de maio de 2023, o Logging usa uma conta de serviço compartilhada para todos os coletores no recurso subjacente.

A identidade do gravador de um coletor é o identificador da conta de serviço associada a ele. Todos os coletores têm uma identidade de gravador, a menos que gravem em um bucket de registros no projeto atual do Google Cloud.

Para rotear registros para um recurso protegido por um perímetro de serviço, é necessário adicionar a conta de serviço desse coletor a um nível de acesso e, em seguida, atribuí-la ao perímetro de serviço de destino de dados. Isso não é necessário para coletores não agregados. Para detalhes, consulte VPC Service Controls: Cloud Logging.

Para definir permissões a fim de rotear o coletor para o destino, faça o seguinte:

Console

  1. Para receber informações sobre a conta de serviço do coletor, faça o seguinte:

    1. No painel de navegação do console do Google Cloud, selecione Logging e clique em Roteador de registros:

      Acessar o roteador de registros

    2. Selecione Menu e, em seguida, Visualizar detalhes do coletor.

      No painel Detalhes do coletor, o campo writerIdentity contém a identidade da conta de serviço. A string serviceAccount: faz parte da identidade da conta de serviço. Exemplo:

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
      
  2. No projeto de destino, conceda à identidade de gravador o papel necessário para que a conta de serviço grave no destino. Para conceder um papel a um principal, você precisa ter o papel de Proprietário (roles/owner):

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Criador de objetos do Storage (roles/storage.objectCreator).
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Editor de dados do BigQuery (roles/bigquery.dataEditor).
    • Para destinos do Pub/Sub, incluindo Splunk, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel de Editor do Pub/Sub (roles/pubsub.publisher).
    • Para destinos de bucket do Logging em diferentes projetos do Google Cloud, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel Gravador de bucket de registros (roles/logging.bucketWriter).
    • Para destinos de projetos do Google Cloud, adicione a identidade de gravador do coletor como principal usando o IAM e conceda a ele o papel de gravador de registros (roles/logging.logWriter). Especificamente, um principal precisa da permissão logging.logEntries.route.
    Se você não tiver acesso de Proprietário ao destino do coletor, peça para um proprietário do projeto adicionar a identidade de gravador como principal.

API

  1. Para receber informações sobre a conta de serviço do coletor, chame o método de API organizations.sinks.get ou folders.sinks.get.

    O campo writerIdentity contém a identidade da conta de serviço. A string serviceAccount: faz parte da identidade da conta de serviço. Exemplo:

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
    
  2. No projeto de destino, conceda à identidade de gravador o papel necessário para que a conta de serviço grave no destino. Para conceder um papel a um principal, você precisa ter o papel de Proprietário (roles/owner):

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Criador de objetos do Storage (roles/storage.objectCreator).
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Editor de dados do BigQuery (roles/bigquery.dataEditor).
    • Para destinos do Pub/Sub, incluindo Splunk, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel de Editor do Pub/Sub (roles/pubsub.publisher).
    • Para destinos de bucket do Logging em diferentes projetos do Google Cloud, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel Gravador de bucket de registros (roles/logging.bucketWriter).
    • Para destinos de projetos do Google Cloud, adicione a identidade de gravador do coletor como principal usando o IAM e conceda a ele o papel de gravador de registros (roles/logging.logWriter). Especificamente, um principal precisa da permissão logging.logEntries.route.
    Se você não tiver acesso de Proprietário ao destino do coletor, peça para um proprietário do projeto adicionar a identidade de gravador como principal.

gcloud

  1. Para informações sobre a conta de serviço do coletor, execute o seguinte comando:

    gcloud logging sinks describe SINK_NAME
    

    O campo writerIdentity contém a identidade da conta de serviço. A string serviceAccount: faz parte da identidade da conta de serviço. Exemplo:

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com
    
  2. No projeto de destino, conceda à identidade de gravador o papel necessário para que a conta de serviço grave no destino. Para conceder um papel a um principal, você precisa ter o papel de Proprietário (roles/owner):

    • Para destinos do Cloud Storage, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Criador de objetos do Storage (roles/storage.objectCreator).
    • Para destinos do BigQuery, adicione a identidade do gravador do coletor como principal usando o IAM e, em seguida, conceda o papel Editor de dados do BigQuery (roles/bigquery.dataEditor).
    • Para destinos do Pub/Sub, incluindo Splunk, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel de Editor do Pub/Sub (roles/pubsub.publisher).
    • Para destinos de bucket do Logging em diferentes projetos do Google Cloud, adicione a identidade do gravador do coletor como principal usando o IAM e conceda o papel Gravador de bucket de registros (roles/logging.bucketWriter).
    • Para destinos de projetos do Google Cloud, adicione a identidade de gravador do coletor como principal usando o IAM e conceda a ele o papel de gravador de registros (roles/logging.logWriter). Especificamente, um principal precisa da permissão logging.logEntries.route.
    Se você não tiver acesso de Proprietário ao destino do coletor, peça para um proprietário do projeto adicionar a identidade de gravador como principal.

A seguir