Como gerenciar alertas com base em registros

É possível usar os alertas baseados em registros para notificá-lo sempre que uma mensagem específica aparecer nos registros incluídos. Neste documento, descrevemos como fazer o seguinte:

  • Crie e teste um alerta baseado em registro.
  • Editar um alerta baseado em registro
  • Exclua um alerta baseado em registro.

Antes de começar

Analise a comparação de alertas para determinar se os alertas baseados em registros são adequados aos dados nos seus registros. Exemplo:

  • Os alertas baseados em registros não operam em registros excluídos.

  • Não é possível usar alertas com base em registros para derivar contagens dos seus registros. Para derivar contagens, é necessário usar métricas com base em registros.

Criar um alerta baseado em registro (Explorador de registros)

É possível criar alertas com base em registros na página Explorador de registros no Console do Google Cloud ou usando a API Cloud Monitoring. Nesta seção, descrevemos como criar alertas com base em registros usando o Explorador de registros. Se você quiser criar alertas baseados em registros usando a API Cloud Monitoring, consulte Criar um alerta baseado em registros (API Monitoring)

A interface do Explorador de registros para criar e editar alertas baseados em registros orienta você nas seguintes etapas:

  • Forneça um nome e uma descrição para o alerta.
  • Escolha os registros para receber uma notificação.
  • Definir o tempo entre as notificações.
  • Especifique quem você quer notificar.

Por exemplo, suponha que você tenha um aplicativo que grave uma entrada de registro syslog com gravidade NOTICE quando o aplicativo alterar um endereço de rede. As entradas de registro para alterações de endereço de rede incluem um payload JSON semelhante a este:

"jsonPayload": {
  "type": "Configuration change",
  "action": "Set network address",
  "result": "IP_ADDRESS",
}

Você quer criar um alerta baseado em registro que notifique você quando um endereço IPv4 inválido aparecer no campo jsonPayload.result de entradas de registro em syslog com gravidade NOTICE.

Para criar o alerta baseado em registro, faça o seguinte:

  1. No Console do Cloud, selecione Logging e, em seguida, selecione Explorador de registros:

    Acesse o Explorador de registros

  2. Use o painel Consulta para criar uma consulta que corresponda à mensagem que você quer usar no alerta baseado em registro.

    Por exemplo, para encontrar entradas de registro com um nível de gravidade de NOTICE no registro syslog que têm endereços IP inválidos no payload JSON, use a seguinte consulta:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    Use Executar consulta no painel Resultados da consulta para validar a consulta.

  3. No painel Resultados da consulta, localize o menu Ações e selecione Criar alerta de registro.

  4. No painel Detalhes do alerta, forneça um nome e uma descrição para o alerta:

    1. Digite um nome para o alerta no campo Nome do alerta. Por exemplo: "Endereço de rede: valor IPv4 inválido".

    2. Digite uma descrição deste alerta. Você também pode incluir informações que possam ajudar o destinatário de uma notificação a diagnosticar o problema.

      Para informações sobre como formatar e adaptar o conteúdo desse campo, consulte Como usar o Markdown e as variáveis nos modelos de documentação.

  5. Clique em Próxima para avançar para a próxima etapa.

  6. No painel Escolher registros a serem incluídos no alerta, verifique a consulta e os resultados clicando em Visualizar registros.

    Recomendamos criar a consulta no painel Consulta do Explorador de registros. A consulta que você criou no painel Consulta também é exibida nesse painel, por exemplo:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    É possível editar a consulta neste painel, se necessário. Se você editar a consulta, verifique os resultados clicando em Visualizar registros.

  7. Clique em Próxima para avançar para a próxima etapa.

  8. Selecione o tempo mínimo entre as notificações. Esse valor permite controlar o número de notificações recebidas desse alerta, se ele for acionado várias vezes. Neste exemplo, selecione 5 minutos nas opções.

  9. Clique em Próxima para avançar para a próxima etapa.

  10. Selecione um ou mais canais de notificação para seu alerta. Neste exemplo, selecione um canal de notificação por e-mail.

    Se você já tiver um canal de notificação por e-mail configurado, selecione-o na lista. Caso contrário, clique em Gerenciar canais de notificação e adicione um canal de e-mail. Para saber mais sobre como criar canais de notificação, consulte Como gerenciar canais de notificação.

  11. Clique em Save.

