Alertas do Google Cloud Monitoring por ligação via webhook

O Cloud Monitoring manda e-mail, SMS e push, mas não liga. Envie as políticas de alertas do GCP a um webhook de ligação: configuração, campos e filtros.

Atualizado

Sumário

O Google Cloud Monitoring não consegue ligar para o seu telefone. Os canais de notificação dele são e-mail, SMS, o app para dispositivos móveis do Google Cloud, Slack, Google Chat, PagerDuty, Pub/Sub e webhooks — e a própria documentação do Google avisa que o SMS não é totalmente confiável e pode não estar disponível na sua região. Se você quer que uma política de alertas toque como uma chamada recebida, o caminho mais curto é um canal de webhook apontado para um canal de ligação do Echobell, com duas linhas de template e uma condição.

Este guia cobre o canal, o webhook, os campos que o Cloud Monitoring realmente envia no payload, como fazer os incidentes "open" tocarem e os "closed" ficarem quietos, e as configurações da política de alertas que decidem com que frequência o seu telefone toca.

Por que os canais nativos não bastam às 3 da manhã

  • O e-mail espera você olhar.
  • O SMS, nas palavras do Google, não é um tipo de canal totalmente confiável, e pode não ser oferecido no seu país. Além disso, o Não Perturbe silencia o SMS como qualquer outra mensagem.
  • O app para dispositivos móveis envia um push comum. Ele aparece na tela bloqueada; não fica tocando.
  • O PagerDuty consegue ligar para você, mas é uma plataforma de plantão completa, com configuração e contrato próprios.

Um canal de webhook, por outro lado, alcança qualquer coisa com um endpoint HTTPS público, e o Cloud Monitoring envia a ele um documento JSON estruturado para cada incidente. É tudo de que o Echobell precisa.

O que você precisa

  • Um projeto do Google Cloud com pelo menos uma política de alertas (ou uma verificação de tempo de atividade sobre a qual você quer ser alertado)
  • Permissão para editar canais de notificação (roles/monitoring.notificationChannelEditor ou Monitoring Editor)
  • Echobell instalado (App Store / Google Play)
  • Dez minutos

Nada no seu projeto precisa aceitar tráfego de entrada. Quem faz a requisição de saída é o Cloud Monitoring.

Passo 1 — Crie um canal que toca

No Echobell, crie um canal e defina o tipo de notificação como Ligação. Um canal de ligação se comporta como uma chamada recebida em vez de um push, então ocupa a tela e toca. Com o modo Foco ou o Não Perturbe do iOS ativado, ele só toca se as suas configurações de Foco permitirem chamadas.

Abra as Configurações avançadas do canal e ative Modelo personalizado. O Cloud Monitoring embrulha tudo num objeto incident, então os templates leem campos aninhados:

Título: {{incident.state}}: {{incident.policy_name}}
Corpo: {{incident.summary}}

Defina o template de link para que tocar na notificação abra o incidente no console do Google Cloud:

{{incident.url}}

Adicione uma condição para que só os incidentes recém-abertos toquem:

incident.state == "open"

Copie a URL do webhook do canal na tela de detalhes:

https://hook.echobell.one/t/<channel-token>

Passo 2 — Adicione um canal de notificação de webhook no Google Cloud

  1. Abra Monitoring → Alerting e clique em Edit notification channels
  2. Em Webhooks, clique em Add new
  3. Endpoint URL: a URL do seu canal do Echobell do passo 1
  4. Display name: Echobell (call)
  5. Deixe Use HTTP Basic Auth desativado
  6. Clique em Test connection e depois em Save

Deixe o Basic Auth desativado de propósito. O handshake de Basic Auth do Google espera que o endpoint responda à primeira requisição com um 401 e um cabeçalho WWW-Authenticate; o Echobell, em vez disso, autentica pelo token secreto da URL, então trate essa URL como uma senha.

Se você gerencia os canais com Terraform, o mesmo canal fica assim:

