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

Neste documento, você verá como criar coletores agregados. Os coletores agregados permitem combinar e encaminhar registros gerados pelos recursosGoogle Cloud na sua organização ou pasta para um local centralizado.

Antes de começar

Antes de criar um coletor, verifique se:

  • Conhecer o comportamento dos coletores agregados. Para saber mais sobre esses coletores, consulte Visão geral dos coletores agregados.

  • Você tem uma Google Cloud pasta ou organização com entradas de registro que podem ser vistas no Explorador de registros.

  • Você tem um dos seguintes papéis do IAM para a organização ou pastaGoogle Cloud a partir da qual está roteando entradas de registro.

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

  • O destino do coletor agregado existe ou você tem a capacidade de criá-lo.

    Quando o destino é um projeto Google Cloud , ele pode estar em qualquer organização. Todos os outros destinos podem estar em qualquer projeto em qualquer organização.

  • Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

      After installing the Google Cloud CLI, initialize it by running the following command: 

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud .

Criar um coletor agregado

Para configurar um coletor agregado, crie-o e conceda as permissões de gravação no destino. Esta seção descreve como criar um coletor agregado. Para informações sobre como conceder permissões ao sink, consulte a seção desta página intitulada Definir permissões de destino.

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

Console

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

  1. No console Google Cloud , acesse a página Roteador de registros:

    Acessar o roteador de registros

    Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

  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 menu Selecionar serviço de coletor, selecione o tipo de destino e preencha a caixa de diálogo para especificar o destino. Você pode selecionar um destino atual ou criar um.

    • Para um sink de interceptação, selecione Google Cloud project e digite o nome totalmente qualificado do projeto Google Cloud de destino:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Para um coletor que não intercepta, selecione o destino e insira o nome totalmente qualificado dele. Os destinos abaixo são compatíveis:

      • Google Cloud project

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket do Cloud Logging

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

      • Conjunto de dados do BigQuery

        Você precisa inserir o nome totalmente qualificado de um conjunto de dados com gravação ativada. O conjunto de dados pode ser uma tabela particionada ou com divisões por data. Não insira o nome de um conjunto de dados vinculado. Os conjuntos de dados vinculados são somente leitura.

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

      • Bucket do Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Tópico do Pub/Sub

        pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

      • Splunk

        Insira o tópico do Pub/Sub para o serviço do Splunk.

  6. No painel Escolha os registros para incluir no coletor, selecione os recursos a serem incluídos no coletor.

    • Para um coletor de interceptação, selecione Interceptar registros ingeridos por esta organização e todos os recursos filhos.

    • Para um coletor que não intercepta, selecione Incluir registros ingeridos por este recurso e todos os recursos filhos.

  7. No campo Criar filtro de inclusão, insira uma expressão de filtro que corresponda às entradas de registro que você quer incluir. Se você não definir um filtro, todas as entradas de registro do recurso selecionado serão roteadas para o destino.

    Por exemplo, é possível criar um filtro para encaminhar 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")

    Para conferir exemplos de filtros, consulte a seção Criar filtros para coletores agregados desta página.

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

  8. Opcional: para verificar se você inseriu o filtro correto, selecione Visualizar registros. Isso abre o Explorador de registros em uma nova guia com o filtro pré-preenchido.

  9. 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 as entradas de registro de um projeto específico sejam roteadas para o destino, adicione o seguinte filtro de exclusão:

      logName:projects/PROJECT_ID

      Para excluir entradas de registro 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.

  10. Selecione Criar coletor.

  11. Para concluir a configuração do coletor agregado, conceda à conta de serviço dele a permissão para gravar entradas de registro no destino do coletor. Para mais informações, consulte Definir permissões de destino.

gcloud

Para criar um coletor agregado, use o comando logging sinks create:

  1. Para criar um coletor, chame o comando gcloud logging sinks create e inclua a opção --include-children.

    Antes de usar o comando a seguir, faça as seguintes substituições:

    • SINK_NAME: o nome do coletor de registros. Não é possível mudar o nome de uma sink depois de criá-la.
    • SINK_DESTINATION: o serviço ou projeto para onde você quer que as entradas de registro sejam roteadas. Para informações sobre o formato desses destinos, consulte Formatos de caminho de destino.
    • INCLUSION_FILTER: o filtro de inclusão de um coletor. Para conferir exemplos de filtros, consulte Criar filtros para coletores agregados.
    • FOLDER_ID: o ID da pasta. Se você quiser criar um coletor no nível da organização, substitua --folder=FOLDER_ID por -- organization=ORGANIZATION_ID.

    Execute o comando gcloud logging sinks create:

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

    Você também pode oferecer as seguintes opções:

    • Para criar um coletor de interceptação, inclua a opção --intercept-children.

    Por exemplo, se você estiver criando um coletor agregado no nível da pasta e cujo destino for um tópico do Pub/Sub, o comando poderá ter a seguinte aparência:

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

  2. Conceda à conta de serviço a permissão para gravar no destino do coletor. Para mais informações, consulte Definir permissões de destino.

REST

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

  1. Defina o campo parent como a organização ou a pasta 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:

    • Defina includeChildren como True.

    • Para criar um coletor de interceptação, defina o campo interceptChildren como True.

  3. Defina o campo filter para corresponder às entradas de registro que você quer incluir.

    Para conferir exemplos de filtros, consulte Criar filtros para coletores agregados.

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

  4. Defina os campos restantes do LogSink como faria para qualquer coletor. Para mais informações, consulte Rotear registros para destinos compatíveis.

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

  6. Conceda à conta de serviço a permissão para gravar no destino do coletor. Para mais informações, consulte Definir permissões de destino.

