Назад в блог

Sentry-алерты на телефон: push-уведомления об ошибках без кода

Sentry-алерты на телефон: push-уведомления об ошибках без кода

Sentry фиксирует исключение в момент его возникновения. Потом он отправляет письмо или пишет в Slack-канал, куда также приходят сообщения о деплоях, напоминания о стендапах и ещё несколько сотен других событий. Если ошибка случается в 2 часа ночи или когда вас нет за ноутбуком, вы узнаете о ней, только когда её заметит пользователь.

Алерты Sentry могут работать лучше, но собственного push-приложения для алертов у Sentry нет. Зато есть вебхук, который срабатывает, когда совпадает правило алерта. Направьте его на Pocket Alert, и каждый алерт станет push-уведомлением на вашем телефоне с заголовком ошибки, местом возникновения и кнопкой, которая открывает issue. Ни сервера, ни кода не нужно.

Что понадобится

  • Организация в Sentry, где вам разрешено создавать интеграции и алерты.
  • Аккаунт Pocket Alert с приложением на вашем iPhone или Android-телефоне. Бесплатный тариф включает один вебхук, и для этой настройки этого достаточно.
  • API-ключ из раздела API Keys, если вы хотите кнопку «Open in Sentry» (подробнее об этом ниже).

Как Sentry отправляет алерты на вебхук

У Sentry есть два способа отправить алерт методом POST на URL, и JSON в них разный:

  • Internal integration (рекомендуется самим Sentry). Вы создаёте приватную интеграцию с URL вебхука и включаете переключатель Alert Action. После этого она появляется в алертах как действие. Алерты по issue приходят с заголовком Sentry-Hook-Resource: event_alert и ошибкой в data.event. Алерты по issue из Metric Monitors приходят как metric_alert с готовым заголовком в data.description_title.
  • Webhooks (Legacy). Плагин для отдельного проекта, настраивается в его параметрах. Он всё ещё работает, но на странице настроек прямо написано, что Sentry настоятельно рекомендует вместо него внутреннюю интеграцию. Его payload плоский: project_name, culprit, level, url, triggering_rules и исходный event.

В этом руководстве используется внутренняя интеграция, а шаблон для устаревшего вебхука приведён в конце.

Шаг 1: создайте вебхук в Pocket Alert

Pocket Alert называет каждое push с вебхука Webhook <name>, поэтому назовите вебхук Sentry, и заголовок на экране блокировки будет «Webhook Sentry». Текст берётся из шаблона, который извлекает поля из JSON Sentry через плейсхолдеры %path%.

Быстрее всего сделать это одним вызовом API, потому что шаблон кнопки действий можно задать только через API. Вызов создаёт вебхук с шаблоном сообщения, уровнем по умолчанию и кнопкой «Open in Sentry», а затем выводит URL для приёма:

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'

Шаблон выглядит необычно намеренно. Одна внутренняя интеграция Sentry имеет один URL вебхука, и на него приходят и алерты по issue, и алерты по метрикам. Плейсхолдер, путь которого отсутствует в payload, превращается в пустую строку, поэтому %data.event.title%%data.description_title% показывает заголовок ошибки для алерта по issue и заголовок алерта для алерта по метрике. Тот же приём даёт кнопке правильную ссылку в обоих случаях. Для алерта по issue строка Rule: показывает название алерта, а в алерте по метрике эта строка остаётся пустой.

Если вам удобнее работать мышкой, создайте вебхук в консоли на странице Webhooks: название Sentry, Default priority High, и вставьте шаблон сообщения:

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