resource "google_monitoring_notification_channel" "echobell_call" {
  display_name = "Echobell (call)"
  type         = "webhook_tokenauth"

  labels = {
    url = "https://hook.echobell.one/t/<channel-token>"
  }
}

Mantenha o token fora do controle de versão: leia-o de uma variável ou do Secret Manager em vez de commitar a URL.

Passo 3 — Vincule o canal às políticas que merecem uma ligação

Abra uma política de alertas, vá até Notifications and name e adicione Echobell (call) em Notification channels. Uma política pode notificar vários canais ao mesmo tempo, então mantenha o seu canal de e-mail ou de Slack ao lado.

Seja exigente aqui. Este é o filtro de verdade: um canal vinculado só a "a API de produção caiu" e "o banco de dados ficou sem disco" toca raramente o bastante para você continuar atendendo. Deixe "CPU acima de 70% por cinco minutos" no e-mail.

Duas configurações na mesma página definem o que chega ao seu telefone:

  • Notify on incident closure. Com ela ativada, o Cloud Monitoring também envia uma notificação quando o incidente é fechado. A condição incident.state == "open" do passo 1 impede que essa toque; o passo 6 mostra como recebê-la em silêncio.
  • Incident autoclose duration. Se a métrica parar de enviar dados, os incidentes abertos são fechados depois desse período. Deixe o valor padrão, a menos que tenha um motivo para mudar.

Passo 4 — Saiba como o payload é de verdade

O Cloud Monitoring envia por padrão a versão 1.2 do esquema. Reduzido aos campos que você provavelmente vai usar, um incidente aberto fica assim:

{
  "version": "1.2",
  "incident": {
    "incident_id": "0.opqiw61fsv7p",
    "scoping_project_id": "my-project",
    "url": "https://console.cloud.google.com/monitoring/alerting/incidents/0.opqiw61fsv7p?project=my-project",
    "state": "open",
    "renotify": false,
    "started_at": 1794713564,
    "ended_at": null,
    "policy_name": "Prod API 5xx rate",
    "condition_name": "5xx ratio above 5%",
    "resource_display_name": "prod-api",
    "threshold_value": "0.05",
    "observed_value": "0.183",
    "severity": "Critical",
    "policy_user_labels": {
      "team": "payments"
    },
    "documentation": {
      "content": "Check the latest deploy first. Runbook: https://wiki.example.com/api-5xx",
      "mime_type": "text/markdown"
    },
    "summary": "5xx ratio for prod-api with metric labels {response_code_class=500} is above the threshold of 0.050 with a value of 0.183."
  }
}

O que vale saber antes de editar um template:

  • Tudo fica dentro de incident. {{policy_name}} sai vazio; {{incident.policy_name}}, não.
  • state é open ou closed. É desse único campo que dependem a condição e o template de título.
  • summary é texto gerado. O Google não garante um formato estável, então exiba-o, mas não compare com ele numa condição.
  • Campos podem faltar. O Google observa que alguns campos ficam ausentes ou null dependendo da política e do estado do incidente. No Echobell, um campo ausente é renderizado como string vazia, então o template continua funcionando; só não monte uma condição sobre um campo que as suas políticas não preenchem.
  • documentation.content é seu. O que você digitar na caixa Documentation da política chega aqui. Uma instrução de uma linha ("Verifique primeiro o último deploy") é mais útil num telefone tocando do que o resumo gerado.
  • A gravidade segue a política. É o nível que você definiu na política. Mande para si mesmo um incidente de teste e confira o valor exato antes de filtrar por ele.

Um corpo que começa com as suas próprias palavras e recorre ao resumo:

{{incident.documentation.content}}
{{incident.summary}}

Passo 5 — Decida o que toca e com que frequência

A maior parte da filtragem já aconteceu quando você escolheu quais políticas recebem o canal. A condição do canal do Echobell cuida do resto.

ObjetivoCondição
Tocar só quando um incidente abreincident.state == "open"
Tocar uma vez, não a cada lembreteincident.state == "open" && !incident.renotify
Tocar só para as políticas de um timeincident.state == "open" && incident.policy_user_labels.team == "payments"
Tocar só de madrugada (00:00–07:00 UTC)incident.state == "open" && hour < 7

