Configurar coletores agregados

Neste documento, você verá como criar coletores agregados. Para informações sobre como gerenciar coletores existentes, consulte Gerenciar coletores.

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

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

Para criar um coletor agregado, use a API Cloud Logging ou a ferramenta de linha de comando gcloud. Os coletores agregados não podem ser criados usando o Console do Google Cloud. É possível usar o Console do Google Cloud para criar somente coletores no nível do projeto (não agregados). Para criar coletores nos projetos do Cloud, consulte Configurar coletores.

Para uma visão geral conceitual mais ampla dos coletores, consulte Visão geral do roteamento e do armazenamento: coletores.

Destinos possíveis

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

  • Cloud Storage: arquivos JSON armazenados em buckets do Cloud Storage.
  • Pub/Sub: mensagens JSON entregues aos tópicos do Pub/Sub. Compatível com integrações de terceiros, como o Splunk, com o Logging.
  • BigQuery: tabelas criadas em conjuntos de dados do BigQuery.
  • Outro bucket do Cloud Logging: entradas de registro retidas nos buckets de registro do Cloud Logging.

Antes de começar

Antes de criar um coletor, verifique o seguinte:

  • Você tem um recurso com registros que podem ser vistos no Explorador de registros.

  • Você tem um dos seguintes papéis do IAM para a organização, pasta ou conta de faturamento do Google Cloud a partir da qual está enviando 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 os 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 dos coletores de registro precisa ser criado antes do coletor, por meio da ferramenta de linha de comando gcloud, do Console do Cloud ou das APIs do Google Cloud. É possível criar o destino em qualquer projeto do Cloud em qualquer organização, mas é necessário 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, pasta ou conta de faturamento do Google Cloud e defina o parâmetro includeChildren do coletor como True. Esse coletor poderá rotear as entradas de registro da organização, conta de faturamento ou pasta, além de (de maneira recursiva) de qualquer pasta, conta de faturamento ou projetos do Cloud. Defina os filtros de inclusão e exclusão do coletor para especificar as entradas de registro que você quer rotear para o destino.

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

API

Para criar um coletor de geração de registros, use organizations.Sinks.create, folders.Sinks.create ou billingAccounts.Sinks.create na API Logging. Prepare os argumentos do método da seguinte maneira:

  1. Defina o parâmetro parent como a organização, a pasta ou a conta de faturamento do Google Cloud para criar o coletor. O pai precisa ser um dos seguintes parâmetros:

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

    • Defina includeChildren como True.

    • Defina a propriedade filter. O comprimento de um filtro não pode exceder 20.000 caracteres.

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

    • Defina os campos restantes do LogSink como faria para qualquer coletor. Para mais informações, consulte Como criar coletores.

  3. Chame organizations.Sinks.create, folders.Sinks.create ou billingAccounts.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 permissão à conta de serviç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 de geração de registros, use o comando logging sinks create.

  1. Forneça o nome do coletor, o destino do coletor, o filtro e o ID da pasta, da conta de faturamento ou da organização.

    Por exemplo, configure um coletor agregado no nível da pasta desta forma:

    gcloud logging sinks create SINK_NAME \
    storage.googleapis.com/STORAGE_BUCKET_NAME --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 uma conta de faturamento, substitua --folder=FOLDER_ID por --billing-account=BILLING_ACCOUNT_ID.

    • Para que o coletor inclua todos os projetos da organização, a sinalização --include-children precisa ser definida, mesmo quando a sinalização --organization for passada para create. Quando definido como false (padrão), um coletor roteia 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.

Criar filtros para coletores agregados

Como qualquer coletor, o coletor agregado contém um filtro que seleciona entradas de registro individuais. Para exemplos de filtros que podem ser usados para criar o 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 filtro 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 rotear registros de projetos, pastas ou organizações específicas do Cloud, use uma das seguintes comparações de amostra:

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

Selecione o recurso monitorado.

Para rotear registros de apenas um recurso monitorado específico em um projeto do 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 ver uma lista de tipos de recursos, consulte Tipos de recursos monitorados.

Selecione uma amostra de entradas de registro

Para rotear uma amostra aleatória de entradas de registro, adicione a função integrada 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 ver a lista completa de papéis e permissões do Logging, consulte Controle de acesso.

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

Para rotear registros para um recurso protegido por um perímetro de serviço, adicione a conta de serviço desse coletor de registros a um nível de acesso e, em seguida, atribua-o ao serviço de destino perímetro. Isso não é necessário para coletores de nível do projeto (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:

API

  1. Consiga a conta de serviço do campo writerIdentity no seu coletor chamando o método de API organizations.Sinks.get, folders.Sinks.get ou billingAccounts.Sinks.get.

    A conta de serviço é semelhante a esta:

    serviceAccount:p123456789012-12345@gcp-sa-logging.iam.gserviceaccount.com
    
  2. Adicione a identidade de gravador do novo coletor à lista de permissões do destino, dando permissão ao gravador para gravar no destino.

    Se você tiver acesso de Proprietário do IAM ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade de gravador do coletor ao bucket do Cloud Storage e atribua a ele o papel Criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade de gravador do coletor ao conjunto de dados e conceda a ele o papel Editor de dados do BigQuery.
    • Para o Pub/Sub, incluindo o Splunk, adicione a identidade de gravador do coletor ao seu tópico e atribua a ele o papel Editor do Pub/Sub.
    • Para destinos de bucket do Logging em diferentes projetos do Cloud, adicione a identidade de gravador do coletor ao bucket de registro de destino e conceda a permissão roles/logging.bucketWriter.

    Se você não tiver proprietário ao destino do destino do coletor, envie o nome da conta de serviço da identidade do gravador para alguém que tenha essa capacidade. Essa pessoa precisa seguir as instruções da etapa anterior para adicionar a identidade do gravador ao destino do coletor.

gcloud

  1. Consiga a identidade de gravador do coletor, um endereço de e-mail, com o novo coletor:

  2. 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
    
  3. Se você tiver acesso de Proprietário do IAM ao destino, adicione a conta de serviço ao destino da seguinte maneira:

    • Para destinos do Cloud Storage, adicione a identidade de gravador do coletor ao bucket do Cloud Storage e atribua a ele o papel Criador de objetos do Storage.
    • Para destinos do BigQuery, adicione a identidade de gravador do coletor ao conjunto de dados e atribua a ele o papel Editor de dados do BigQuery.
    • Para o Pub/Sub, incluindo o Splunk, adicione a identidade de gravador do coletor ao seu tópico e atribua a ele o papel editor do Pub/Sub.
    • Para destinos de bucket do Logging em diferentes projetos do Cloud, adicione a identidade de gravador do coletor ao bucket de registro de destino e conceda a permissão roles/logging.bucketWriter.

    Se você não tiver proprietário ao destino do destino do coletor, envie o nome da conta de serviço da identidade do gravador para alguém que tenha essa capacidade. Essa pessoa precisa seguir as instruções da etapa anterior para adicionar a identidade do gravador ao destino do coletor.

    Por exemplo, para rotear registros entre buckets do Logging em projetos diferentes do Cloud, adicione roles/logging.bucketWriter à conta de serviço da seguinte maneira:

    1. Consiga a política de gerenciamento de identidade e acesso do projeto de destino do Cloud 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 que a conta de serviço grave apenas no destino 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
      

A seguir