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 políticas de alertas.
- Como criar uma política de alertas usando a Google Cloud CLI 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 este campo para fornecer informações que ajudem os responsáveis pela resposta a incidentes. Para mais informações, consulte Anotar notificações com a documentação definida pelo usuário.userLabels
: qualquer rótulo definido pelo usuário anexado à política. Para informações sobre como usar rótulos com alertas, consulte Anotar incidentes com rótulos.conditions[]
: uma matriz de estruturasCondition
.combiner
: um operador lógico que determina como lidar com várias condições.notificationChannels[]
: uma matriz de nomes de recursos, cada um identificando umNotificationChannel
.alertStrategy
: especifica a rapidez com que o Monitoring fecha incidentes quando os dados param de chegar. Esse objeto também especifica se as 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. Com esse campo, é possível 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 quando essa condição é atendida. Para informações sobre notificações quando as políticas de alertas contiverem 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 métricas com base em registros, use 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 da condição 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 será atendida somente quando todas as série temporal estiverem ausentes. Essa condição usa o parâmetro aggregations
para agregar várias séries temporais em uma única série temporal. Para mais informações, consulte a referência MetricAbsence
na documentação da API.
Uma política de alertas 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étricas.
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 esse campo não é definido, os dados medidos são comparados com um limite.
No entanto, quando este campo é definido, os dados previstos são comparados com um limite. Para mais informações, consulte Criar políticas de alertas de valores de métricas previstas.
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 consultas da linguagem de consulta do Prometheus (PromQL, na sigla em inglês)
para selecionar e manipular dados de série temporal a serem monitorados.
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
condição na política de alertas. Para mais informações, consulte Políticas de alertas com 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 de métricas diferentes está sujeita a anomalias devido a períodos de amostragem diferentes e janelas de alinhamento.
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, usando uma janela de alinhamento maior que o período de amostragem ou agrupando dados de determinados 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
com métricas com base em registros. As políticas de alertas que monitoram métricas com base em registros são políticas com base em métricas. Para mais informações sobre como escolher entre políticas de alertas que monitoram métricas com base em registros ou entradas de registro, consulte Como monitorar seus registros.
As políticas de alertas usadas nos exemplos do documento Gerenciar políticas de alertas por API são políticas de alertas com base em métricas, embora os princípios sejam os mesmos para 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 terminologia usados com políticas de alertas. 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 das linguagens que quer usar. Consulte Bibliotecas de cliente para mais 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ê usa o Cloud Shell, a Google Cloud CLI já está instalada.
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 receber 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ê o papel do IAM Editor de AlertPolicy do Monitoring (
roles/monitoring.alertPolicyEditor
) no projeto. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.Também é possível receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.
Para informações detalhadas sobre os papéis do IAM para o Monitoring, consulte Controlar o acesso com o Identity and Access Management.
Projete seu aplicativo para chamadas da API Cloud Monitoring de linha de execução única que modificam o estado de uma política de alertas em um projeto do Google Cloud. Por exemplo, chamadas de API de linha de execução ú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 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, e é possível ler arquivos JSON programaticamente, convertê-los em objetos AlertPolicy
e criar políticas com base neles 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 poderá migrá-lo para uma política de alertas do Cloud Monitoring
com uma condição do PromQL. Para mais informações, consulte
Migrar regras de alerta e receptores 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 não descrevem como criar um arquivo JSON ou YAML que descreva uma política de alertas. Em vez disso, os exemplos pressupõem que existe um arquivo no formato JSON e ilustram como emitir a chamada de API. Para ver exemplos de arquivos JSON, consulte Políticas de amostra. Para informações gerais sobre proporções de monitoramento 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 o nome de exibição "Alta taxa de alteração 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 com base em métricas
Por padrão, uma política de alertas com base em métricas envia uma notificação para cada canal de notificação quando um incidente é aberto. No entanto, é possível alterar o comportamento padrão e configurar uma política de alertas para reenviar notificações a todos ou alguns dos canais de notificação da política. Essas notificações repetidas são enviadas para incidentes com status "Aberto" ou "Reconhecido". O intervalo entre essas notificações precisa ser de, no mínimo, 30 minutos e não superior a 24 horas, expresso em segundos.
Para configurar notificações repetidas, adicione à configuração da política de alertas um objeto AlertStrategy
que contenha pelo menos um objeto NotificationChannelStrategy
.
Um objeto NotificationChannelStrategy
tem dois campos:
renotifyInterval
: o intervalo, em segundos, entre notificações repetidas.Se você alterar o valor do campo
renotifyInterval
quando um incidente da política de alertas for aberto, acontecerá o seguinte:- A política de alertas envia outra notificação sobre o incidente.
- A política de alertas reinicia o período de intervalo.
notificationChannelNames
: uma matriz de nomes de recursos do canal de notificação, que são strings no formatoprojects/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 JSON a seguir mostra uma estratégia de alertas configurada para enviar notificações repetidas a cada 1.800 segundos (30 minutos) a 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, edite a política de alertas usando a API e remova o objeto NotificationChannelStrategy
.