Avvisi Sentry via chiamata per errori critici

Indice

• Perché Sentry da solo non può farti squillare il telefono
• Cosa ti serve
• Passo 1 — Crea un canale che squilla
• Passo 2 — Crea un'integrazione interna in Sentry
• Passo 3 — Aggiungi l'integrazione come azione della regola
• Passo 4 — Sapere cosa arriva davvero
• Passo 5 — Restringi a ciò che merita una chiamata
• Passo 6 — Una porta più silenziosa per gli avvisi minori
• Squillare solo fuori orario
• Le due trappole
• Dimensione del payload, tempeste e troncamento
• Condividere con il team
• Cosa questo setup non ti dà
• Risoluzione dei problemi
• Domande frequenti
• Sentry può fare una telefonata in modo nativo?
• Un avviso Sentry passa attraverso Non disturbare?
• Serve un piano Sentry a pagamento per i webhook?
• Perché la variabile del template è vuota?
• Come faccio ad avvisare per un solo ambiente?
• Possono essere chiamate due persone per lo stesso errore?
• Meglio filtrare in Sentry o in Echobell?
• In sintesi
• Articoli correlati

Sentry non può chiamarti. Può mandarti una mail, scrivere su Slack o passare l'avviso a PagerDuty, ma non esiste un'azione vocale integrata. Il modo per ottenerla senza comprare una piattaforma di incident management è mandare l'avviso di Sentry a un webhook che squilla: crei un'integrazione interna, la punti a un canale di chiamata Echobell e ci metti davanti un filtro, così passano solo gli errori che rompono davvero la produzione.

Questa guida copre tutto il percorso: l'integrazione, la regola di avviso, il payload che Sentry manda davvero, i template che lo leggono e le due trappole che fanno desistere.

Perché Sentry da solo non può farti squillare il telefono

Le azioni degli issue alert di Sentry coprono notifiche (email, Slack, Discord, Microsoft Teams), creazione di ticket (Jira, GitHub, Azure DevOps) e passaggio a un prodotto di reperibilità (PagerDuty, Opsgenie). Ognuna finisce su uno schermo che devi stare guardando, o su una postazione a pagamento di un'altra piattaforma.

Alle 14:00 va benissimo. Alle 03:00 un messaggio Slack è indistinguibile dal silenzio, e una notifica push perde contro Non disturbare. Per quel piccolo insieme di errori in cui due ore di ritardo costano soldi veri — il checkout che restituisce 500, l'autenticazione che rifiuta tutti, un worker che perde job in silenzio — serve un dispositivo che squilli.

Il webhook è la giuntura. Sentry può chiamare un endpoint HTTPS qualsiasi come azione di una regola; Echobell trasforma quella richiesta HTTP in un avviso in stile chiamata che attraversa la modalità Full Immersion di iOS.

Cosa ti serve

• Un'organizzazione Sentry in cui puoi raggiungere Settings → Developer Settings (owner o manager)
• Echobell installato (App Store / Google Play)
• Cinque minuti

Dalla tua parte non serve nulla di raggiungibile da internet. È Sentry a fare la richiesta in uscita; tu la ricevi e basta.

Passo 1 — Crea un canale che squilla

In Echobell crea un canale e imposta il tipo di notifica su Chiamata. È tutto il senso dell'operazione: un canale di chiamata si comporta come una telefonata in arrivo invece che come un push, quindi passa attraverso Full Immersion e Non disturbare.

Dagli template che abbiano senso alle 3 di notte. Il payload di Sentry è molto annidato, quindi i percorsi delle variabili sono più lunghi del solito:

Titolo: {{data.event.level}}: {{data.event.metadata.type}}
Corpo: {{data.event.title}} — {{data.event.culprit}}

Imposta il template del link nelle impostazioni avanzate, così toccando la notifica si apre l'issue:

{{data.event.web_url}}

Copia l'URL del webhook dalla vista di dettaglio del canale. Ha questa forma:

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

Passo 2 — Crea un'integrazione interna in Sentry

Sentry offre un webhook come azione di regola solo tramite un'integrazione, quindi devi crearne una. È un modulo, non un servizio: non scrivi codice.

