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 registros. 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 dados de registros 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 Dados de Registros, consulte Consultar e analisar traces com a Análise de Dados de Registros.

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 você pode usar para receber notificações quando conteúdo ou padrões aparecem nos dados de rastreamento:

  • 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 alerta 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 ver ou analisar traces ou períodos individuais ou atributos anexados a períodos, use a página Explorador de traces. Para informações sobre essa página, consulte Encontrar e analisar traces.

  • Para monitorar a análise agregada dos dados de rastreamento, combine a Análise de registros com políticas de alertas. Neste cenário, você usa consultas SQL para consultar a visualização _AllSpans no bucket de observabilidade chamado _Trace. Por fim, você cria 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 rastreamento 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 com que frequência a política de alertas executa a consulta. O cronograma também define o tamanho da janela de lookback, que é um filtro que seleciona apenas os dados recebidos desde a última vez que a consulta foi avaliada. Por exemplo, se você definir o cronograma para 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 você a resolver os problemas que causaram o incidente. É possível conferir o incidente usando o console do Google Cloud .

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

As condições que monitoram o resultado de uma consulta SQL aceitam 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 de limite.

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

As políticas de alertas que monitoram o resultado de uma 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 rastreamento, é necessário configurar um conjunto de dados vinculado do BigQuery. Com os conjuntos de dados vinculados, o BigQuery pode ler seus dados de rastreamento e executar 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 projeto Google Cloud 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 reservados estão sujeitos aos preços do BigQuery.

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

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

Janela de lookback e tempo de propagação do incidente

Quando uma política de alertas é programada para avaliar a condição, a Análise de dados de registros 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 dados de registros 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 se propagar pelo sistema.

Falhas de consulta

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

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

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

  • Ocorrer um erro interno.

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

Antes de começar

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

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 para conceder a você os seguintes papéis do IAM no seu 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: não há 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, recomendamos que você crie vários tipos de canais de notificação. Para mais informações, 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, faça o seguinte:

Console doGoogle Cloud

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

    Acesse Análise de registros

    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 dados de registros, 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 dados de registros executa sua consulta no mecanismo do BigQuery e mostra os resultados na tabela Resultados.

    Se a opção Executar no BigQuery não aparecer, 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 dados de registros, clique em  Criar alerta.

    A página Análise de dados de registros mostra a janela Criar política de alertas de 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 sua política de alertas.

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

    1. Adicione canais de notificação e configure o conteúdo da notificação, como um assunto personalizado.

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

    3. Clique em Próxima.

  7. Revise a política de alertas e clique em Salvar para criá-la.

API Cloud Monitoring

Use o método alertPolicies.create para criar políticas de alertas de forma programática. O tipo Condition da sua política de alertas precisa ser MonitoringQueryLanguageCondition, que é uma instância de SqlCondition. Esse tipo permite que as condições da sua 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 contiver 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 atingir 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.

Terraform

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

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

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

  4. No Cloud Shell, insira terraform apply.

Para modificar sua 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 com o Terraform, consulte Terraform com Google Cloud.

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

A seguir