Este documento ilustra como usar a API Cloud Monitoring para criar, editar, excluir, listar e receber políticas de alertas com base em métricas de maneira programática. Os exemplos mostram como usar a Google Cloud CLI e as bibliotecas de cliente. Este conteúdo não se aplica a políticas de alertas baseadas em registros. Para saber mais sobre políticas de alertas com base em registros, consulte Como monitorar seus registros.
Essas tarefas também podem ser realizadas usando o console do Google Cloud. para mais informações, consulte os seguintes documentos:
- Criar políticas de alertas de limite de métrica usando o console do Google Cloud
- Gerenciar políticas de alertas usando o console do Google Cloud
Sobre políticas de alertas
Uma política de alertas é representada por um objeto AlertPolicy
, que descreve um conjunto de condições que indicam um status potencialmente não íntegro em seu sistema. As políticas de alertas referenciam canais de notificação, que permitem especificar como você quer ser informado de que uma política de alertas foi acionada.
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
.
O recurso AlertPolicy
suporta cinco operações:
- criação de novas políticas
- exclusão de políticas existentes
- recuperação de políticas específicas
- recuperação de todas as políticas
- modificação de políticas existentes
As políticas de alertas podem ser expressas em JSON ou YAML, o que permite gravar políticas em arquivos e usar arquivos para fazer backup e restaurar políticas. Com a CLI do Google Cloud, você pode criar políticas com base em arquivos de qualquer formato. Com a API REST, você pode criar políticas com base em arquivos JSON. Consulte Políticas de amostra para uma seleção de políticas de alertas em formato JSON.
Os exemplos a seguir usam a interface gcloud
e a API para ilustrar esses casos de uso básicos. As amostras de API são extraídas de um programa de amostra que usa a API para implementar um sistema de backup e restauração para políticas de alertas. As amostras mais completas são mostradas em Exemplo: backup e restauração.
Antes de começar
Para escrever código na API, você precisa cumprir estes requisitos:
- Ter familiaridade com os conceitos gerais e a terminologia usados com alertas policies; consulte Visão geral de alertas para mais informações imprecisas ou inadequadas.
- 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 a idiomas que você quer usar. ver Bibliotecas de cliente para mais detalhes. Atualmente, a API é compatível com alertas somente em C#, Go, Java, Node.js e Python.
Se você pretende usar a CLI do Google Cloud, 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 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ê o papel do IAM de Editor de políticas de alertas do Monitoring (
roles/monitoring.alertPolicyEditor
) no seu 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 os papéis do IAM para o Monitoring, consulte Controle de acesso com o gerenciamento de identidade e acesso.
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 do gcloud poderá migrá-lo para uma política de alerta do Cloud Monitoring
com uma condição do PromQL. Para mais informações, consulte
Migre regras e receptores de alertas do Prometheus.
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, os exemplos presumem que um arquivo formatado em JSON existe e ilustram como emitir a chamada de API. Para conferir exemplos de arquivos JSON, consulte Políticas de amostra. Para informações gerais sobre o monitoramento de taxas de métricas, consulte Taxas 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 para uma política com o nome de exibição "Taxa alta de alteração da CPU". Para saber mais sobre essa política, consulte Política de alteração de taxas.
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.
Listar e receber políticas de alertas
Para recuperar uma lista das políticas em um projeto, use o método alertPolicies.list
.
Use esse método para recuperar políticas e aplicar uma ação a cada uma delas, por exemplo, fazendo backup delas. Esse método também suporta as opções filter
e orderBy
para restringir e classificar os resultados. Consulte Classificação e filtragem.
Se você estiver procurando uma política específica e souber o nome dela, use o método alertPolicies.get
para recuperar apenas essa política. O nome de uma política é o valor do campo name
, não o displayName
, no objeto AlertPolicy
. O nome de uma política tem o formato projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]
, por exemplo:
projects/a-gcp-project/alertPolicies/12669073143329903307
gcloud
Para listar todas as políticas de alertas em um projeto, use o comando gcloud alpha monitoring
policies list
:
gcloud alpha monitoring policies list
Se for bem-sucedido, o comando list
fornecerá uma lista de todas as políticas no projeto especificado, formatadas como YAML. Por exemplo, a
política com o nome de exibição "Alta taxa de mudança de CPU"
no projeto a-gcp-project
é listada desta forma,
entre as outras políticas listadas:
---
combiner: OR
conditions:
- conditionThreshold:
aggregations:
- alignmentPeriod: 900s
perSeriesAligner: ALIGN_PERCENT_CHANGE
comparison: COMPARISON_GT
duration: 180s
filter: metric.type="compute.googleapis.com/instance/cpu/utilization" AND resource.type="gce_instance"
thresholdValue: 0.5
trigger:
count: 1
displayName: CPU usage is increasing at a high rate
name: projects/a-gcp-project/alertPolicies/12669073143329903307/conditions/12669073143329903008
creationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
displayName: High CPU rate of change
enabled: true
mutationRecord:
mutateTime: '2018-03-26T18:52:39.363601689Z'
mutatedBy: [USER@DOMAIN]
name: projects/a-gcp-project/alertPolicies/12669073143329903307
---
Para listar uma única política de alertas, use gcloud alpha monitoring policies
describe
no lugar e especifique o nome da política. Por exemplo, este comando retorna apenas a listagem acima:
gcloud alpha monitoring policies describe projects/a-gcp-project/alertPolicies/12669073143329903307
Consulte as referências gcloud alpha monitoring policies list
e describe
para mais informações. O comando describe
corresponde ao método alertPolicies.get
na API.
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.
Excluir uma política de alertas
Para excluir uma política de um projeto, use o método alertPolicies.delete
e forneça o nome da política de alertas a ser excluída.
gcloud
Para excluir uma política de alertas, use gcloud alpha monitoring policies
delete
e especifique o nome da política a ser excluída. Por exemplo, o
comando a seguir exclui o
política com o nome de exibição "Alta taxa de mudança de CPU":
gcloud alpha monitoring policies delete projects/a-gcp-project/alertPolicies/12669073143329903307
Consulte a referência gcloud alpha monitoring policies delete
para mais informações.
Modificar uma política de alertas
Para modificar uma política de alertas, use o método alertPolicies.patch
(na API REST).
Outras implementações de API e a interface gcloud
chamam este update
em vez de patch
.
Uma operação de atualização pode substituir toda a política existente ou modificar um subconjunto de campos. Uma operação de atualização leva um novo objeto AlertPolicy
e uma máscara de campo opcional.
Se uma máscara de campo for especificada, todos os campos listados na máscara de campo serão atualizados com o valor na política fornecida. Se a política fornecida não incluir um campo mencionado na máscara de campo, esse campo será apagado e definido como o valor padrão dele. Qualquer campo não listado na máscara mantém o valor anterior dele.
Se nenhuma máscara de campo for especificada, a política existente será substituída pela fornecida, mas o nome (projects/[PROJECT_ID]/alertPolicies/[POLICY_ID]
) será reutilizado. Todas as condições na nova política que tiverem valores name
que incluam um CONDITION_ID
manterão esses nomes. Do contrário, novos nomes de condição e política são criados.
Ao usar a linha de comando gcloud
para atualizar políticas, serão usadas as sinalizações de linha de comando, e não uma máscara de campo, para especificar os campos a serem atualizados.
Consulte gcloud alpha monitoring policies update
para detalhes.
Ativar ou desativar uma política de alertas
Para ativar ou desativar uma política, altere o valor do campo booleano enabled
no objeto AlertPolicy
. Depois que você ativar uma política, ela ainda poderá ser acionada por dados coletados enquanto estiver desativada.
gcloud
Para desativar uma política de alertas, use o comando gcloud alpha monitoring policies update
e forneça a sinalização --no-enabled
. O comando a seguir desativa a política de alertas de "Alta taxa de alteração da CPU" no projeto a-gcp-project
:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 --no-enabled
Para ativar a política, use o mesmo comando e forneça a sinalização --enabled
.
Consulte a referência gcloud alpha monitoring policies update
para mais informações. O comando update
corresponde ao método alertPolicies.patch
na API REST.
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.
Atualizar canais de notificação em uma política de alertas
Também é possível atualizar os canais de notificação referenciados por uma política de alertas. As políticas de alertas se referem a canais de notificação por nome. Os canais precisam existir para serem usados em uma política de alertas.
Crie e gerencie canais de notificação programaticamente usando os recursos NotificationChannel
e NotificationChannelDescriptors
.
Nos exemplos desta seção, supomos que esses canais já existam, e os usos dessas APIs também são exibidos nas amostras programáticas.
Para mais discussão dos objetos do canal de notificação, consulte Criar e gerenciar canais de notificação por API.
gcloud
Para modificar os canais de notificação em uma política de alertas, use o comando gcloud alpha monitoring policies update
. Há várias sinalizações relacionadas aos canais de notificação, permitindo remover canais de notificação, substituir canais de notificação e adicionar novos canais de notificação.
Por exemplo, a política com o nome de exibição "Alta taxa de mudança de CPU" no projeto a-gcp-project foi criada sem canais de notificação.
Para adicionar um canal de notificação a esta política, use o comando gcloud alpha monitoring
policies update
e especifique o canal a ser adicionado com a sinalização --add-notification-channels
:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--add-notification-channels="projects/a-gcp-project/notificationChannels/1355376463305411567"
Consulte a referência gcloud alpha monitoring policies update
para mais informações. O comando update
corresponde ao método alertPolicies.patch
na API REST.
O canal de notificação adicionado aqui já precisa existir. Consulte Criar um canal de notificação 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.
Modificar a documentação em uma política de alertas
Uma política pode apresentar documentação com incidentes e notificações associados à política. Use esse campo a fim de incluir informações para ajudar os responsáveis pela resposta a entender e processar o problema indicado pela política de alertas. A documentação está incluída em notificações por e-mail e tipos de notificação que permitam isso. Outros tipos de canal podem omiti-la.
gcloud
Para adicionar documentação a uma política ou substituir a documentação existente, use o comandogcloud alpha monitoring policies update
e forneça a
sinalização --documentation-format="text/markdown"
(o único formato aceito)
e a sinalização --documentation
(para inserir o valor da linha de comando)
ou a sinalização --documentation-from-file
(para ler o valor de um arquivo).
Por exemplo, a política com o nome de exibição "Alta taxa de mudança de CPU" no projeto a-gcp-project foi criada sem documentação.
O comando a seguir define o campo documentation
na política especificada para o conteúdo do arquivo cpu-usage-doc.md
:
gcloud alpha monitoring policies update projects/a-gcp-project/alertPolicies/12669073143329903307 \
--documentation-format="text/markdown" \
--documentation-from-file="cpu-usage-doc.md"
Consulte a referência gcloud alpha monitoring policies update
para mais informações. O comando update
corresponde ao método alertPolicies.patch
na API REST.
Adicionar uma política de alertas a um painel
Para exibir um resumo de uma política de alertas de condição única no painel personalizado, adicione um widget AlertChart
ao painel.
Use o método
dashboards.create
para um novo painel e o método
dashboards.patch
para um painel existente.
Se você especificar uma política de alertas de várias condições,
o widget AlertChart
não vai mostrar dados.
Para informações detalhadas sobre como usar esses métodos de API, consulte Criar e gerenciar painéis por API.
Exemplo: backup e restauração
Todos os exemplos da API mostrados são extraídos de um aplicativo maior que pode fazer backup das políticas de alerta em um projeto para um arquivo e pode restaurar as políticas, possivelmente para outro projeto. Se os projetos usados em backup e restauração forem diferentes, o aplicativo exportará e importará efetivamente políticas de um projeto para outro.
Esta seção mostra o código para backup e restauração no contexto, e não como um conjunto de pequenos trechos isolados.
Como fazer backup de políticas
A operação de backup é simples. O conjunto de políticas de alertas e o conjunto de canais de notificação em cada projeto são coletados e salvos no armazenamento externo em JSON.
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.
Como restaurar as políticas em backup
O processo de restauração é mais complexo que o backup original. Você pode restaurar o backup original do projeto. Também é possível restaurar para um projeto diferente, fornecendo efetivamente a importação das políticas de alertas.
Em caso de restauração do mesmo projeto, todos os canais ou as políticas existentes serão atualizados, se ainda existirem. Se não tiverem, serão recriados. Os campos somente leitura como os registros de criação e mutação nas políticas de backup são apagados pelo processo de restauração antes que políticas e notificações sejam recriadas.
É possível usar uma política salva em um projeto para criar uma nova ou semelhante em outro projeto. No entanto, você precisa primeiro fazer as seguintes alterações em uma cópia da política salva:
- Remova os campos a seguir de todos os canais de notificação:
name
verificationStatus
- Crie canais de notificação antes de consultar os canais nas políticas de alertas. São necessários os novos identificadores de canal.
- Remova os campos a seguir de todas as políticas de alertas que você estiver recriando:
name
condition.name
creationRecord
mutationRecord
Se a política estiver sendo recriada em um novo projeto, os nomes de quaisquer condições nas políticas armazenadas em backup serão apagados, além dos registros de criação e mutação.
Quando é recriado em um projeto distinto, um canal de notificação recebe um nome diferente. Assim, o processo de restauração precisa mapear os nomes de canais em políticas de alertas armazenadas em backup para os novos nomes deles e substituir os nomes anteriores pelos novos.
Além dos nomes dos canais de notificação, o valor do
campo verificationStatus
não pode ser definido quando o canal é criado
ou atualizado, então, um valor de sentinela, unspecified
, é usado. Depois que tiverem sido restaurados em um novo projeto, os canais precisarão ser verificados explicitamente.
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.
Alertas e Google Cloud CLI
Na CLI do Google Cloud, o grupo de comandos para gerenciar políticas de alertas e
canais de notificação é monitoring
, que está na versão Alfa.
O grupo monitoring
está disponível no componente alpha
.
Ou seja, todos esses comandos começarão com:
gcloud alpha monitoring
Para verificar se você tem o componente alpha
instalado, execute este comando:
gcloud components list
Se você não tiver o componente alpha
instalado, execute este comando para instalá-lo:
gcloud components install alpha
Se você tiver o componente alpha
, verifique o grupo monitoring
executando este comando:
gcloud alpha monitoring --help
Se o grupo monitoring
não estiver incluído, a CLI do Google Cloud vai solicitar que você o
adicione:
You do not currently have this command group installed.
[...]
Do you want to continue (Y/n)? y