Torna al blog

Alert Sentry sul telefono: notifiche push per gli errori, senza codice

Alert Sentry sul telefono: notifiche push per gli errori, senza codice

Sentry intercetta l'eccezione nel momento in cui si verifica. Poi ti manda una email, oppure pubblica un messaggio su un canale Slack che riceve anche i messaggi di deploy, i promemoria della standup e qualche centinaio di altre cose. Se l'errore si verifica alle 2 di notte o mentre sei lontano dal portatile, lo scopri quando lo segnala un utente.

Gli alert di Sentry possono fare di meglio, ma Sentry non ha un'app push propria per gli alert. Quello che ha è un webhook che si attiva quando una regola di alert corrisponde. Puntalo su Pocket Alert e ogni alert diventa una notifica push sul tuo telefono, con il titolo dell'errore, il culprit e un pulsante che apre la issue. Nessun server, nessun codice.

Cosa ti serve

  • Un'organizzazione Sentry in cui puoi creare integrazioni e alert.
  • Un account Pocket Alert con l'app sul tuo telefono iPhone o Android. Il piano gratuito include un webhook, che è tutto ciò che serve per questa configurazione.
  • Una chiave API da Chiavi API se vuoi il pulsante "Apri in Sentry" (ne parliamo più avanti).

Come Sentry invia gli alert a un webhook

Sentry ha due modi per inviare con POST un alert a un URL, e inviano JSON diversi:

  • Integrazione interna (consigliata da Sentry). Crei un'integrazione privata con un URL del webhook e attivi il suo interruttore Alert Action. Da quel momento compare come azione negli alert. Gli alert su issue arrivano con l'header Sentry-Hook-Resource: event_alert e l'errore sotto data.event; gli alert sulle issue generati dai Metric Monitor arrivano come metric_alert con un titolo già pronto in data.description_title.
  • Webhook (Legacy). Un plugin per progetto, nelle impostazioni del progetto. Funziona ancora, ma la pagina delle impostazioni stessa dice che Sentry consiglia caldamente un'integrazione interna. Il suo payload è piatto: project_name, culprit, level, url, triggering_rules e l'event grezzo.

Questa guida usa l'integrazione interna e alla fine fornisce un template per il webhook legacy.

Passo 1: Crea il webhook Pocket Alert

Pocket Alert intitola ogni push da webhook Webhook <name>, quindi chiamalo Sentry e il titolo sulla schermata di blocco sarà "Webhook Sentry". Il corpo deriva da un template che estrae i campi dal JSON di Sentry tramite i segnaposto %path%.

Il modo più rapido è una singola chiamata API, perché il template del pulsante di azione può essere impostato solo tramite API. Crea il webhook con il template del messaggio, un livello predefinito e un pulsante "Apri in Sentry", poi stampa l'URL di ricezione:

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'

Il template sembra strano di proposito. Un'integrazione Sentry ha un solo URL di webhook, e sia gli alert su issue sia quelli metrici vi arrivano. Un segnaposto il cui percorso non esiste nel payload viene reso come stringa vuota, quindi %data.event.title%%data.description_title% mostra il titolo dell'errore per un alert su issue e il titolo dell'alert per un alert metrico. Lo stesso trucco fornisce al pulsante il link corretto in entrambi i casi. Per un alert su issue la riga Rule: mostra il nome dell'alert; su un alert metrico quella riga resta vuota.

Se preferisci usare il mouse, crea il webhook dalla console in Webhook: nome Sentry, Priorità predefinita Alta, e incolla il template del messaggio:

%data.event.title%%data.description_title%
%data.event.culprit%%data.description_text%
Rule: %data.triggered_rule%

Ricevi le stesse push, solo senza il pulsante. Copia l'URL di ricezione mostrato dalla console (https://p4a.me/wh/...).

Passo 2: Crea l'integrazione interna in Sentry

  1. In Sentry vai su Settings > Developer Settings, crea una nuova integrazione e scegli Internal Integration.
  2. Dalle un nome come "Pocket Alert".
  3. Incolla l'URL di ricezione in Webhook URL.
  4. Attiva Alert Action. Questo interruttore è ciò che inserisce l'integrazione nel generatore di alert.
  5. Salva. Le integrazioni interne si installano da sole nella tua organizzazione; non c'è un passaggio OAuth.