1. Vai su Settings → Developer Settings → Custom Integrations
2. Create New Integration → Internal Integration
3. Name: Echobell (è l'etichetta che sceglierai nella regola)
4. Webhook URL: l'URL del canale del passo 1
5. Attiva l'interruttore Alert Rule Action
6. Permissions: basta Issue & Event → Read
7. Sotto Webhooks, lascia tutte le caselle non spuntate — vedi la trappola più sotto
8. Salva

Un'integrazione interna è limitata alla tua organizzazione e si installa da sola. Il token che genera, per questo setup, non ti servirà mai.

Passo 3 — Aggiungi l'integrazione come azione della regola

Vai su Alerts → Create Alert → Issue Alert, oppure modifica una regola esistente.

Sotto Then perform these actions aggiungi Send a notification via an integration e scegli Echobell.

Imposta Action interval — il limitatore "se questo avviso è scattato più di una volta" — ad almeno 30 minutes. Il valore predefinito invia a ogni scatto, e un errore che parte 400 volte al minuto comporrà il tuo numero finché non spegni tutto.

Salva e lancia il test della regola, così vedi arrivare un payload vero prima di fidarti.

Passo 4 — Sapere cosa arriva davvero

È qui che la maggior parte dei setup si rompe, perché il payload non ha la forma che immagini. Sentry incapsula tutto:

{
  "action": "triggered",
  "actor": { "id": "sentry", "name": "Sentry", "type": "application" },
  "data": {
    "event": {
      "event_id": "e4874d664c3540c1a32eab185f12c5ab",
      "level": "error",
      "title": "ReferenceError: heck is not defined",
      "culprit": "?(<anonymous>)",
      "platform": "javascript",
      "project": 1,
      "release": null,
      "metadata": { "type": "ReferenceError", "value": "heck is not defined" },
      "tags": [["level", "error"], ["browser", "Chrome 75.0.3770"]],
      "issue_id": "1117540176",
      "issue_url": "https://sentry.io/api/0/issues/1117540176/",
      "web_url": "https://sentry.io/organizations/test-org/issues/1117540176/events/e4874.../"
    },
    "triggered_rule": "Very Important Alert!"
  },
  "installation": { "uuid": "a8e5d2..." }
}

Quattro cose da sapere prima di scrivere anche un solo template:

• Tutto ciò che serve sta sotto data.event. {{title}} non produce nulla; {{data.event.title}} produce l'errore.
• data.event.project è un ID numerico, non uno slug. Se vuoi un nome di progetto leggibile nella notifica, scrivilo come testo nel template del titolo e usa un canale per progetto.
• Non c'è un campo environment. L'ambiente arriva dentro data.event.tags come coppia ["environment", "production"], e la sua posizione nell'array non è stabile: non accedervi per indice. Filtra l'ambiente nella regola di Sentry (passo 5).
• data.triggered_rule è il nome della regola. Utile nel corpo quando un canale serve più regole.

L'header Sentry-Hook-Resource vale event_alert per gli issue alert. Puoi richiederlo in una condizione del canale, così nient'altro può farlo squillare:

header["sentry-hook-resource"] == "event_alert"

Passo 5 — Restringi a ciò che merita una chiamata

Un canale di chiamata che squilla a ogni nuovo issue è peggio di nessun canale: in una settimana lo avrai silenziato, e a quel punto non squillerà nemmeno per quello che contava. Filtra in due punti.

In Sentry, con conditions e filters della regola:

In Echobell, usa una condizione di canale come rete di sicurezza per ciò che Sentry non sa esprimere, o per modifiche che oggi non puoi rilasciare:

data.event.level == "fatal" || data.event.level == "error"

Filtrare la gravità nella regola di Sentry di solito è meglio, perché lì vive anche la limitazione di frequenza. Farlo in Echobell è meglio quando vuoi due livelli di urgenza da una sola regola.

Passo 6 — Una porta più silenziosa per gli avvisi minori

Il senso dei livelli è che la chiamata conservi il suo significato. Crea un secondo canale Echobell di tipo Urgente (Time Sensitive), aggiungi una seconda regola Sentry con una soglia più bassa e puntala a una seconda integrazione interna (un'integrazione contiene un solo URL webhook, quindi un secondo canale richiede una seconda integrazione).

Un setup che sopravvive a una settimana vera assomiglia a questo:

Squillare solo fuori orario

Di giorno stai già guardando Sentry. Echobell espone alle condizioni variabili di orario di sistema in UTC, così un canale può comportarsi diversamente a seconda dell'ora senza una seconda regola Sentry:

data.event.level == "fatal" && (hour >= 17 || hour < 9)

Aggiungi un controllo sul giorno se il tuo weekend è davvero libero:

data.event.level == "fatal" && (hour >= 17 || hour < 9 || dayOfWeek == 0 || dayOfWeek == 6)

Sono tutte in UTC, quindi converti dal tuo fuso prima di fissare i numeri. Il riferimento delle condizioni ha l'elenco completo delle variabili.

Le due trappole

Trappola 1: spuntare le caselle Webhooks. Un'integrazione interna ha due percorsi webhook indipendenti. L'interruttore Alert Rule Action rende l'integrazione selezionabile nelle regole: è quello che vuoi. Le caselle Webhooks (issue, error, comment) ti iscrivono a ogni evento di quella risorsa: ogni issue creato, risolto, assegnato, archiviato o ignorato, in tutta l'organizzazione. Spunta issue e il telefono squillerà quando un collega risolve qualcosa. Lasciale tutte vuote e solo le tue regole faranno partire il webhook.

Trappola 2: usare il vecchio plugin Webhooks. Il vecchio plugin per progetto Legacy Integrations → WebHooks esiste ancora e funziona ancora, e sembra una scorciatoia perché puoi incollare un URL senza creare un'integrazione. Il suo payload ha una forma diversa e più piatta, le richieste non sono firmate, e Sentry stesso indirizza altrove i nuovi setup. Se lo usi, i tuoi template avranno bisogno di percorsi di variabili diversi da quelli sopra. Usa l'integrazione interna.

Dimensione del payload, tempeste e troncamento

Tre limiti da conoscere prima che qualcosa vada storto su larga scala:

• 1 MiB di corpo. Echobell rifiuta con HTTP 413 i corpi di trigger oltre 1 MiB. Un payload Sentry porta lo stack trace completo e il contesto della richiesta, quindi di norma sta nelle decine di kilobyte, ma un evento con un corpo di richiesta grande può avvicinarsi. Sentry non ha una manopola max_alerts, quindi la mitigazione è ripulire i corpi grandi nel beforeSend del tuo SDK, cosa che vuoi comunque fare per privacy.
• 120 richieste al minuto per token. Oltre, il trigger risponde 429 con RATE_LIMIT_EXCEEDED e un Retry-After. È l'action interval di Sentry a tenerti sotto; 30 minutes bastano e avanzano.
• 1500 byte di corpo della notifica. Oltre, il testo viene troncato prima di arrivare al dispositivo. data.event.title più culprit ci sta comodo; riversare data.event.exception no, ed è comunque illeggibile su una schermata di blocco. Lascia il dettaglio dietro al template del link.

Condividere con il team

A un canale Echobell possono iscriversi più persone, e ognuna sceglie il proprio tipo di notifica. La stessa regola Sentry può quindi far squillare il telefono di chi è reperibile e arrivare come push normale a tutti gli altri, senza prezzo per postazione né configurazione dei turni.

Quello che non è, è una policy di escalation. Non esiste il "se nessuno conferma entro cinque minuti, chiama il prossimo". Se ti serve quello, ti serve una vera piattaforma di reperibilità; Echobell copre il livello di consegna sottostante.

Cosa questo setup non ti dà

Meglio dirlo chiaramente:

• Nessuna presa in carico. Rispondere alla chiamata non dice nulla a Sentry e non ferma i telefoni degli altri iscritti.
• Nessun turno né escalation. O lo ricevono tutti gli iscritti, o nessuno.
• Nessuna deduplicazione oltre a quella di Sentry. Raggruppamento e limitazione avvengono nella regola; Echobell consegna ciò che arriva.
• Nessuna sincronizzazione bidirezionale. Risolvere l'issue in Sentry non cancella nulla sul telefono.

Se questi sono ostacoli insormontabili, non è lo strumento giusto. Se quello che ti serve davvero è "svegliami quando si rompe il checkout", è più o meno il modo affidabile più economico per ottenerlo.

Risoluzione dei problemi

La regola scatta ma non arriva nulla. Verifica che Alert Rule Action sia attivo nell'integrazione. Se è spento, l'integrazione non compare nemmeno nell'elenco delle azioni — e una regola salvata prima di attivarlo conserva l'azione obsoleta.

Arriva una notifica ma è vuota. Il template sta leggendo chiavi di primo livello. Sentry annida tutto sotto data.event.

Squilla per cose inattese. Controlla le caselle Webhooks dell'integrazione (trappola 1), poi se l'ambiente della regola è rimasto su "All Environments".

Squilla ripetutamente per lo stesso errore. Alza l'action interval della regola. Il ritentativo di Echobell è un'altra cosa: Riprova chiamata fallita, nelle impostazioni dell'app, richiama una chiamata persa.

Non arriva mai nulla, nemmeno il test. Attiva prima il canale con curl per escludere il lato Echobell:

curl -X POST https://hook.echobell.one/t/<channel-token> \
  -H 'Content-Type: application/json' \
  -d '{"data":{"event":{"level":"fatal","title":"Test error","culprit":"manual test","metadata":{"type":"TestError"}}}}'

Se questo squilla e Sentry no, il problema è nell'integrazione, non nel canale.

Domande frequenti

Sentry può fare una telefonata in modo nativo?

No. Le azioni degli avvisi di Sentry sono notifiche, creazione di ticket e integrazioni con prodotti di reperibilità. Una chiamata vocale richiede un servizio esterno: o una piattaforma come PagerDuty, o un ricevitore di webhook che squilla, come Echobell.

Un avviso Sentry passa attraverso Non disturbare?

Solo se arriva come avviso in stile chiamata. Un canale Echobell di tipo chiamata si comporta come una telefonata in arrivo, e Full Immersion e Non disturbare di iOS la lasciano passare. Un push normale di una qualsiasi app no.

Serve un piano Sentry a pagamento per i webhook?

Integrazioni interne e azioni di regola sono disponibili dal piano Developer di Sentry in su. Il webhook in sé non costa nulla in più.

Perché la variabile del template è vuota?

Quasi sempre perché il percorso è troppo corto. Il payload dell'avviso annida l'evento sotto data.event, quindi è {{data.event.title}}, non {{title}}. Attiva il canale una volta e guarda il corpo della richiesta registrato nell'app per vedere la forma esatta.

Come faccio ad avvisare per un solo ambiente?

Imposta il campo Environment nella regola di avviso di Sentry. Non provare a leggerlo da data.event.tags: è un array di coppie [chiave, valore] il cui ordine non è garantito.

Possono essere chiamate due persone per lo stesso errore?

Sì. Condividi il canale e lascia che ognuno si iscriva con il tipo di notifica che preferisce. Non c'è presa in carico, quindi vengono chiamati tutti quelli che hanno scelto "chiamata".

Meglio filtrare in Sentry o in Echobell?

In Sentry quando puoi: nella regola vivono anche la limitazione di frequenza e l'ambito dell'ambiente. In Echobell quando vuoi due livelli di urgenza da una regola sola, quando ti serve una finestra oraria o quando la regola oggi non si può cambiare.

In sintesi

Il setup sono quattro cose: un canale di chiamata, un'integrazione interna con Alert Rule Action attivo e le caselle Webhooks vuote, una regola di avviso abbastanza stretta da meritare una telefonata, e template che leggono data.event. Tutto il resto di questa pagina serve a tenerla abbastanza stretta perché tra un mese quello squillo significhi ancora qualcosa.

Scarica Echobell per iPhone oppure prendilo su Google Play, poi manda il curl qui sopra prima di affidare a questo percorso qualcosa di davvero importante.

Articoli correlati

• Riferimento delle condizioni di canale
• Guida all'integrazione con i webhook
• Guida per sviluppatori all'alert fatigue
• Avvisi telefonici con Prometheus Alertmanager
• Superare la modalità Full Immersion di iOS per gli avvisi critici