Seu alerta com base em registros está pronto para ser testado.

Teste o exemplo de alerta baseado em registro

Para testar o alerta que você criou, grave manualmente uma entrada de registro que corresponda à consulta usando as etapas a seguir:

  1. Acesse a página de referência logEntries.write ou clique no botão a seguir:

    Acessar logEntries.write

  2. No painel Testar esta API, faça o seguinte:

    1. Na entrada de registro a seguir, altere a variável PROJECT_ID para o ID do projeto:

      {
        "entries": [
        {
          "logName": "projects/PROJECT_ID/logs/syslog",
          "jsonPayload": {
            "type": "Configuration change",
            "action": "Set network address",
            "result": "999.027.405.1",
          },
          "severity": "NOTICE",
          "resource": {
            "type": "generic_task",
            "labels" : {
              "project_id": "PROJECT_ID",
              "location": "us-east1",
              "namespace": "fake-task",
              "job": "write-log-entry",
              "task_id": "1",
            },
          },
        ],
      }
      
    2. Copie a entrada de registro e substitua o conteúdo do campo Corpo da solicitação no APIs Explorer pela entrada de registro copiada.

    3. Clique em Executar.

      Se a chamada logEntries.write for bem-sucedida, você receberá um código de resposta HTTP 200 e um corpo de resposta vazio, {}. Para mais informações sobre o APIs Explorer, consulte Como usar o APIs Explorer na documentação do Monitoring. O APIs Explorer funciona da mesma maneira com a API Logging.

A entrada de registro corresponde ao filtro especificado para o alerta das seguintes maneiras:

  • O valor logName especifica o registro syslog no seu projeto do Cloud.
  • O valor severity dessa entrada de registro é NOTICE.
  • O valor jsonPayload.result não é um endereço IPv4 válido.

Depois que você grava a entrada de registro, ocorre a seguinte sequência:

  • A nova entrada de registro aparece no Explorador de registros e aciona o alerta.
  • Um incidente é aberto no Cloud Monitoring.
  • Você recebe uma notificação sobre o incidente. Se você tiver configurado um canal de notificação de e-mail, a notificação será semelhante à seguinte captura de tela:

    O exemplo de alerta baseado em registro gera uma notificação por e-mail.

Clique em Ver incidente no e-mail para ver o incidente no Cloud Monitoring. Para saber mais sobre incidentes, consulte Como gerenciar incidentes para alertas com base em registros.

Outros cenários: alertas em registros de auditoria

O exemplo em Como criar um alerta baseado em registro é artificial. normalmente, você não cria um alerta e grava manualmente uma entrada de registro para testá-lo. Na maioria dos casos, as entradas de registro são gravadas por aplicativos ou outros serviços. Mas a única diferença na criação do alerta baseado em registro é a consulta usada para selecionar as entradas de registro.

As seções a seguir descrevem cenários realistas de alertas baseados em registros com base no conteúdo dos registros de auditoria e ilustram como criar as consultas para isolar as entradas de registro desejadas nos registros de auditoria. Caso contrário, o procedimento para criar os alertas baseados em registros será o mesmo mostrado em Como criar alertas baseados em registros.

Alertas sobre acesso humano de secrets

Suponha que seu projeto armazene secrets no Gerenciador de secrets, e alguns deles foram criados apenas para contas de serviço. Exceto em circunstâncias incomuns, esses secrets nunca são acessados por um usuário humano.

Se você ativou a geração de registros de auditoria para o Gerenciador de secrets, cada tentativa bem-sucedida de acessar um secret criará uma entrada de registro de auditoria. Cada entrada inclui o nome do secret e a identidade do autor da chamada.

É possível criar um alerta baseado em registro que notifique você se um secret for acessado por um usuário humano.

Veja a seguir o trecho de uma entrada de registro de auditoria escrita pelo Secret Manager. O trecho mostra os campos úteis para criar a consulta de um alerta baseado em registro:

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "serviceName": "secretmanager.googleapis.com",
    "methodName": "google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion",
    "authenticationInfo": {
      "principalEmail": "my-svc-account@PROJECT_ID.iam.gserviceaccount.com",
      "serviceAccountDelegationInfo": [],
      "principalSubject": "serviceAccount:my-svc-account@PROJECT_ID.iam.gserviceaccount.com"
    },
    ...
  },
  ...
}

