Alertas do Sentry no celular: notificações push para erros, sem código

O Sentry captura a exceção no momento em que ela acontece. Depois ele manda um e-mail para você, ou posta em um canal do Slack que também recebe mensagens de deploy, lembretes de standup e algumas centenas de outras coisas. Se o erro acontecer às 2 da manhã ou enquanto você está longe do notebook, você só descobre quando um usuário avisa.
Os alertas do Sentry podem fazer melhor que isso, mas o Sentry não tem um app push próprio para alertas. O que ele tem é um webhook que dispara quando uma regra de alerta é atendida. Aponte o webhook para o Pocket Alert e cada alerta vira uma notificação push no seu celular, com o título do erro, o culpado e um botão que abre a issue. Sem servidor, sem código.
O que você precisa
- Uma organização no Sentry em que você tenha permissão para criar integrações e alertas.
- Uma conta no Pocket Alert com o app instalado no seu celular iPhone ou Android. O plano gratuito inclui um webhook, que é tudo o que essa configuração precisa.
- Uma chave de API em Chaves de API, se você quiser o botão "Open in Sentry" (mais sobre isso abaixo).
Como o Sentry envia alertas para um webhook
O Sentry tem dois jeitos de fazer POST de um alerta para uma URL, e eles enviam JSONs diferentes:
- Integração interna (recomendada pelo próprio Sentry). Você cria uma integração privada com uma URL de webhook e ativa o toggle Alert Action. Ela então aparece como uma ação nos seus alertas. Alertas de issues chegam com o header
Sentry-Hook-Resource: event_alerte o erro emdata.event; alertas de issues vindos de Metric Monitors chegam comometric_alert, com um título pronto emdata.description_title. - Webhooks (Legacy). Um plugin por projeto, nas configurações do projeto. Ele ainda funciona, mas a própria página de configurações diz que o Sentry recomenda fortemente uma integração interna. Seu payload é plano:
project_name,culprit,level,url,triggering_rulese oeventbruto.
Este guia usa a integração interna e traz um template para o webhook legacy no final.
Passo 1: criar o webhook no Pocket Alert
O Pocket Alert nomeia cada push de webhook como Webhook <name>, então chame o seu de Sentry e o título na tela de bloqueio vai ser "Webhook Sentry". O corpo vem de um template que extrai campos do JSON do Sentry usando placeholders %path%.
O jeito mais rápido é uma chamada de API, porque o template dos botões de ação só pode ser definido pela API. Ela cria o webhook com o template da mensagem, um nível padrão e um botão "Open in Sentry", e depois imprime a URL de recebimento:
jq -n \
--arg msg $'%data.event.title%%data.description_title%\n%data.event.culprit%%data.description_text%\nRule: %data.triggered_rule%' \
--arg act '[{"type":"view","label":"Open in Sentry","value":"%data.event.web_url%%data.web_url%"}]' \
'{name: "Sentry", message: $msg, default_level: 1, actions: $act}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
-H "Token: YOUR_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- |
jq -r '"Receive URL: https://p4a.me/wh/" + .url'
O template parece estranho de propósito. Uma integração do Sentry tem uma única URL de webhook, e tanto alertas de issues quanto alertas de métricas vão para ela. Um placeholder cujo caminho não existe no payload vira uma string vazia, então %data.event.title%%data.description_title% mostra o título do erro em um alerta de issue e o título do alerta em um alerta de métrica. O mesmo truque dá ao botão o link certo nos dois casos. Em um alerta de issue, Rule: mostra o nome do alerta; em um alerta de métrica, essa linha fica vazia.
Se preferir clicar, crie o webhook no console em Webhooks: nome Sentry, Prioridade padrão High, e cole o template da mensagem:
%data.event.title%%data.description_title%
%data.event.culprit%%data.description_text%
Rule: %data.triggered_rule%
Você recebe os mesmos pushes, só que sem o botão. Copie a URL de recebimento que o console mostra (https://p4a.me/wh/...).
Passo 2: criar a integração interna no Sentry
- No Sentry, vá em Settings > Developer Settings, crie uma nova integração e escolha Internal Integration.
- Dê a ela um nome como "Pocket Alert".
- Cole a URL de recebimento em Webhook URL.
- Ative Alert Action. Esse toggle é o que coloca a integração no construtor de alertas.
- Salve. Integrações internas se instalam sozinhas na sua organização; não há etapa de OAuth.
Deixe desmarcadas as outras assinaturas de webhook (issue, error, comment). O Pocket Alert transforma cada requisição que recebe em um push, e esses recursos chegariam como pushes com linhas quase vazias.
Passo 3: enviar alertas para ele
O construtor de alertas atual do Sentry fica em Monitors > Alerts > Create Alert:
- Source: os projetos que importam para você, ou monitores específicos.
- Environment: escolha
production, para o ruído do staging não chegar ao seu celular. - When: "A new issue is created" é a escolha clássica. Vale adicionar "An issue escalates" e "A resolved issue regresses".
- Then: Send a notification via an integration, e selecione a integração "Pocket Alert".
- Throttling: defina algo como 30 minutos, para que uma issue quente não envie um push para cada evento.
Antes de salvar, clique em Send Test Notification no bloco If/Then. Um push com o título "Webhook Sentry" deve chegar ao seu celular em um ou dois segundos.
O que chega no seu celular
Para um alerta de issue, o payload do Sentry traz o erro em data.event. Estes são os campos que o template usa, a partir do payload event_alert documentado pelo Sentry:
| Campo | Exemplo | Usado para |
|---|---|---|
data.event.title | ReferenceError: heck is not defined | Primeira linha do push |
data.event.culprit | onde o erro foi lançado | Segunda linha |
data.triggered_rule | Very Important Alert! | Qual alerta disparou |
data.event.web_url | https://sentry.io/organizations/…/issues/…/events/…/ | Botão "Open in Sentry" |
data.event.level | error | Opcional, veja abaixo |
Um alerta de métrica não tem data.event. Seu action é critical, warning ou resolved, e data.description_title já inclui o estado, por exemplo "Resolved: Too many errors", com data.description_text logo abaixo ("1000 events in the last 10 minutes"). O botão usa data.web_url.
Quer o nível do Sentry no texto? Adicione Level: %data.event.level% ao template. É só texto; a próxima seção explica por que isso não muda o volume com que o push chega.
Níveis: o que de fato define o volume do push
O Pocket Alert tem cinco níveis: silent, low, default, high e critical. Para webhooks, o nível é escolhido nesta ordem: um campo level no nível superior do JSON recebido, depois o nível padrão do webhook, depois o nível padrão do aplicativo.
O Sentry não se mapeia sozinho nisso, e um template não consegue traduzir valores:
- O payload da integração interna não tem
levelno nível superior. O level do Sentry fica emdata.event.level, então o Pocket Alert usa o nível padrão do webhook. Por isso o webhook acima é criado comdefault_level: 1(high), que aparece no iPhone como uma notificação sensível ao tempo que atravessa o Foco. - O webhook legacy envia um
levelno nível superior, mas com os valores do Sentry:fatal,error,warning,info,debug. Nenhum deles é um nível do Pocket Alert, então é ignorado e o nível padrão se aplica. O alerta mesmo assim é entregue.
Se um erro fatal em produção deve te acordar enquanto todo o resto fica em high, separe isso do lado do Sentry. Em um plano pago, crie um segundo webhook do Pocket Alert chamado "Sentry critical" com default_level: 2, e uma segunda integração interna apontando para ele. Depois use dois blocos If/Then no mesmo alerta:
- Bloco 1: If none de: Event level equals
fatal. Then notifique a integração "Pocket Alert". - Bloco 2: If all de: Event level equals
fatal. Then notifique "Pocket Alert critical".
Alertas critical passam pelo Não perturbe no iOS e no Android (veja níveis de prioridade). É um recurso pago: no plano gratuito, critical é entregue como high.
O webhook legacy, se você já usa
Projetos com Webhooks (Legacy) ativado em Project Settings > Legacy Integrations podem apontá-lo para o mesmo tipo de webhook do Pocket Alert. O payload é diferente, então use este template:
%project_name%: %event.title%
%culprit%
Rule: %triggering_rules.0%
E este template de botão para a chamada de API acima:
[{ "type": "view", "label": "Open in Sentry", "value": "%url%" }]
Use %event.title% em vez do %message% do nível superior. No payload legacy, message é a mensagem de log do evento, que fica vazia para uma exceção comum. O plugin legacy só envia quando um alerta tem a ação que notifica as integrações legacy do projeto, e a página de configurações dele tem um botão Send Test Event.
Limites honestos
- Um título para tudo. O Pocket Alert titula pushes de webhook como
Webhook <name>; o erro vai no corpo. Se você precisa do erro como título do push, coloque uma pequena função entre o Sentry e a API de mensagens. - Sem verificação de assinatura. Integrações internas assinam requisições com
Sentry-Hook-Signature, e o Pocket Alert não verifica isso. A URL de recebimento aleatória é o segredo, então não a publique. Se vazar, apague o webhook e crie um novo. - Somente JSON. Os dois mecanismos do Sentry enviam JSON, então aqui tudo bem, mas um remetente que envia form-encoded seria rejeitado.
- Limites diários. O plano gratuito entrega 50 mensagens por dia. Com throttling ativado e alertas só de produção, isso é mais que suficiente; um alerta de "every event captured" vai consumir tudo rapidinho.
Se nada chegar
- Abra o histórico do webhook. Cada requisição ao seu webhook do Pocket Alert fica registrada com headers, corpo, a mensagem renderizada e o status. Se a requisição estiver lá, o problema é o template; se não estiver, o Sentry nunca a enviou.
- Confira o toggle Alert Action. Sem ele, a integração não aparece em Send a notification via an integration.
- Confira o histórico do alerta. A página de detalhes do alerta no Sentry lista as execuções recentes. Filtros como environment ou event level costumam excluir o evento que você esperava.
- Linhas vazias no push significam que um caminho não bate com o payload. Compare com o corpo no histórico do webhook; os nomes dos campos diferenciam maiúsculas de minúsculas.
- Sem botão significa que o caminho da URL saiu vazio, e um botão inválido é descartado enquanto a mensagem ainda é entregue.
FAQ
Preciso escrever algum código?
Não. O Sentry envia o webhook e o Pocket Alert o transforma em push. O único comando deste guia é a chamada de API opcional que adiciona o botão "Open in Sentry".
Dá para separar produção e staging?
Dá. Filtre o alerta por environment, ou crie um alerta por ambiente apontando para integrações e webhooks diferentes, cada um indo para o seu próprio aplicativo no Pocket Alert, para que você possa silenciar o staging separadamente.
Isso funciona com o Sentry auto-hospedado?
A integração interna e a alert action fazem parte do próprio Sentry, então uma instalação auto-hospedada recente o bastante para tê-las pode enviar para o Pocket Alert da mesma forma, desde que consiga acessar p4a.me pela internet.
E o Rollbar, o Bugsnag e outros rastreadores?
A mesma abordagem funciona com qualquer rastreador que faça POST de JSON para uma URL; só mudam os caminhos do template. Veja alertas de rastreamento de erros para a visão geral, a ferramenta de webhook e a sintaxe de templates para entender como os templates funcionam.
É gratuito?
O plano gratuito do Pocket Alert cobre um webhook, um dispositivo e 50 mensagens por dia, o que basta para alertas de erros de produção em um app pequeno.
Crie uma conta gratuita, cole a URL no Sentry, e o próximo erro de produção vai chegar até você primeiro.