Lascia deselezionate le altre iscrizioni ai webhook (issue, error, comment). Pocket Alert trasforma in push ogni richiesta che riceve, e quelle risorse arriverebbero come push con righe quasi vuote.

Passo 3: Invia gli alert a Pocket Alert

Il generatore di alert attuale di Sentry si trova in Monitors > Alerts > Create Alert:

  1. Source: i progetti che ti interessano, o monitor specifici.
  2. Environment: scegli production, così il rumore dello staging resta fuori dal telefono.
  3. When: "A new issue is created" è la scelta classica. Vale la pena aggiungere "An issue escalates" e "A resolved issue regresses".
  4. Then: Send a notification via an integration, e seleziona l'integrazione "Pocket Alert".
  5. Throttling: imposta qualcosa come 30 minuti, così una issue molto attiva non invia una push per ogni evento.

Prima di salvare, clicca Send Test Notification nel blocco If/Then. Una push intitolata "Webhook Sentry" dovrebbe arrivare sul telefono in uno o due secondi.

Cosa arriva sul telefono

Per un alert su issue, il payload di Sentry contiene l'errore sotto data.event. Questi sono i campi usati dal template, presi dal payload event_alert documentato da Sentry:

CampoEsempioUsato per
data.event.titleReferenceError: heck is not definedPrima riga della push
data.event.culpritdove è stato generato l'erroreSeconda riga
data.triggered_ruleVery Important Alert!Quale alert è scattato
data.event.web_urlhttps://sentry.io/organizations/…/issues/…/events/…/Pulsante "Apri in Sentry"
data.event.levelerrorFacoltativo, vedi sotto

Un alert metrico non ha data.event. Il suo action è critical, warning o resolved, e data.description_title include già lo stato, per esempio "Resolved: Too many errors", con data.description_text sotto ("1000 events in the last 10 minutes"). Il pulsante usa data.web_url.

Vuoi il livello di Sentry nel testo? Aggiungi Level: %data.event.level% al template. È solo testo; la sezione successiva spiega perché non cambia il volume con cui arriva la push.

Livelli: cosa decide davvero il volume della push

Pocket Alert ha cinque livelli: silenzioso, basso, predefinito, alto e critico. Per i webhook il livello viene scelto in quest'ordine: un campo level di primo livello nel JSON in arrivo, poi il livello predefinito del webhook, poi quello predefinito dell'applicazione.

Sentry non si mappa da solo su questo, e un template non può tradurre i valori:

  • Il payload dell'integrazione interna non ha un level di primo livello. Il livello di Sentry sta in data.event.level, quindi Pocket Alert usa il livello predefinito del webhook. Per questo il webhook qui sopra viene creato con default_level: 1 (alto), che su iPhone appare come notifica sensibile al tempo che passa attraverso Full immersion.
  • Il webhook legacy invia un level di primo livello, ma con i valori di Sentry: fatal, error, warning, info, debug. Nessuno di questi è un livello di Pocket Alert, quindi viene ignorato e si applica il livello predefinito. L'alert viene comunque consegnato.

Se un errore fatale in produzione deve svegliarti mentre tutto il resto resta su alto, separalo lato Sentry. Con un piano a pagamento, crea un secondo webhook Pocket Alert chiamato "Sentry critical" con default_level: 2, e una seconda integrazione interna che punti ad esso. Poi usa due blocchi If/Then nello stesso alert:

  • Blocco 1: If none di: Event level equals fatal. Then notifica l'integrazione "Pocket Alert".
  • Blocco 2: If all di: Event level equals fatal. Then notifica "Pocket Alert critical".

Gli alert critici passano da Non disturbare sia su iOS sia su Android (vedi livelli di priorità). È una funzione a pagamento: con il piano gratuito, il livello critico viene consegnato come alto.

Il webhook legacy, se lo usi già