Os seguintes subcampos do protoPayload são de interesse específico:

  • @type: indica que esta entrada de registro é uma entrada de registro de auditoria.
  • serviceName: registra o serviço que gravou a entrada de registro de auditoria. Use este campo para identificar entradas gravadas pelo Secret Manager.
  • methodName: identifica o método em que a entrada de registro de auditoria foi gravada. Use esse campo para identificar a ação que causou a criação dessa entrada. Neste exemplo, é o método AccessSecretVersion.
  • authenticationInfo.principalEmail: registra a conta que invocou o método no campo methodName. O valor esperado nesse campo é uma conta de serviço que termina com gserviceaccount.com.

Para encontrar entradas de registro para acesso secreto de um usuário humano, procure entradas de registro de auditoria gravadas pelo Secret Manager. Você quer encontrar as entradas de registro em que o método AccessSecretVersion foi invocado por um principal que não termina com gserviceaccount.com. A consulta a seguir isola essas entradas de registro:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "secretmanager.googleapis.com"
protoPayload.methodName =~ "AccessSecretVersion$"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

Para criar um alerta baseado em registro para acesso humano aos secrets, use esta consulta no painel Escolher registros a serem incluídos no alerta.

Alertas sobre eventos de descriptografia

A análise do exemplo anterior pode ser adaptada a outros serviços. Por exemplo, se você usar o Cloud Key Management Service para criptografar e descriptografar dados confidenciais, é possível usar os registros de auditoria gerados pelo Cloud KMS para determinar se um usuário humano descriptografa um valor.

Para encontrar entradas de registro para descriptografia feita por um usuário humano, procure entradas de registro de auditoria gravadas pelo Cloud KMS. Você quer encontrar as entradas de registro em que o método Decrypt foi invocado por um principal que não termina com gserviceaccount.com, que indica uma conta de serviço. A consulta a seguir isola essas entradas de registro:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "cloudkms.googleapis.com"
protoPayload.methodName = "Decrypt"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

Para criar um alerta baseado em registro para descriptografia realizado por um usuário humano, use essa consulta no painel Escolher registros a serem incluídos no alerta.

Gerenciar alertas com base em registros no Monitoring

É possível ver, editar e excluir alertas com base em registros no Cloud Monitoring. Não é possível criar alertas com base em registros no Console do Google Cloud para o Monitoring. Os alertas baseados em registros precisam ser criados usando o Explorador de registros ou a API Monitoring.

Para ver uma lista de todas as políticas de alertas no seu projeto do Google Cloud, siga um dos procedimentos a seguir:

  • Para navegar do Logging:

    1. No Console do Cloud, selecione Logging e, em seguida, selecione Explorador de registros:

      Acesse o Explorador de registros

    2. No painel Resultados da consulta, localize o menu Ações e selecione Gerenciar alertas.

  • Para navegar no Monitoring:

    1. No Console do Cloud, selecione Monitoramento:

      Acessar o Monitoramento

    2. Selecione Alertas.

    3. Uma lista parcial de políticas é mostrada no painel Políticas. Para ver todas as políticas e ativar a filtragem, clique em Ver todas as políticas.

Essas duas ações levam você à página Políticas do Monitoring, que lista todas as políticas de alertas no seu projeto do Cloud.

Para restringir as políticas de alerta listadas, adicione filtros. Cada filtro é composto por um nome e um valor. É possível definir o valor como uma correspondência exata para um nome de política ou uma correspondência parcial. As correspondências não diferenciam maiúsculas de minúsculas. Se você tiver vários filtros, os filtros serão unidos automaticamente por um AND lógico, a menos que você insira um filtro OR. Veja na captura de tela a seguir as políticas de alertas ativadas no momento criadas após 1o de janeiro de 2021:

Lista de políticas de alertas ativadas criadas após 1o de janeiro de 2021.

Na página Políticas, é possível editar, excluir, copiar, ativar ou desativar uma política de alertas:

  • Para editar ou copiar uma política, clique em Mais opções e selecione a opção desejada. Editar e copiar uma política é semelhante ao procedimento descrito em Como criar um alerta baseado em registro . É possível alterar e, em alguns casos, excluir os valores nos campos. Quando terminar, clique em Salvar.

    Também é possível editar uma política de alertas baseada em registro clicando no nome dela na lista de políticas.

  • Para excluir uma política, clique em Mais opções e selecione Excluir. Na caixa de diálogo de confirmação, selecione Excluir.

  • Para ativar ou desativar a política de alertas, clique no botão localizado abaixo do título Ativado.