Пуши будут такими же, только без кнопки. Скопируйте URL для приёма, который показывает консоль (https://p4a.me/wh/...).

Шаг 2: создайте внутреннюю интеграцию в Sentry

  1. В Sentry откройте Settings > Developer Settings, создайте новую интеграцию и выберите Internal Integration.
  2. Дайте ей название, например «Pocket Alert».
  3. Вставьте URL для приёма в поле Webhook URL.
  4. Включите Alert Action. Именно этот переключатель добавляет интеграцию в конструктор алертов.
  5. Сохраните. Внутренние интеграции устанавливаются в вашу организацию автоматически; шага OAuth нет.

Остальные подписки на вебхуки (issue, error, comment) не отмечайте. Pocket Alert превращает в push каждый полученный запрос, а эти ресурсы приходили бы push-уведомлениями почти с пустыми строками.

Шаг 3: отправляйте алерты в интеграцию

Текущий конструктор алертов Sentry находится в разделе Monitors > Alerts > Create Alert:

  1. Source: проекты, которые вас интересуют, или конкретные мониторы.
  2. Environment: выберите production, чтобы шум со staging не попадал на телефон.
  3. When: классический вариант — «A new issue is created». Стоит добавить «An issue escalates» и «A resolved issue regresses».
  4. Then: Send a notification via an integration и выберите интеграцию «Pocket Alert».
  5. Throttling: установите что-то вроде 30 минут, чтобы активная issue не отправляла push на каждое событие.

Перед сохранением нажмите Send Test Notification в блоке If/Then. Push с заголовком «Webhook Sentry» должен прийти на телефон через секунду-две.

Что приходит на телефон

Для алерта по issue payload Sentry передаёт ошибку в data.event. Ниже поля, которые использует шаблон, из задокументированного payload event_alert в Sentry:

ПолеПримерДля чего используется
data.event.titleReferenceError: heck is not definedПервая строка push
data.event.culpritместо, где было выброшено исключениеВторая строка
data.triggered_ruleVery Important Alert!Какой алерт сработал
data.event.web_urlhttps://sentry.io/organizations/…/issues/…/events/…/Кнопка «Open in Sentry»
data.event.levelerrorНеобязательно, см. ниже

В алерте по метрике поля data.event нет. Его action принимает значения critical, warning или resolved, а data.description_title уже содержит состояние, например «Resolved: Too many errors», а под ним data.description_text («1000 events in the last 10 minutes»). Кнопка использует data.web_url.

Хотите видеть уровень Sentry в тексте? Добавьте Level: %data.event.level% в шаблон. Это только текст: следующий раздел объясняет, почему он не меняет громкость push.

Уровни: что на самом деле определяет громкость push

В Pocket Alert пять уровней: silent, low, default, high и critical. Для вебхуков уровень выбирается в таком порядке: поле level верхнего уровня во входящем JSON, затем уровень вебхука по умолчанию, затем уровень по умолчанию для приложения.

Sentry сам по себе под это не подходит, а шаблон не может переводить значения:

  • В payload внутренней интеграции нет level верхнего уровня. Уровень Sentry находится в data.event.level, поэтому Pocket Alert использует уровень вебхука по умолчанию. Поэтому вебхук выше создаётся с default_level: 1 (high), что на iPhone отображается как чувствительное ко времени уведомление, которое проходит через Фокусирование.
  • Устаревший вебхук отправляет level верхнего уровня, но со значениями Sentry: fatal, error, warning, info, debug. Ни одно из них не является уровнем Pocket Alert, поэтому оно игнорируется и применяется уровень по умолчанию. Алерт всё равно доставляется.

Если фатальная ошибка в production должна вас будить, а всё остальное пусть остаётся на уровне high, разделите их на стороне Sentry. На платном тарифе создайте второй вебхук Pocket Alert с названием «Sentry critical» и default_level: 2, а также вторую внутреннюю интеграцию, которая на него указывает. Затем используйте два блока If/Then в одном алерте:

  • Блок 1: If none из условий: Event level equals fatal. Then отправить уведомление в интеграцию «Pocket Alert».
  • Блок 2: If all из условий: Event level equals fatal. Then отправить уведомление в «Pocket Alert critical».

Критические уведомления проходят режим «Не беспокоить» и на iOS, и на Android (см. уровни приоритета). Это платная функция: на бесплатном тарифе critical доставляется как high.

Устаревший вебхук, если вы уже его используете

Проекты, в которых включён Webhooks (Legacy) в Project Settings > Legacy Integrations, могут направить его на такой же вебхук Pocket Alert. Payload здесь другой, поэтому используйте этот шаблон:

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

И этот шаблон кнопки для вызова API выше:

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

Используйте %event.title%, а не %message% верхнего уровня. В устаревшем payload message — это лог-сообщение события, которое для обычного исключения пустое. Устаревший плагин отправляет данные только тогда, когда в алерте есть действие, уведомляющее устаревшие интеграции проекта, а на его странице настроек есть кнопка Send Test Event.

Честные ограничения

  • Один заголовок для всего. Pocket Alert называет push с вебхука Webhook <name>, а ошибка попадает в текст. Если нужна ошибка в заголовке push, поставьте небольшую функцию между Sentry и API сообщений.
  • Нет проверки подписи. Внутренние интеграции подписывают запросы через Sentry-Hook-Signature, а Pocket Alert её не проверяет. Секретом служит случайный URL для приёма, поэтому не публикуйте его. Если он утёк, удалите вебхук и создайте новый.
  • Только JSON. Оба механизма Sentry отправляют JSON, так что здесь всё в порядке, но отправитель с form-encoded данными получит отказ.
  • Дневные лимиты. Бесплатный тариф доставляет 50 сообщений в день. При включённом throttling и алертах только для production этого достаточно; алерт на «каждое захваченное событие» исчерпает лимит быстро.

Если ничего не приходит

  • Откройте историю вебхука. Каждый запрос к вашему вебхуку Pocket Alert записывается с заголовками, телом, готовым сообщением и статусом. Если запрос есть, проблема в шаблоне; если нет, Sentry его не отправлял.
  • Проверьте переключатель Alert Action. Без него интеграция не появится в разделе Send a notification via an integration.
  • Проверьте историю алерта. На странице деталей алерта в Sentry перечислены последние запуски. Фильтры по окружению или уровню события часто отсекают событие, которое вы ожидали.
  • Пустые строки в push означают, что путь не совпадает с payload. Сравните его с телом в истории вебхука: имена полей чувствительны к регистру.
  • Нет кнопки означает, что путь URL получился пустым; некорректная кнопка отбрасывается, а сообщение при этом доставляется.

Частые вопросы

Нужно ли писать код?

Нет. Sentry отправляет вебхук, а Pocket Alert превращает его в push. Единственная команда в этом руководстве — необязательный вызов API, который добавляет кнопку «Open in Sentry».

Можно ли разделить production и staging?

Да. Отфильтруйте алерт по окружению или создайте по одному алерту на окружение, направленному на разные интеграции и вебхуки, каждый из которых отправляет в своё приложение Pocket Alert, чтобы можно было отключить staging отдельно.

Работает ли это с self-hosted Sentry?

Внутренняя интеграция и действие алерта являются частью самого Sentry, поэтому self-hosted установка достаточно свежей версии, где они есть, может отправлять данные в Pocket Alert так же, если она имеет доступ к p4a.me через интернет.

А Rollbar, Bugsnag и другие трекеры?

Тот же подход работает с любым трекером, который отправляет JSON на URL; меняются только пути в шаблоне. Общую картину см. в разделе алерты об ошибках, а о том, как работают шаблоны, — в инструменте для вебхуков и синтаксисе шаблонов.

Это бесплатно?

Бесплатный тариф Pocket Alert включает один вебхук, одно устройство и 50 сообщений в день, чего хватает для алертов об ошибках в production небольшого приложения.

Создайте бесплатный аккаунт, вставьте URL в Sentry, и следующая ошибка в production придёт к вам первой.

Поделиться статьёй