Voltar para o blog

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

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_alert e o erro em data.event; alertas de issues vindos de Metric Monitors chegam como metric_alert, com um título pronto em data.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_rules e o event bruto.

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

  1. No Sentry, vá em Settings > Developer Settings, crie uma nova integração e escolha Internal Integration.
  2. Dê a ela um nome como "Pocket Alert".
  3. Cole a URL de recebimento em Webhook URL.
  4. Ative Alert Action. Esse toggle é o que coloca a integração no construtor de alertas.
  5. 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:

  1. Source: os projetos que importam para você, ou monitores específicos.
  2. Environment: escolha production, para o ruído do staging não chegar ao seu celular.
  3. When: "A new issue is created" é a escolha clássica. Vale adicionar "An issue escalates" e "A resolved issue regresses".
  4. Then: Send a notification via an integration, e selecione a integração "Pocket Alert".
  5. 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:

CampoExemploUsado para
data.event.titleReferenceError: heck is not definedPrimeira linha do push
data.event.culpritonde o erro foi lançadoSegunda linha
data.triggered_ruleVery Important Alert!Qual alerta disparou
data.event.web_urlhttps://sentry.io/organizations/…/issues/…/events/…/Botão "Open in Sentry"
data.event.levelerrorOpcional, 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 level no nível superior. O level do Sentry fica em data.event.level, então o Pocket Alert usa o nível padrão do webhook. Por isso o webhook acima é criado com default_level: 1 (high), que aparece no iPhone como uma notificação sensível ao tempo que atravessa o Foco.
  • O webhook legacy envia um level no 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.

Compartilhe este artigo