Sumário
- Por que os canais nativos não bastam às 3 da manhã
- O que você precisa
- Passo 1 — Crie um canal que toca
- Passo 2 — Adicione um canal de notificação de webhook no Google Cloud
- Passo 3 — Vincule o canal às políticas que merecem uma ligação
- Passo 4 — Saiba como o payload é de verdade
- Passo 5 — Decida o que toca e com que frequência
- Passo 6 — Dê aos fechamentos uma porta mais silenciosa
- Teste antes de confiar
- Alertas baseados em registros e verificações de tempo de atividade
- Limites que importam durante um incidente
- O que essa configuração não oferece
- Solução de problemas
- Perguntas frequentes
- O Google Cloud Monitoring consegue ligar para um número de telefone nativamente?
- Preciso de Pub/Sub ou de uma Cloud Function?
- Um alerta do Cloud Monitoring atravessa o Não Perturbe?
- Devo usar a opção Basic Auth no webhook?
- Posso ligar para pessoas diferentes conforme a política?
- E com vários projetos?
- Fechando
- Artigos relacionados
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.notificationChannelEditorou 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
- Abra Monitoring → Alerting e clique em Edit notification channels
- Em Webhooks, clique em Add new
- Endpoint URL: a URL do seu canal do Echobell do passo 1
- Display name:
Echobell (call) - Deixe Use HTTP Basic Auth desativado
- 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éopenouclosed. É 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.
| Objetivo | Condição |
|---|---|
| Tocar só quando um incidente abre | incident.state == "open" |
| Tocar uma vez, não a cada lembrete | incident.state == "open" && !incident.renotify |
| Tocar só para as políticas de um time | incident.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 Echobell | Condição | Tipo de canal | Comportamento |
|---|---|---|---|
gcp-call | incident.state == "open" | Ligação | Toca como uma chamada recebida |
gcp-log | nenhuma | Urgente ou Normal | Cada 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
429comRATE_LIMIT_EXCEEDEDe umRetry-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.