Lembretes. Uma política pode reenviar notificações enquanto o incidente continuar aberto: na API é alertStrategy.notificationChannelStrategy[].renotifyInterval, de 30 minutos a 24 horas. Essas repetições chegam com renotify: true. Se elas devem tocar é uma escolha: tocar de novo é um escalonamento rudimentar, mas eficaz, para um incidente que ninguém resolveu, e pulá-las evita que uma interrupção longa toque a noite inteira. A segunda linha da tabela faz esse pulo.

Rótulos de usuário. Os rótulos de usuário da política, como team: payments, vêm em policy_user_labels. Uma condição sobre eles faz um canal vinculado a muitas políticas tocar para algumas e ficar quieto para as demais. Eles filtram, não roteiam: cada URL de webhook sempre aciona o mesmo canal do Echobell, então um rótulo não consegue mandar um incidente para o canal de outra pessoa.

As variáveis de hora do Echobell são em UTC, então converta do seu fuso primeiro. A referência de condições lista todas as variáveis.

Passo 6 — Dê aos fechamentos uma porta mais silenciosa

Com Notify on incident closure ativado, um incidente fechado é uma boa notícia que vale ver, mas não vale um toque. Crie um segundo canal do Echobell do tipo Urgente (Time Sensitive) (ou normal) com os mesmos templates e sem condição, adicione-o no Google Cloud como um segundo canal de webhook e vincule os dois à política. O template de título já se lê como "closed: Prod API 5xx rate".

Canal do EchobellCondiçãoTipo de canalComportamento
gcp-callincident.state == "open"LigaçãoToca como uma chamada recebida
gcp-lognenhumaUrgente ou NormalCada abertura, lembrete e fechamento, sem tocar

Teste antes de confiar

Teste primeiro o lado do Echobell. Envie um payload no formato do Cloud Monitoring:

curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H 'Content-Type: application/json' \
  -d '{"version":"1.2","incident":{"state":"open","renotify":false,"policy_name":"Manual test","summary":"Testing the Echobell path","url":"https://console.cloud.google.com/monitoring/alerting"}}'

Depois teste o lado do Google. O botão Test connection envia um payload de exemplo cujos campos não são de um incidente real, então ele pode não passar na sua condição. Para um teste de ponta a ponta, crie uma política descartável com um limite que você já ultrapassa — por exemplo, utilização de CPU da VM acima de 1% —, vincule Echobell (call), espere disparar e depois exclua a política.

Se o curl toca e a política real não, o problema está do lado do Google — o canal não está vinculado, a condição ainda não foi atendida pela duração definida ou a URL do endpoint foi copiada errada —, não no canal do Echobell.

Alertas baseados em registros e verificações de tempo de atividade

  • As verificações de tempo de atividade não notificam ninguém sozinhas; elas alimentam uma política de alertas. Crie a política a partir da verificação e vincule o mesmo canal de webhook.
  • As políticas de alertas baseadas em registros só notificam quando um incidente abre — o Google não envia notificação de fechamento para elas — e exigem um limite de taxa de notificações, que restringe com que frequência uma linha de log barulhenta pode fazer você tocar. A condição incident.state == "open" continua funcionando; o canal de fechamentos simplesmente nunca recebe nada dessas políticas.

Limites que importam durante um incidente

  • Corpo de 1 MiB. O Echobell rejeita com HTTP 413 corpos de gatilho acima de 1 MiB. Um incidente do Cloud Monitoring tem poucos kilobytes.
  • 120 requisições por minuto por token. Acima disso, o gatilho responde 429 com RATE_LIMIT_EXCEEDED e um Retry-After. Uma única política raramente chega perto, mas dezenas de políticas disparando ao mesmo tempo durante uma interrupção regional podem chegar — mais um motivo para manter curta a lista do canal de ligação.
  • 1500 bytes de corpo de notificação. Renderizações mais longas são truncadas. Mantenha a documentação da política curta, ou coloque nela o link para o runbook em vez do runbook inteiro.

