Retour au blog

Alertes Sentry sur votre téléphone : notifications push pour les erreurs, sans code

Alertes Sentry sur votre téléphone : notifications push pour les erreurs, sans code

Sentry détecte l’exception au moment où elle se produit. Ensuite, il vous envoie un e-mail, ou publie un message dans un canal Slack qui reçoit aussi les messages de déploiement, les rappels de réunion quotidienne et quelques centaines d’autres choses. Si l’erreur survient à 2 h du matin ou pendant que vous êtes loin de votre ordinateur, vous l’apprenez quand un utilisateur vous le signale.

Les alertes Sentry peuvent faire mieux, mais Sentry ne propose pas d’application push propre aux alertes. En revanche, il dispose d’un webhook qui se déclenche lorsqu’une règle d’alerte correspond. Pointez-le vers Pocket Alert et chaque alerte devient une notification push sur votre téléphone, avec le titre de l’erreur, le coupable et un bouton qui ouvre le ticket. Aucun serveur, aucun code.

Ce dont vous avez besoin

  • Une organisation Sentry dans laquelle vous êtes autorisé à créer des intégrations et des alertes.
  • Un compte Pocket Alert avec l’application installée sur votre téléphone iPhone ou Android. L’offre gratuite comprend un webhook, ce qui suffit pour cette configuration.
  • Une clé API depuis Clés API si vous voulez le bouton « Open in Sentry » (voir plus bas).

Comment Sentry envoie les alertes à un webhook

Sentry propose deux façons d’envoyer une alerte en POST à une URL, et elles n’envoient pas le même JSON :

  • Intégration interne (recommandée par Sentry). Vous créez une intégration privée avec une URL de webhook et vous activez son interrupteur Alert Action. Elle apparaît alors comme une action dans vos alertes. Les alertes sur les incidents arrivent avec l’en-tête Sentry-Hook-Resource: event_alert et l’erreur sous data.event. Les alertes issues des Metric Monitors arrivent avec metric_alert et un titre déjà prêt dans data.description_title.
  • Webhooks (Legacy). Un plugin par projet, dans les paramètres du projet. Il fonctionne toujours, mais la page de paramètres indique elle-même que Sentry recommande fortement une intégration interne. Sa charge utile est plate : project_name, culprit, level, url, triggering_rules et l’objet brut event.

Ce guide utilise l’intégration interne et fournit à la fin un modèle pour le webhook legacy.

Étape 1 : créer le webhook Pocket Alert

Pocket Alert nomme chaque notification push issue d’un webhook Webhook <name>. Appelez donc le webhook Sentry : le titre sur votre écran verrouillé sera « Webhook Sentry ». Le corps du message provient d’un modèle qui extrait des champs du JSON de Sentry à l’aide de marqueurs %path%.

Le plus rapide est un seul appel API, car le modèle du bouton d’action ne peut être défini que par l’API. Il crée le webhook avec le modèle de message, un niveau par défaut et un bouton « Open in Sentry », puis affiche l’URL de réception :

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'

Le modèle paraît étrange, et c’est voulu. Une intégration Sentry ne possède qu’une seule URL de webhook, et les alertes sur les incidents comme les alertes de métriques y sont envoyées. Un marqueur dont le chemin n’existe pas dans la charge utile s’affiche sous forme de chaîne vide : %data.event.title%%data.description_title% affiche donc le titre de l’erreur pour une alerte sur un incident, et le titre de l’alerte pour une alerte de métrique. Le même procédé donne au bouton le bon lien dans les deux cas. Pour une alerte sur un incident, Rule: affiche le nom de l’alerte ; pour une alerte de métrique, cette ligne reste vide.

Si vous préférez passer par l’interface, créez le webhook dans la console à l’adresse Webhooks : nom Sentry, Priorité par défaut Élevée, puis collez le modèle de message :

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

