Monitorar os resultados da consulta SQL com uma política de alertas

Este documento explica como criar uma política de alertas para monitorar os resultados de uma consulta executada na Análise de observabilidade. Essas consultas são escritas em SQL e precisam consultar uma visualização de observabilidade chamada _AllSpans. A política de alertas notifica você quando o resultado da consulta atende às condições especificadas.

As políticas de alertas criadas na página Análise de observabilidade são executadas em um mecanismo do BigQuery. Portanto, os dados consultados precisam estar acessíveis por um conjunto de dados vinculado do BigQuery.

Para informações gerais sobre a Análise de observabilidade, consulte Consultar e analisar traces com a Análise de observabilidade.

Como as políticas de alertas funcionam

Uma política de alertas descreve as circunstâncias em que você quer receber alertas e notificações sobre um incidente. Há algumas abordagens diferentes que podem ser usadas para receber notificações quando o conteúdo ou os padrões aparecem nos dados de trace:

  • Para monitorar o número de períodos do Cloud Trace ingeridos por mês, o uso da cota e a taxa de ingestão de períodos, crie políticas de alertas no Cloud Monitoring. Se você nunca criou uma política de alertas, consulte Criar políticas de alertas para informações detalhadas sobre como usar o console do Cloud Monitoring.

  • Para visualizar ou explorar traces ou períodos individuais ou visualizar atributos anexados a períodos, use a página Trace Explorer. Para informações sobre essa página, consulte Encontrar e explorar traces.

  • Para monitorar a análise agregada dos dados de trace, combine a Análise de observabilidade com políticas de alertas. Nesse cenário, você usa consultas SQL para consultar a visualização _AllSpans no bucket de observabilidade chamado _Trace. Por fim, crie a política de alertas para monitorar os resultados da consulta SQL. Esse tipo de política de alertas é chamado de política de alertas baseada em SQL.

    Para saber mais sobre como os dados de trace são armazenados, consulte Visão geral do armazenamento.

    O restante deste documento descreve como usar políticas de alertas baseadas em SQL.

Componentes da política de alerta

Uma política de alertas baseada em SQL contém uma condição e uma programação:

  • A condição contém a consulta, que é uma consulta SQL que consulta seus dados. A condição também define as circunstâncias em que o resultado da consulta faz com que o Monitoring crie um incidente.

  • A programação define a frequência com que a política de alertas executa a consulta. A programação também define o tamanho da janela de lookback, que é um filtro que seleciona apenas os dados recebidos desde a última vez em que a consulta foi avaliada. Por exemplo, se você definir a programação como 60 minutos, a consulta será executada a cada 60 minutos usando uma janela de lookback que seleciona os 60 minutos mais recentes de dados.

As políticas de alertas também contêm uma lista de canais de notificação. Quando a condição da política de alertas é atendida, o Cloud Monitoring cria um incidente e envia notificações sobre ele por esses canais. Um incidente é um registro dos dados que fizeram com que a condição fosse atendida, além de outras informações relevantes. Essas informações podem ajudar a resolver os problemas que causaram o incidente. É possível visualizar o incidente usando o Google Cloud console.

Tipos de avaliação para políticas de alertas baseadas em SQL

As condições que monitoram um resultado de consulta SQL oferecem suporte a dois tipos de avaliação:

  • Limite de contagem de linhas: a condição é atendida quando o número de linhas no resultado da consulta é maior, igual ou menor que um valor limite.

  • Booleano: a condição é atendida quando uma coluna booleana específica na tabela de resultados da consulta contém qualquer linha com um valor de true.

As políticas de alertas que monitoram um resultado de consulta SQL precisam ter apenas uma condição.

Políticas de alertas e BigQuery

Para que uma política de alertas consulte seus dados de trace, é necessário configurar um conjunto de dados vinculado do BigQuery. Os conjuntos de dados vinculados permitem que o BigQuery leia seus dados de trace e que você execute funções do BigQuery nos dados retornados pela consulta SQL.

Quando uma política de alertas executa uma consulta SQL, ela é executada no mecanismo do BigQuery no Google Cloud projeto em que a política de alertas está definida. Por padrão, as consultas executadas no mecanismo do BigQuery usam slots sob demanda. Os slots sob demanda e os slots reservados estão sujeitos a preços do BigQuery.

Também é possível configurar reservas de Slot do BigQuery dedicados para o projeto:

  1. Crie uma reserva com slots dedicados ou identifique uma reserva existente.
  2. Crie atribuições de reserva para o projeto.

Janela de lookback e tempo de propagação de incidentes

Quando uma política de alertas é programada para avaliar a condição, a Análise de observabilidade atrasa a execução da consulta SQL em cinco minutos para dar tempo de o Cloud Logging indexar os dados recebidos durante a janela de lookback. Por exemplo, se a política de alertas usar uma janela de lookback que termina às 14h, a Análise de observabilidade não vai executar a consulta SQL até as 14h05.

Se a condição de alerta for atendida após a execução da consulta, o incidente poderá levar até dois minutos adicionais para ser propagado pelo sistema.

Falhas de consulta