Qualquer mudança feita em um sink pode levar alguns minutos para ser aplicada.

Filtros para coletores agregados

Esta seção apresenta exemplos de filtros que podem ser usados em um coletor agregado. Para mais exemplos, consulte Amostra de consultas usando o Explorador de registros.

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 é restrito a 20.000 caracteres.

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

Selecionar a origem do registro

Para rotear entradas de registro de todos os recursos filhos, não especifique um projeto, pasta ou 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, as entradas de registro com um tipo de recurso de instâncias do Compute Engine gravadas em qualquer criança dessa organização são roteadas pelo sink agregado para o destino.

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

Os filtros a seguir restringem as entradas de registro a projetos, pastas ou organizações Google Cloud específicos:

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 as entradas de registro gravadas em instâncias do Compute Engine que foram gravadas na pasta my-folder, use o seguinte filtro:

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

Com o filtro anterior, as entradas de registro gravadas em qualquer recurso, exceto my-folder, incluindo as entradas de registro gravadas em projetos Google Cloud que são filhas de my-folder, não são roteadas para o destino.

Selecione o recurso monitorado.

Para rotear entradas de registro de apenas um recurso monitorado específico em um projeto doGoogle 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

Esta seção descreve como conceder ao Logging as permissões do Identity and Access Management para gravar entradas de registro 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 encaminha entradas de registro para qualquer destino, exceto um bucket de registros no projeto atual, é necessária uma conta de serviço para esse coletor. A geração de registros cria e gerencia automaticamente a conta de serviço para você:

  • A partir de 22 de maio de 2023, quando você criar um coletor e nenhuma conta de serviço para o recurso subjacente existir, o Logging vai criar a conta de serviço. O registro usa a mesma conta de serviço para todos os destinos no recurso subjacente. Os recursos podem ser um projeto 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 destinos no recurso subjacente.

A identidade do gravador de uma sink é o identificador da conta de serviço associada a ela. Todos os coletores têm uma identidade de gravador, a menos que gravam em um bucket de registros no projeto Google Cloud atual. O endereço de e-mail na identidade do gravador identifica o participante que precisa ter acesso para gravar dados no destino.

Para rotear entradas de registro para um recurso protegido por um perímetro de serviço, adicione a conta de serviço desse coletor a um nível de acesso e atribua-a ao perímetro de serviço de destino. 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 sink, faça o seguinte:

    1. No console Google Cloud , acesse a página Roteador de registros:

      Acessar o roteador de registros

      Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

    2. Selecione Menu e, depois, Ver detalhes do coletor. A identidade do gravador aparece no painel Detalhes do coletor.

    3. Se o valor do campo writerIdentity contiver um endereço de e-mail, prossiga para a próxima etapa. Quando o valor é None, não é preciso configurar as permissões de destino.

    4. Copie a identidade do gravador do coletor para a área de transferência. O exemplo a seguir ilustra uma identidade de gravador:

      serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  2. Conceda ao principal especificado pela identidade do gravador do coletor a permissão para gravar dados de registro no destino:

    1. No console Google Cloud , acesse a página IAM:

      Acesse o IAM

      Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo IAM e administrador.

    2. Na barra de ferramentas do console Google Cloud , selecione o projeto que armazena o destino da coletor agregado. Quando o destino for um projeto, selecione esse projeto.

    3. Clique em CONCEDER ACESSO.

    4. Insira o principal especificado pela identidade do gravador do coletor e conceda um papel do IAM:

gcloud

  1. Verifique se você tem acesso de proprietário no projetoGoogle Cloud que contém o destino. Se você não tiver acesso de proprietário ao destino do coletor, peça a um proprietário do projeto para adicionar a identidade do gravador como principal.

  2. Para receber informações sobre a conta de serviço do sink, chame o método gcloud logging sinks describe.

    Antes de usar o comando a seguir, faça as seguintes substituições:

    • SINK_NAME: o nome do coletor de registros. Não é possível mudar o nome de uma sink depois de criá-la.

    Execute o comando gcloud logging sinks describe:

    gcloud logging sinks describe SINK_NAME

  3. Se os detalhes do sink contiverem um campo com a etiqueta writerIdentity, siga para a próxima etapa. Quando os detalhes não incluem um campo writerIdentity, não é necessário configurar as permissões de destino para o coletor.

  4. Copie a identidade do gravador do coletor para a área de transferência. O exemplo a seguir ilustra uma identidade de gravador:

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  5. Conceda à identidade de gravador do coletor a permissão para gravar dados de registro no destino chamando o comando gcloud projects add-iam-policy-binding.

    Antes de usar o comando a seguir, faça as seguintes substituições:

    • PROJECT_ID: o identificador do projeto. Selecione o projeto que armazena o destino da coleção agregada. Quando o destino for um projeto, selecione esse projeto.
    • PRINCIPAL: um identificador do principal a quem você quer conceder o papel. Os identificadores dos principais geralmente têm o seguinte formato: PRINCIPAL-TYPE:ID. Por exemplo, user:my-user@example.com. Para uma lista completa dos formatos que PRINCIPAL pode ter, consulte Identificadores principais.

    • ROLE: um papel do IAM. Conceda à identidade do gravador do coletor um papel do IAM com base no destino do coletor de registros:

    Execute o comando gcloud projects add-iam-policy-binding:

    gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

Recomendamos que você use o console Google Cloud ou a Google Cloud CLI para conceder um papel à conta de serviço.

A seguir