Criar um alerta baseado em registro (API Monitoring)

É possível criar alertas com base em registros usando a API Cloud Monitoring. Forneça as mesmas informações à API Monitoring que você fornece ao usar o Explorador de registros no Console do Google Cloud:

  • Um nome e uma descrição para o alerta.
  • Os registros de que você quer receber uma notificação.
  • O tempo entre as notificações.
  • Quem deve ser notificado.

Para criar políticas de alertas usando a API Monitoring, crie um objeto AlertPolicy e envie-o para o método alertPolicies.create.

Antes de usar a API Monitoring, é necessário ativar a API e ter autorização para usá-la. Para mais informações, consulte a documentação a seguir:

Estrutura de políticas de alertas

A API Cloud Monitoring representa uma política de alertas usando a estrutura AlertPolicy. A estrutura AlertPolicy tem várias estruturas incorporadas, incluindo uma descrição da condição que aciona o alerta. As políticas de alertas baseadas em registros diferem das políticas de alertas baseadas em métricas das seguintes maneiras:

  • Para descrever a condição, use o tipo de condição LogMatch. As políticas de alertas com base em métricas usam diferentes tipos de condição.
  • Uma política de alertas baseada em registros pode ter apenas uma condição.
  • Especifique o tempo entre as notificações incluindo uma estrutura AlertStrategy. As políticas de alertas com base em métricas não incluem um tempo entre as notificações.

Como gerenciar políticas de alertas por API descreve como criar, listar, editar e excluir políticas de alertas usando a API Monitoring. Nesta seção, descrevemos como criar uma política de alertas com base em registros. Essas políticas são diferentes das políticas de alertas baseadas em métricas no tipo de condição usada. Para alertas com base em registros, o tipo de condição é LogMatch.. Quando você usa a API Monitoring para gerenciar políticas de alertas com base em registros, não há diferenças na forma como você lista, edita ou exclui as políticas.

Projetar a política de alertas

Em Criar um alerta baseado em registro (Explorador de registros), crie um alerta baseado em registro que notifique você quando um endereço IPv4 inválido aparecer no campo jsonPayload.result do registro. entradas em syslog com gravidade NOTICE.

Para criar o mesmo alerta baseado em registro usando a API Monitoring, crie um objeto AlertPolicy como esta estrutura JSON:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "A network address has been set to an invalid value for IPv4.",
    "mimeType": "text/markdown"
  },

  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\") severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",

  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    }
  },

  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Esse código JSON especifica as mesmas informações que você especifica ao criar um alerta baseado em registro usando o Explorador de Registros. As seções a seguir mapeiam o conteúdo dessa estrutura AlertPolicy para as etapas a serem seguidas ao usar o Explorador de registros para criar um alerta baseado em registro. O valor do campo conditionMatchedLog é uma estrutura LogMatch.

Fornecer um nome e uma descrição

Uma política de alertas tem um nome de exibição e uma documentação associada fornecida com notificações para ajudar os socorristas. No Explorador de registros, eles são chamados de Nome do alerta e Descrição do alerta. Esses valores são representados em uma estrutura AlertPolicy da seguinte maneira:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "A network address has been set to an invalid value for IPv4.",
    "mimeType": "text/markdown"
  },
  ...
}

O valor de displayName neste exemplo anexa "(API)" ao nome fornecido ao Explorador de registros para que seja possível distinguir entre as duas políticas ao visualizar a lista de políticas no Console do Cloud. A página Políticas do Monitoring lista políticas por nome de exibição e indica se a política é baseada em métricas ou registros. Para mais informações, consulte Gerenciar alertas com base em registros no Monitoring.

O campo documentation inclui, no subcampo content, a descrição que você pode fornecer ao usar o Explorador de registros. O segundo subcampo, mimeType, será obrigatório se você especificar um valor para o campo documentation. O único valor válido é "text/markdown".

Escolha os registros para receber uma notificação