Vous recevrez les mêmes notifications, simplement sans le bouton. Copiez l’URL de réception affichée dans la console (https://p4a.me/wh/...).

Étape 2 : créer l’intégration interne dans Sentry

  1. Dans Sentry, allez dans Settings > Developer Settings, créez une nouvelle intégration et choisissez Internal Integration.
  2. Donnez-lui un nom, par exemple « Pocket Alert ».
  3. Collez l’URL de réception dans Webhook URL.
  4. Activez Alert Action. Cet interrupteur est ce qui fait apparaître l’intégration dans le générateur d’alertes.
  5. Enregistrez. Les intégrations internes s’installent automatiquement dans votre organisation : aucune étape OAuth n’est nécessaire.

Laissez décochés les autres abonnements webhook (issue, error, comment). Pocket Alert transforme chaque requête reçue en notification push, et ces ressources arriveraient sous forme de notifications presque vides.

Étape 3 : envoyer les alertes vers ce webhook

Le générateur d’alertes actuel de Sentry se trouve sous Monitors > Alerts > Create Alert :

  1. Source : les projets qui vous intéressent, ou des monitors précis.
  2. Environment : choisissez production, pour que le bruit de l’environnement de préproduction reste hors de votre téléphone.
  3. When : « A new issue is created » est le choix classique. Ajoutez « An issue escalates » et « A resolved issue regresses », qui valent le coup.
  4. Then : Send a notification via an integration, puis sélectionnez l’intégration « Pocket Alert ».
  5. Throttling : réglez une valeur du type 30 minutes, pour qu’un incident très actif n’envoie pas une notification à chaque événement.

Avant d’enregistrer, cliquez sur Send Test Notification dans le bloc If/Then. Une notification intitulée « Webhook Sentry » doit arriver sur votre téléphone en une ou deux secondes.

Ce qui arrive sur votre téléphone

Pour une alerte sur un incident, la charge utile de Sentry transporte l’erreur sous data.event. Voici les champs utilisés par le modèle, tirés de la charge utile event_alert documentée par Sentry :

ChampExempleUtilisé pour
data.event.titleReferenceError: heck is not definedPremière ligne de la notification
data.event.culpritl’endroit où l’erreur a été levéeDeuxième ligne
data.triggered_ruleVery Important Alert!Quelle alerte s’est déclenchée
data.event.web_urlhttps://sentry.io/organizations/…/issues/…/events/…/Bouton « Open in Sentry »
data.event.levelerrorFacultatif, voir ci-dessous

Une alerte de métrique ne comporte pas de data.event. Son action vaut critical, warning ou resolved, et data.description_title contient déjà l’état, par exemple « Resolved: Too many errors », suivi de data.description_text (« 1000 events in the last 10 minutes »). Le bouton utilise data.web_url.

Vous voulez le niveau Sentry dans le texte ? Ajoutez Level: %data.event.level% au modèle. Ce n’est qu’un texte : la section suivante explique pourquoi cela ne change pas l’intensité avec laquelle la notification est signalée.

Niveaux : ce qui détermine réellement l’intensité de la notification

Pocket Alert propose cinq niveaux : silencieux, faible, par défaut, élevé et critique. Pour les webhooks, le niveau est choisi dans cet ordre : un champ level de premier niveau dans le JSON entrant, puis le niveau par défaut du webhook, puis le niveau par défaut de l’application.

Sentry ne correspond pas à ce système de lui-même, et un modèle ne peut pas traduire des valeurs :

  • La charge utile de l’intégration interne ne contient pas de level de premier niveau. Le niveau de Sentry se trouve dans data.event.level, donc Pocket Alert utilise le niveau par défaut du webhook. C’est pourquoi le webhook ci-dessus est créé avec default_level: 1 (élevé), ce qui l’affiche sur iPhone comme une notification sensible au temps qui passe le mode Concentration.
  • Le webhook legacy envoie bien un level de premier niveau, mais avec les valeurs de Sentry : fatal, error, warning, info, debug. Aucune de ces valeurs n’est un niveau Pocket Alert ; elle est donc ignorée et le niveau par défaut s’applique. L’alerte est tout de même livrée.

Si une erreur fatale en production doit vous réveiller alors que tout le reste reste au niveau élevé, séparez les cas côté Sentry. Avec une offre payante, créez un second webhook Pocket Alert nommé « Sentry critical » avec default_level: 2, ainsi qu’une seconde intégration interne qui pointe vers lui. Utilisez ensuite deux blocs If/Then dans la même alerte :

  • Bloc 1 : If none of : Event level equals fatal. Then notifier l’intégration « Pocket Alert ».
  • Bloc 2 : If all of : Event level equals fatal. Then notifier « Pocket Alert critical ».

Les alertes critiques passent le mode Ne pas déranger sur iOS comme sur Android (voir niveaux de priorité). Il s’agit d’une fonctionnalité payante : avec l’offre gratuite, le niveau critique est livré comme élevé.

Le webhook legacy, si vous l’utilisez déjà

Les projets qui ont activé Webhooks (Legacy) sous Project Settings > Legacy Integrations peuvent le faire pointer vers le même type de webhook Pocket Alert. La charge utile est différente, utilisez donc ce modèle :

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

Et ce modèle de bouton pour l’appel API ci-dessus :

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

Utilisez %event.title% plutôt que le %message% de premier niveau. Dans la charge utile legacy, message correspond au message de journal de l’événement, qui est vide pour une exception ordinaire. Le plugin legacy n’envoie quelque chose que lorsqu’une alerte comporte l’action qui notifie les intégrations legacy du projet, et sa page de paramètres propose un bouton Send Test Event.

Limites honnêtes

  • Un seul titre pour tout. Pocket Alert intitule les notifications issues de webhooks « Webhook » ; l’erreur se trouve dans le corps. Si vous voulez l’erreur comme titre de notification, placez une petite fonction entre Sentry et l’API des messages.
  • Pas de vérification de signature. Les intégrations internes signent les requêtes avec Webhook <name>, et Pocket Alert ne la vérifie pas. L’URL de réception aléatoire fait office de secret : ne la publiez pas. En cas de fuite, supprimez le webhook et créez-en un nouveau.
  • JSON uniquement. Les deux mécanismes de Sentry envoient du JSON, ce qui convient ici, mais un émetteur en Sentry-Hook-Signature serait rejeté.
  • Limites quotidiennes. L’offre gratuite livre 50 messages par jour. Avec le throttling activé et des alertes limitées à la production, c’est largement suffisant ; une alerte sur « chaque événement capturé » les épuisera vite.

Si rien n’arrive

  • Ouvrez l’historique du webhook. Chaque requête reçue par votre webhook Pocket Alert est journalisée avec ses en-têtes, son corps, le message généré et le statut. Si la requête figure dans l’historique, le problème vient du modèle ; sinon, Sentry ne l’a jamais envoyée.
  • Vérifiez l’interrupteur Alert Action. Sans lui, l’intégration n’apparaît pas sous Send a notification via an integration.
  • Vérifiez l’historique de l’alerte. La page de détails de l’alerte dans Sentry liste les exécutions récentes. Des filtres comme l’environnement ou le niveau d’événement excluent souvent l’événement attendu.
  • Des lignes vides dans la notification signifient qu’un chemin ne correspond pas à la charge utile. Comparez-le avec le corps dans l’historique du webhook ; les noms de champs sont sensibles à la casse.
  • Aucun bouton signifie que le chemin de l’URL était vide ; un bouton invalide est ignoré, mais le message est tout de même livré.

FAQ

Dois-je écrire du code ?

Non. Sentry envoie le webhook et Pocket Alert le transforme en notification push. La seule commande de ce guide est l’appel API facultatif qui ajoute le bouton « Open in Sentry ».

Puis-je séparer la production et la préproduction ?

Oui. Filtrez l’alerte par environnement, ou créez une alerte par environnement pointant vers des intégrations et des webhooks différents, chacun envoyant vers sa propre application Pocket Alert afin que vous puissiez couper la préproduction indépendamment.

Cela fonctionne-t-il avec un Sentry auto-hébergé ?

L’intégration interne et l’action d’alerte font partie de Sentry lui-même. Une installation auto-hébergée suffisamment récente pour les proposer peut donc envoyer vers Pocket Alert de la même façon, à condition qu’elle puisse joindre p4a.me sur Internet.

Et Rollbar, Bugsnag et les autres outils de suivi ?

La même approche fonctionne avec tout outil de suivi qui envoie du JSON à une URL ; seuls les chemins des modèles changent. Consultez les alertes de suivi d’erreurs pour une vue d’ensemble, l’outil webhook et la syntaxe des modèles pour comprendre leur fonctionnement.

Est-ce gratuit ?

L’offre gratuite de Pocket Alert couvre un webhook, un appareil et 50 messages par jour, ce qui suffit pour les alertes d’erreurs de production d’une petite application.

Créer un compte gratuit, collez l’URL dans Sentry, et la prochaine erreur de production vous parviendra en premier.

Partager cet article