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

Os coletores agregados no Cloud Logging permitem combinar e rotear entradas de registro de todos os recursos em uma pasta ou organização para um destino central. É possível configurar coletores como interceptadores ou não interceptadores, definir filtros de inclusão e exclusão e gerenciar permissões de gravação de destino.

Limitações

Ao configurar um coletor agregado, as seguintes limitações se aplicam:

  • Um caminho de destino só pode incluir um endpoint de serviço global, como pubsub.googleapis.com. Não é possível incluir um endpoint de serviço regional (REP, na sigla em inglês), como pubsub.LOCATION.rep.googleapis.com. Para uma lista de caminhos de destino compatíveis, consulte Formatos de caminho de destino.

  • Não é possível rotear dados de registro para tópicos do Pub/Sub com restrições em trânsito. Se você configurar um coletor de registros para um tópico do Pub/Sub com restrições em trânsito, talvez veja erros de configuração topic_region_not_allowed e registros descartados.

Antes de começar

Antes de criar um coletor, verifique se:

  • Você conhece o comportamento dos coletores agregados. Para mais informações, consulte Visão geral de coletores agregados.

  • Você tem uma pasta ou organização do Google Cloud com entradas de registro que podem ser vistas na Análise de registros.

  • Você tem um dos seguintes papéis do Identity and Access Management para a organização ou pasta doGoogle Cloud de onde 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ê pode criá-lo. O destino pode estar em qualquer projeto do Google Cloud e em qualquer organização. Para ver uma lista de destinos compatíveis e as limitações deles, consulte Destinos compatíveis.

  • Selecione a interface que você quer usar:

    Console

    Quando você usa o console do Google Cloud para acessar os serviços e as APIs do Google Cloud , não é necessário configurar a autenticação.

    gcloud

    Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada. Depois de fazer login, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    REST

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

      Instale a Google Cloud CLI e faça login na CLI gcloud com sua identidade federada.

    Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Criar um coletor agregado

Para configurar um coletor agregado, crie o coletor e conceda a ele as permissões para gravar no destino. Nesta seção, descrevemos como criar um coletor agregado. Para saber como conceder permissões ao coletor, consulte 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 do 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.

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

  5. No menu Selecionar serviço do coletor, selecione o tipo de destino e preencha a caixa de diálogo para especificar o destino. É possível selecionar um destino atual ou criar um.

    • Para um coletor de interceptação, selecione projeto doGoogle Cloud e insira o nome totalmente qualificado do projeto de destino doGoogle Cloud :

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

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

      • Google Cloud projeto

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket do Logging

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

      • Tópico do Pub/Sub

        Não insira o nome de um tópico do Pub/Sub que aplique restrições em trânsito.

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

  6. No painel Escolher 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 rotear todos os registros de auditoria de acesso a dados para um único bucket do Logging. Esse filtro é semelhante ao seguinte:

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

    Para ver exemplos, consulte Filtros para coletores agregados.

    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 a Análise de Registros em uma nova guia com o filtro pré-preenchido.

  9. Opcional: no painel Escolher registros para excluir 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 as 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 do coletor 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, execute o comando gcloud logging sinks create e inclua a flag --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 um coletor depois que ele é criado.
    • SINK_DESTINATION: o serviço ou projeto para onde você quer rotear as entradas de registro. 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 ver exemplos, consulte 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"

    Para criar um coletor de interceptação, inclua também a flag --intercept-children.

    Por exemplo, se você estiver criando um coletor agregado no nível da pasta com um tópico do Pub/Sub como destino, o comando será semelhante a este:

    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 do coletor 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 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:

    • Defina includeChildren como true.

    • Para criar um coletor de interceptação, defina também o campo interceptChildren como true.

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

    Para ver exemplos, consulte Filtros para coletores agregados.

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

  4. Defina os campos restantes de 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 do coletor permissão para gravar no destino do coletor. Para mais informações, consulte Definir permissões de destino.

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

Definir permissões de destino

Nesta seção, descrevemos como conceder à identidade de gravador de um coletor de registros as permissões do IAM necessárias para que o coletor possa gravar entradas de registro no destino do coletor. A identidade do gravador é o ID da conta de serviço associada ao coletor. Essa identidade inclui um endereço de e-mail que identifica o principal que precisa ter acesso para gravar dados no destino.

Não é necessário definir permissões de destino quando um coletor de registros encaminha entradas de registro para um bucket de registros no mesmo projeto. Para essa configuração, uma conta de serviço não é necessária. Para todas as outras configurações, o Logging cria e gerencia automaticamente a conta de serviço de um coletor de registros, e você precisa definir as permissões de destino:

  • A partir de 22 de maio de 2023, o Logging usa a mesma conta de serviço para todos os coletores no recurso subjacente. Os recursos podem ser um projeto doGoogle 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.

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 console do 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, em seguida, Ver detalhes do coletor. A identidade do gravador é exibida no painel Detalhes do coletor.

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

    4. Copie a identidade do gravador do coletor para a área de transferência. As identidades do gravador podem parecer diferentes dependendo do recurso ao qual o coletor pertence, mas sempre têm o prefixo serviceAccount:. Veja a seguir um exemplo de identidade de gravador:

      serviceAccount:service-123456789012@gcp-sa-logging.

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

    1. No console do 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 do Google Cloud , selecione o projeto que armazena o destino do coletor agregado. Quando o destino for um projeto, selecione-o.

    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 ao projeto doGoogle Cloud que contém o destino. Se você não tiver acesso de Proprietário ao destino do coletor, peça para um proprietário do projeto adicionar a identidade do gravador como principal.

  2. Para receber informações sobre a conta de serviço do coletor, execute o comando 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 um coletor depois que ele é criado.

    Execute o comando gcloud logging sinks describe:

    gcloud logging sinks describe SINK_NAME

  3. Se os detalhes do coletor tiverem um campo chamado writerIdentity, prossiga 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. Veja a seguir uma identidade de gravador:

    serviceAccount:service-123456789012@gcp-sa-logging.

  5. Conceda à identidade de gravador do coletor a permissão para gravar dados de registro no destino executando 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 do coletor agregado. Quando o destino for um projeto, selecione-o.
    • 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, . 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 do Google Cloud ou a Google Cloud CLI para conceder um papel à conta de serviço.

Filtros para coletores agregados

Nesta seção, mostramos exemplos de filtros que podem ser usados em um coletor agregado. Para mais exemplos, consulte Exemplos de consultas usando a Análise 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 tamanho 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, 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 esse filtro, o coletor agregado encaminha as entradas de registro das instâncias do Compute Engine em qualquer recurso filho dessa organização 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, talvez você queira armazenar registros de auditoria de pastas ou projetos específicos em um bucket do Cloud Storage próprio. Nessas situações, configure o filtro de inclusão para especificar cada recurso filho com as entradas de registro que você quer rotear. Se você quiser rotear 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 unir as instruções com uma cláusula OR.

Os filtros a seguir restringem as entradas de registro 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 entradas de registro geradas por instâncias do Compute Engine e originadas na pasta my-folder, use o seguinte filtro:

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

Com esse filtro, as entradas de registro que se originam em qualquer recurso que não seja my-folder, incluindo entradas de registro que se originam em projetos do Google Cloud que são filhos 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 com exatidão:

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 informações sobre os filtros do Logging, consulte Linguagem de consulta do Logging.

A seguir