Uma política de alertas com base em registros tem uma única condição. No Explorador de registros, especifique a condição ao fornecer uma consulta no campo Definir entradas de registro para alertas em. Esses valores são representados em uma estrutura AlertPolicy da seguinte maneira:

{ ...
  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",
  ...
}

O campo conditions utiliza uma lista de estruturas Condition, mas uma política de alertas baseada em registros precisa ter apenas uma condição. Cada Condition tem um nome de exibição e uma descrição da condição.

  • O valor do campo displayName é uma breve descrição da condição. Quando você usa o Explorador de registros para criar alertas com base em registros, o nome de exibição é sempre "Condição de correspondência de registro". Quando você usa a API Monitoring, é possível fornecer um nome de exibição mais preciso. É necessário informar um valor.

  • O valor do campo conditionMatchedLog é uma estrutura LogMatch, e o valor do campo filter é a consulta especificada no Explorador de registros. Como essa consulta é comprovada como o valor de um campo JSON, toda a consulta é exibida entre aspas, e as aspas na própria consulta precisam ter escape com o caractere \ (barra invertida).

O valor do campo combiner especifica como combinar os resultados de várias condições em políticas de alertas com base em métricas. Só é possível usar uma condição nos alertas baseados em registros e é necessário especificar o campo combiner com o valor "OR". Não é possível criar alertas baseados em registros com várias condições.

Definir o tempo entre as notificações

Uma política de alerta para um alerta baseado em registro especifica o tempo mínimo entre as notificações. No Explorador de registros, selecione um valor no menu Tempo entre as notificações. Para representar esse valor em uma estrutura AlertPolicy, especifique um valor em segundos para o campo period de uma estrutura NotificationRateLimit incorporada a um { 101)AlertStrategy:

{ ...
  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    }
  },
  ...
}

O valor do campo period neste exemplo, 300s, é equivalente a cinco minutos.

Especifique quem notificar

Uma política de alertas pode incluir uma lista de canais de notificação. No Explorador de registros, você seleciona canais em um menu. Esses valores são representados em uma estrutura AlertPolicy fornecendo uma lista de um ou mais nomes de recursos para objetos NotificationChannel configurados:

{ ...
  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Quando você cria um canal de notificação, um nome de recurso é atribuído a ele. Para informações sobre como recuperar a lista de canais de notificação disponíveis, incluindo os nomes dos recursos, consulte Como recuperar canais na documentação do Monitoring. Não é possível receber os IDs dos canais usando o Console do Cloud.

Enviar a política de alertas para a API Cloud Monitoring

Para criar uma política de alertas usando a API Monitoring, crie um objeto AlertPolicy e envie-o para o método alertPolicies.create. É possível invocar alertPolicies.create usando a ferramenta de linha de comando gcloud, chamando a API Monitoring diretamente ou usando bibliotecas de cliente.

Para criar uma política de alertas usando a ferramenta gcloud, faça o seguinte:

  1. Coloque a representação JSON da sua política de alertas em um arquivo de texto, por exemplo, em um arquivo chamado alert-invalid-ip.json.

  2. Transmita esse arquivo JSON à ferramenta gcloud usando o seguinte comando:

    gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"
    
  3. Se for bem-sucedido, este comando retornará o nome do recurso da nova política, por exemplo:

    Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
    

Para criar uma política de alertas chamando alertPolicies.create diretamente, use a ferramenta APIs Explorer da seguinte maneira:

  1. Acesse a página de referência de alertPolicies.create.

  2. No painel Testar esta API, faça o seguinte:

    1. No campo name, digite o seguinte valor:

      projects/PROJECT_ID
      
    2. Copie a representação JSON da política de alertas e substitua o conteúdo do campo Corpo da solicitação no APIs Explorer pela política de alertas copiada.

    3. Clique em Executar.

      Se a chamada alertPolicies.create for bem-sucedida, você receberá um código de resposta HTTP 200 e um corpo de resposta vazio, {}. Para mais informações sobre o APIs Explorer, consulte Como usar o APIs Explorer na documentação do Monitoring.

Para mais informações sobre como criar políticas de alertas usando a API Monitoring, consulte Como criar políticas. Os exemplos desta página usam tipos de condição para políticas de alertas com base em métricas, mas os princípios são os mesmos.

Teste a política de alertas

Para testar sua nova política de alertas, use o mesmo procedimento descrito em Testar o alerta baseado em registro de exemplo.