As consultas emitidas por políticas de alertas baseadas em SQL podem falhar por vários motivos, incluindo os seguintes:

  • A conta de serviço do Monitoring não existe mais ou não tem mais as permissões necessárias para ler os dados de trace que estão sendo consultados.

  • O tempo de execução da consulta excede cinco minutos.

  • Ocorre um erro interno.

Uma consulta com falha gera uma entrada de registro que contém o ID da política de alertas e o status do erro. É possível usar uma política de alertas baseada em registros para criar um alerta quando um erro é registrado.

Antes de começar

Esta seção pressupõe que você tenha um conjunto de dados vinculado do BigQuery para seus dados de trace.

Antes de criar uma política de alertas baseada em SQL, siga estas etapas:

  1. Para receber as permissões necessárias para consultar dados de trace e criar políticas de alertas baseadas em SQL, peça ao administrador que conceda a você os seguintes papéis do IAM no projeto:

  2. Verifique se a conta de serviço do Monitoring existe e se ela tem os seguintes papéis:

    1. Agente de serviço do Monitoring (roles/monitoring.notificationServiceAgent) no seu projeto.
    2. Leitor de dados do BigQuery (roles/bigquery.dataViewer) no conjunto de dados vinculado.

    Se a conta de serviço do Monitoring não existir, consulte Solução de problemas: nenhuma conta de serviço do Monitoring.

  3. Configure os canais de notificação que você quer usar para receber notificações de incidentes. Para fins de redundância, nós recomendamos que você crie vários tipos de canais de notificação. Para saber mais, consulte Criar e gerenciar canais de notificação.

Criar uma política de alertas baseada em SQL

Para criar uma política de alertas baseada em SQL, siga estas etapas:

Console

  1. No Google Cloud console, acesse a página Análise de observabilidade:

    Acessar a Análise de observabilidade

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

  2. Na página Análise de observabilidade, no editor de consultas, insira uma consulta SQL que consulte seus dados de trace.

  3. Na barra de ferramentas, clique em Executar no BigQuery.

    A Análise de observabilidade executa a consulta no mecanismo do BigQuery e mostra os resultados na tabela Resultados.

    Se Executar no BigQuery não for mostrado, clique em Selecionar mecanismo de consulta e em BigQuery. O botão Executar consulta muda para Executar no BigQuery.

  4. Na tabela Resultados da página Análise de observabilidade, clique em  Criar alerta.

    A página Análise de observabilidade mostra a janela Criar política de alertas SQL, que mostra sua consulta na seção Consulta SQL.

  5. Na seção Condição de alerta , configure a condição e a programação da política de alertas.

  6. Configure os detalhes do alerta da política de alertas.

    1. Adicione canais de notificação e configure o conteúdo da notificação, como uma linha de assunto personalizada.

    2. Opcional: adicione rótulos da política de alertas e documentação.

    3. Clique em Próxima.

  7. Revise a política de alertas e crie-a clicando em Salvar.

Terraform

  1. Instale e configure o Terraform para o projeto. Para App Hub configurações, selecione o projeto host do App Hub ou o projeto de gerenciamento.

  2. No Cloud Shell, acesse o diretório que contém a configuração do Terraform.

  3. Na configuração do Terraform, configure uma instância do google_monitoring_alert_policy, incluindo condition_sql.

  4. No Cloud Shell, digite terraform apply.

Para modificar a política de alertas, faça as edições e reaplique a configuração do Terraform. Para mais informações, consulte Gerenciar políticas de alertas com o Terraform.

Para informações gerais sobre como usar o Google Cloud Terraform, consulte Terraform com Google Cloud.

REST

Use o alertPolicies.create método para criar políticas de alerta programaticamente. O Condition tipo da política de alertas precisa ser MonitoringQueryLanguageCondition, que é uma instância de SqlCondition. Esse tipo de condição permite que as condições da política de alertas sejam definidas com SQL.

Para definir a programação, defina um valor periodicity para um dos campos minutes, hours ou days. Por exemplo, se você quiser que a consulta seja executada a cada 12 horas, defina a periodicidade do campo hours como 12.

Para definir a condição, use os seguintes campos:

  • boolean_test: configura a política de alertas para que a condição seja atendida quando uma linha de uma coluna booleana na tabela de resultados da consulta contém um valor verdadeiro.
  • row_count_test: configura a política de alertas para que a condição seja atendida quando o número de linhas na tabela de resultados da consulta atende a um determinado limite.

Para uma lista completa de campos e definições, consulte SqlCondition na documentação da API Cloud Monitoring.

Para mais informações sobre a API Monitoring para políticas de alertas, consulte Como gerenciar políticas de alertas por API.

Limitações

  • É possível ter uma condição por política de alertas baseada em SQL.

  • As consultas emitidas por políticas de alertas baseadas em SQL falham quando o tempo de execução excede cinco minutos.

  • Há um atraso de até sete minutos, mais o tempo de execução da consulta, entre o momento em que uma consulta é programada e quando um incidente é criado.

Para uma lista completa de limites associados a políticas de alertas, consulte Limites de monitoramento.

A seguir