I progetti che hanno Webhook (Legacy) attivo in Project Settings > Legacy Integrations possono puntarlo allo stesso tipo di webhook Pocket Alert. Il payload è diverso, quindi usa questo template:

%project_name%: %event.title%
%culprit%
Rule: %triggering_rules.0%

E questo template del pulsante per la chiamata API sopra:

[{ "type": "view", "label": "Open in Sentry", "value": "%url%" }]

Usa %event.title% invece del %message% di primo livello. Nel payload legacy message è il messaggio di log dell'evento, che è vuoto per un'eccezione ordinaria. Il plugin legacy invia solo quando un alert ha l'azione che notifica le integrazioni legacy del progetto, e la sua pagina delle impostazioni ha un pulsante Send Test Event.

Limiti onesti

  • Un solo titolo per tutto. Pocket Alert intitola le push da webhook Webhook <name>; l'errore finisce nel corpo. Se ti serve l'errore come titolo della push, inserisci una piccola funzione tra Sentry e le API dei messaggi.
  • Nessuna verifica della firma. Le integrazioni interne firmano le richieste con Sentry-Hook-Signature, e Pocket Alert non la verifica. L'URL di ricezione casuale è il segreto, quindi non pubblicarlo. Se trapela, elimina il webhook e creane uno nuovo.
  • Solo JSON. Entrambi i meccanismi di Sentry inviano JSON, quindi qui va bene, ma un mittente che usa form-encoded verrebbe rifiutato.
  • Limiti giornalieri. Il piano gratuito consegna 50 messaggi al giorno. Con il throttling attivo e solo alert di produzione è più che sufficiente; un alert su "ogni evento catturato" li esaurirà in fretta.

Se non arriva nulla

  • Apri la cronologia dei webhook. Ogni richiesta al tuo webhook Pocket Alert viene registrata con header, corpo, messaggio renderizzato e stato. Se la richiesta c'è, il problema è nel template; se non c'è, Sentry non l'ha mai inviata.
  • Controlla l'interruttore Alert Action. Senza di esso l'integrazione non compare in Send a notification via an integration.
  • Controlla la cronologia dell'alert. La pagina dei dettagli dell'alert in Sentry elenca le esecuzioni recenti. Filtri come ambiente o livello dell'evento spesso escludono l'evento che ti aspettavi.
  • Righe vuote nella push significano che un percorso non corrisponde al payload. Confrontalo con il corpo nella cronologia dei webhook; i nomi dei campi sono sensibili alle maiuscole.
  • Nessun pulsante significa che il percorso dell'URL è risultato vuoto, e un pulsante non valido viene scartato mentre il messaggio viene comunque consegnato.

FAQ

Devo scrivere del codice?

No. Sentry invia il webhook e Pocket Alert lo trasforma in una push. L'unico comando di questa guida è la chiamata API facoltativa che aggiunge il pulsante "Apri in Sentry".

Posso separare produzione e staging?

Sì. Filtra l'alert per ambiente, oppure crea un alert per ambiente che punti a integrazioni e webhook diversi, ciascuno inviato alla propria applicazione Pocket Alert, così puoi silenziare lo staging separatamente.

Funziona con Sentry self-hosted?

L'integrazione interna e l'azione di alert fanno parte di Sentry stesso, quindi un'installazione self-hosted abbastanza recente da averle può inviare a Pocket Alert allo stesso modo, purché raggiunga p4a.me tramite internet.

E Rollbar, Bugsnag e altri tracker?

Lo stesso approccio funziona con qualsiasi tracker che invii JSON a un URL; cambiano solo i percorsi del template. Per il quadro generale vedi alert per il tracciamento degli errori, e per il funzionamento dei template vedi lo strumento webhook e la sintassi dei template.

È gratuito?

Il piano gratuito di Pocket Alert include un webhook, un dispositivo e 50 messaggi al giorno, abbastanza per gli alert sugli errori di produzione di una piccola app.

Crea un account gratuito, incolla l'URL in Sentry, e il prossimo errore di produzione ti raggiungerà per primo.

Condividi questo articolo