Uma política de alertas é representada na API Cloud Monitoring
por um objeto AlertPolicy
,
que descreve um conjunto de condições que indicam um status
potencialmente não íntegro em seu sistema.
Neste documento, descrevemos o seguinte:
- Como a API Monitoring representa as políticas de alertas.
- Os tipos de condições que a API Monitoring fornece para e políticas de alertas.
- Como criar uma política de alertas usando a CLI do Google Cloud ou as bibliotecas de cliente.
Estrutura de uma política de alertas
A estrutura AlertPolicy
define os componentes de uma política de alertas. Ao criar uma política, você especifica valores para os
seguintes campos AlertPolicy
:
displayName
: um rótulo descritivo para a política.documentation
: recomendamos que você use esse campo para fornecer informações que ajudem os socorristas. Para mais informações, consulte Anexar documentação definida pelo usuário às notificações.userLabels
: qualquer rótulo definido pelo usuário anexado à política. Para informações sobre como usar rótulos com alertas, consulte Anexar rótulos a incidentes.conditions[]
: uma matriz de estruturasCondition
.combiner
: um operador lógico que determina como lidar com vários pelas condiçõesnotificationChannels[]
: uma matriz de nomes de recursos, cada um identificando umNotificationChannel
.alertStrategy
: especifica a rapidez com que o Monitoring encerra incidentes quando os dados param de chegar. Esse objeto também especifica se notificações repetidas são ativadas para políticas de alertas com base em métricas, e o intervalo entre essas notificações. Para mais informações, consulte Configurar notificações repetidas para políticas de alertas baseadas em métricas.
Também é possível especificar o campo severity
ao usar a API Cloud Monitoring.
e o console do Google Cloud. Esse campo permite definir o nível de gravidade dos incidentes. Se você não especificar uma gravidade,
o Cloud Monitoring definirá a gravidade da política de alertas como No Severity
.
Há outros campos que você pode usar, dependendo das condições que criar.
Quando uma política de alertas contém uma condição, uma notificação é enviada se essa condição for atendida. Para informações sobre notificações ao alertar políticas contêm várias condições, consulte Políticas com várias condições e Número de notificações por política.
Quando você cria ou modifica a política de alertas, o Monitoring também define outros campos, incluindo o name
. O valor do campo name
é o nome do recurso da política de alertas, que identifica a
política. O nome do recurso tem o seguinte formato:
projects/PROJECT_ID/alertPolicies/POLICY_ID
Tipos de condições na API
A API Cloud Monitoring é compatível com vários tipos de condição na
estrutura Condition
. Há vários tipos de condição para políticas de alertas com base em métricas e outro para políticas de alertas com base em registros. As seções a seguir descrevem os tipos de condição disponíveis.
Condições para políticas de alertas com base em métricas
Para criar uma política de alertas que monitore dados de métricas, incluindo você pode usar os seguintes tipos de condição:
Condições de métrica com base em filtro
As condições MetricAbsence
e MetricThreshold
usam filtros de monitoramento para selecionar os dados de série temporal a serem monitorados. Outros campos na estrutura de condições especificam como filtrar,
agrupar e agregar os dados. Para mais informações sobre esses conceitos, consulte Filtragem e agregação: como manipular séries temporais.
Se você usar o tipo de condição MetricAbsence
, poderá criar uma condição
que só é atendida quando todas as séries temporais estão ausentes. Esta condição usa
o parâmetro aggregations
para agregar várias série temporal em uma única
série temporal. Para mais informações, consulte
a referência MetricAbsence
na documentação da API.
Uma política de alerta de ausência de métrica exige que alguns dados tenham sido gravados anteriormente. Para mais informações, consulte Criar políticas de alertas de ausência de métrica.
Se você quiser receber notificações com base em um valor previsto, configure
a política de alertas para usar o
tipo de condição MetricThreshold
e definir o campo forecastOptions
. Quando
este campo não for definido, os dados medidos serão comparados a um limite.
No entanto, quando esse campo é definido, os dados previstos são comparados a um
limite. Para mais informações, consulte Criar políticas de alertas de valor de métrica previsto.
Condições de métrica baseadas em MQL
A condição MonitoringQueryLanguageCondition
usa a linguagem de consulta do Monitoring (MQL, na sigla em inglês) para selecionar e manipular os dados de séries temporais a serem monitoradas. É possível criar políticas
de alerta que comparam valores com um limite ou testar a ausência
de valores com esse tipo de condição.
Se você usar uma condição MonitoringQueryLanguageCondition
, ela precisará ser a única condição na política de alertas. Para mais informações, consulte
Políticas de alertas com a MQL.
Condições da métrica com base em PromQL
A condição PrometheusQueryLanguageCondition
usa a linguagem de consulta do Prometheus (PromQL, na sigla em inglês)
consultas para selecionar e manipular dados de série temporal para monitoramento.
Sua condição pode calcular uma proporção de métricas, avaliar comparações de métricas e muito mais.
Se você usar uma condição PrometheusQueryLanguageCondition
, ela precisará ser a única
na política de alertas. Para mais informações, consulte
Políticas de alertas com o PromQL.
Condições para alertas de proporções
É possível criar políticas de alertas de limite de métricas para monitorar a proporção de duas métricas. É possível criar essas políticas usando o tipo de condição MetricThreshold
ou MonitoringQueryLanguageCondition
.
Também é possível usar o MQL diretamente no console do Google Cloud. Não é possível criar ou gerenciar condições com base em proporção usando a interface gráfica para criar condições de limite.
Recomendamos o uso de MQL para criar políticas de alertas com base em proporção.
A MQL permite criar consultas mais eficientes e flexíveis do que é possível criar usando o tipo de condição MetricTheshold
e filtros do Monitoring.
Por exemplo, com uma condição MonitoringQueryLanguageCondition
, é possível
calcular a proporção de uma métrica em relação a uma métrica delta. Para mais informações, consulte
Exemplos de política de alertas do MQL.
Se você usar a condição MetricThreshold
, o numerador e o denominador
da proporção precisarão ter os mesmos MetricKind
.
Para ver uma lista de métricas e suas propriedades, consulte Listas de métricas.
Em geral, é melhor calcular proporções com base em séries temporais coletadas para um único tipo de métrica usando valores de rótulo. Uma proporção calculada em dois tipos diferentes de métricas está sujeita a anomalias devido a períodos de amostragem e janelas de alinhamento diferentes.
Por exemplo, suponha que você tem dois tipos de métrica diferentes, uma contagem total de RPC e uma contagem de erros de RPC, e quer calcular a proporção de contagem de erros de RPC em relação ao total de RPCs. As RPCs malsucedidas são contadas na série temporal dos dois tipos de métricas. Portanto, há uma chance de que, quando você alinha a série temporal, uma RPC malsucedida não apareça no mesmo intervalo de alinhamento para as duas séries temporais. Essa diferença pode ocorrer por vários motivos, incluindo:
- Como há duas séries temporais diferentes gravando o mesmo evento, há dois valores de contador subjacentes implementando a coleta, e eles não são atualizados atomicamente.
- As taxas de amostragem podem ser diferentes. Quando as séries temporais estão alinhadas a um período comum, as contagens de um único evento podem aparecer em intervalos de alinhamento adjacentes na série temporal de diferentes métricas.
A diferença no número de valores nos intervalos de alinhamento correspondentes pode
levar a valores de proporção error/total
ilógicos, como 1/0 ou 2/1.
Proporções de números maiores têm menos probabilidade de resultar em valores sem sentido. É possível conseguir números maiores por agregação, seja usando uma janela de alinhamento que é maior do que o período de amostragem ou agrupando dados de uma rótulos. Essas técnicas minimizam o efeito de pequenas diferenças no número de pontos em um determinado intervalo. Ou seja, uma disparidade de dois pontos é mais significativa quando o número esperado de pontos em um intervalo é 3 do que quando o número esperado é 300.
Se você estiver usando tipos de métricas integrados, talvez não tenha opção senão calcular proporções nos tipos de métricas para obter o valor necessário.
Se você estiver criando métricas personalizadas para contar o mesmo resultado (como RPCs que retornam status de erro) em duas métricas diferentes, considere uma única métrica que inclua cada contagem apenas uma vez. Por exemplo, suponha que você esteja contando RPCs e queira rastrear a proporção de RPCs malsucedidas para todas as RPCs. Para resolver esse problema, crie um único tipo de métrica para contar RPCs e use um rótulo para registrar o status da invocação, incluindo o status "OK". Depois, cada valor de status, de erro ou "OK" será registrado ao atualizar um contador único para esse caso.
Condição para políticas de alertas com base em registros
Para criar uma política de alertas baseada em registros, que notifica você quando uma mensagem correspondente ao seu filtro aparecer nas entradas de registro, use o tipo de condição LogMatch
. Se você usar uma condição LogMatch
, ela precisará ser a única condição na política de alertas.
Não tente usar o tipo de condição LogMatch
em conjunto com métricas
com base em registros. As políticas de alertas que monitoram métricas com base em registros são baseadas em métricas
políticas. Para mais informações sobre como escolher entre políticas de alertas que monitoram métricas ou entradas de registro baseadas em registros, consulte Como monitorar seus registros.
As políticas de alertas usadas nos exemplos da O documento Gerenciar políticas de alertas por API se baseia em métricas. alertando mas os princípios são os mesmos das políticas de alertas com base em registros. Para informações específicas sobre políticas de alertas com base em registros, consulte Criar uma política de alertas com base em registros usando a API Monitoring na documentação do Cloud Logging.
Antes de começar
Para escrever código na API, você precisa cumprir estes requisitos:
- Estar familiarizado com os conceitos gerais e a terminologia usada em políticas de alerta. Consulte Visão geral de alertas para mais informações.
- Verifique se a API Cloud Monitoring está ativada para uso. Consulte Como ativar a API para mais informações.
- Se você planeja usar bibliotecas de cliente, instale as bibliotecas para as línguas que você quer usar. Consulte Bibliotecas de cliente para saber detalhes. Atualmente, a API é compatível com alertas somente em C#, Go, Java, Node.js e Python.
Se você planeja usar a Google Cloud CLI, instale-a. No entanto, se você usar o Cloud Shell, a Google Cloud CLI será já instalado.
Aqui, também são fornecidos exemplos usando a interface
gcloud
. Observe que os exemplosgcloud
assumem que o projeto atual já foi definido como o destino (gcloud config set project [PROJECT_ID]
), portanto, as chamadas omitem a sinalização explícita--project
. O código do projeto atual nos exemplos éa-gcp-project
.
-
Para ter as permissões necessárias para criar e modificar políticas de alertas usando a API Cloud Monitoring: peça ao administrador para conceder a você Papel do IAM Editor de AlertPolicy do Monitoring (
roles/monitoring.alertPolicyEditor
) no projeto. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.
Para informações detalhadas sobre papéis do IAM para Monitoring, consulte Controle o acesso com o Identity and Access Management.
Projete seu aplicativo para chamadas da API Cloud Monitoring de linha de execução única que modificar o estado de uma política de alertas em um projeto do Google Cloud. Por exemplo, chamadas de API de linha única que criam, atualizam ou excluem uma política de alertas.
Criar uma política de alertas
Para criar uma política de alertas em um projeto, use o método alertPolicies.create
. Para informações sobre como invocar esse
método, os parâmetros dele e os dados de resposta, consulte a página de referência
alertPolicies.create
.
Você pode criar políticas com base em arquivos JSON ou YAML.
A CLI do Google Cloud aceita esses arquivos como argumentos.
é possível ler programaticamente arquivos JSON e convertê-los em AlertPolicy
e criar políticas a partir deles
usando o método alertPolicies.create
. Se você
tiver um arquivo de configuração JSON ou YAML do Prometheus com uma regra de alerta
a CLI gcloud pode migrá-los para um alerta do Cloud Monitoring
política com uma condição PromQL. Para mais informações, consulte
Migre regras e receptores de alertas do Prometheus.
Cada política de alertas pertence a um projeto de escopo de um escopo de métricas. Cada projeto pode conter até 500 políticas.
Para chamadas de API, é preciso fornecer um "ID do projeto". use o ID do projeto de escopo de um escopo de métricas como o valor. Nestes exemplos, o ID do projeto de escopo de um escopo de métricas é a-gcp-project
.
Os exemplos a seguir ilustram a criação de políticas de alertas, mas elas não descrevem como criar um arquivo JSON ou YAML que descreva uma política de alertas. Em vez disso, as amostras presumem que um arquivo formatado em JSON e ilustram como emitir a chamada de API. Para conferir exemplos de arquivos JSON, consulte Políticas de amostra. Para informações gerais sobre como monitorar proporções de métricas, consulte Proporções de métricas.
gcloud
Para criar uma política de alertas em um projeto, use o comando gcloud alpha monitoring
policies create
. O exemplo a seguir cria uma política de alertas em a-gcp-project
a partir do arquivo rising-cpu-usage.json
:
gcloud alpha monitoring policies create --policy-from-file="rising-cpu-usage.json"
Se bem-sucedido, este comando retornará o nome da nova política. Por exemplo:
Created alert policy [projects/a-gcp-project/alertPolicies/12669073143329903307].
O arquivo rising-cpu-usage.json
contém o JSON de uma política com
com o nome de exibição
"Alta taxa de mudança da CPU". Para mais detalhes sobre essa política, consulte
política de taxa de mudança.
Consulte a referência gcloud alpha monitoring policies create
para mais informações.
C#
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Go
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
PHP
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Monitoring, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
O objeto AlertPolicy
criado terá campos adicionais.
A própria política terá os campos name
, creationRecord
e mutationRecord
. Além disso, cada condição na política também recebe um name
.
Esses campos não podem ser modificados externamente. Dessa maneira, não é necessário configurá-los durante a criação de uma política. Nenhum dos exemplos JSON usados para criar políticas os inclui, mas, se as políticas criadas com base neles forem recuperadas depois da criação, os campos estarão presentes.
Configurar notificações repetidas para políticas de alertas baseadas em métricas
Por padrão, uma política de alertas baseada em métricas envia uma notificação para cada canal de notificação quando um incidente é aberto. No entanto, é possível alterar e configure uma política de alertas para reenviar as notificações a todos alguns dos canais de notificação para sua política de alertas. Essas notificações repetidas são enviadas para incidentes com status de "Aberto" ou "Confirmado". O intervalo entre essas notificações precisa ser de pelo menos 30 minutos e não mais de 24 horas, expresso em segundos.
Para configurar notificações repetidas, adicione à configuração da política de alertas
um objeto AlertStrategy
que contém pelo menos um
objeto NotificationChannelStrategy
.
Um objeto NotificationChannelStrategy
tem dois campos:
renotifyInterval
: o intervalo, em segundos, entre intervalos notificações.Se você mudar o valor do campo
renotifyInterval
ao um incidente da política de alertas for aberto, acontecerá o seguinte:- A política de alertas envia outro do incidente.
- A política de alertas reinicia o período do intervalo.
notificationChannelNames
: uma matriz de nomes de recursos de canal de notificação, que são strings no formato deprojects/PROJECT_ID/notificationChannels/CHANNEL_ID
, em que CHANNEL_ID é um valor numérico. Para informações sobre como recuperar o ID do canal, consulte Listar canais de notificação em um projeto
Por exemplo, o exemplo de JSON a seguir mostra uma estratégia de alerta configurada para enviar notificações repetidas a cada 1.800 segundos (30 minutos) para um canal de notificação:
"alertStrategy": { "notificationChannelStrategy": [ { "notificationChannelNames": [ "projects/PROJECT_ID/notificationChannels/CHANNEL_ID" ], "renotifyInterval": "1800s" } ] }
Para interromper temporariamente as notificações repetidas, crie um adiamento. Para
evitar notificações repetidas, editar a política de alertas usando a API e
remova o objeto NotificationChannelStrategy
.