O que essa configuração não oferece

  • Sem reconhecimento. Atender a ligação não reconhece nem fecha o incidente no Google Cloud.
  • Sem escalonamento nem rodízio. Todos os inscritos no canal recebem a ligação; ninguém é chamado depois.
  • Sem deduplicação além do incidente. Uma condição instável abre um incidente novo a cada vez, e cada um toca. Resolva na política com uma janela de duração mais longa.

Se isso for inaceitável, você precisa de uma plataforma de plantão completa. Se o que você precisa é "me liga quando a política de produção disparar", são duas telas no console.

Solução de problemas

O incidente abriu mas nada chegou. Abra o incidente em Monitoring → Alerting e confira se a política lista o canal de webhook. Garanta que a URL do endpoint é a URL completa do Echobell, com o token.

A notificação chegou mas não tocou. O tipo de canal não é Ligação, ou as configurações de Foco do seu telefone não deixam as chamadas passarem. Verifique o canal e a sua configuração de Foco.

A notificação está em branco. O template está lendo campos de nível superior. Adicione o prefixo incident. — {{incident.policy_name}}, não {{policy_name}}.

Toca de novo a cada meia hora. A política tem um intervalo de renotificação. Remova-o, ou adicione !incident.renotify à condição.

Toca quando o incidente fecha. Falta incident.state == "open" na condição, ou ela está no canal errado.

Perguntas frequentes

O Google Cloud Monitoring consegue ligar para um número de telefone nativamente?

Não. Os canais de notificação são e-mail, SMS, o app para dispositivos móveis do Google Cloud, Slack, Google Chat, PagerDuty, Pub/Sub e webhooks. Uma chamada de voz exige um serviço externo: uma plataforma de plantão ou um webhook de ligação como o Echobell.

Preciso de Pub/Sub ou de uma Cloud Function?

Não. O próprio Cloud Monitoring envia o incidente para a URL do webhook. O Pub/Sub é a recomendação do Google para endpoints que não são públicos; o endpoint do Echobell é público, então o canal de webhook basta.

Um alerta do Cloud Monitoring atravessa o Não Perturbe?

Só se chegar como alerta em formato de ligação. Um canal do Echobell do tipo ligação se comporta como uma chamada recebida, e isso o modo Foco e o Não Perturbe do iOS deixam passar quando as suas configurações de Foco permitem chamadas. Um SMS ou um push comum, não. Ative também Repetir chamada com falha: com “Permitir Ligações Repetidas” ativado nas configurações de Foco, uma segunda chamada em até três minutos pode tocar.

Devo usar a opção Basic Auth no webhook?

Não. O Echobell autentica pelo token da URL. O fluxo de Basic Auth do Google espera primeiro um desafio 401, que o Echobell não envia.

Posso ligar para pessoas diferentes conforme a política?

Sim. Crie um canal do Echobell por público, adicione a URL de cada canal ao Google Cloud como um canal de webhook próprio e vincule cada um às políticas pelas quais aquele público responde. Uma URL de webhook sempre aciona o mesmo canal do Echobell, então uma condição com policy_user_labels pode silenciar políticas nesse canal, mas não passá-las para outro. Não há reconhecimento, então todos os inscritos com "ligação" recebem a chamada.

E com vários projetos?

Um canal de notificação pertence a um único projeto. Crie o canal de webhook em cada projeto — a mesma URL do Echobell funciona em todos — ou alerte a partir de um projeto de escopo que monitore os outros.

Fechando

O caminho tem quatro partes: um canal de ligação com a condição incident.state == "open", um canal de notificação de webhook apontado para ele, uma lista curta de políticas que merecem uma ligação e um teste real antes de confiar. O resto é manter essa lista curta o bastante para que, daqui a um mês, o toque ainda signifique alguma coisa.

Baixe o Echobell para iPhone ou pegue no Google Play e depois aponte para ele a sua política de alertas mais importante.

Artigos relacionados