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
- В Sentry откройте Settings > Developer Settings, создайте новую интеграцию и выберите Internal Integration.
- Дайте ей название, например «Pocket Alert».
- Вставьте URL для приёма в поле Webhook URL.
- Включите Alert Action. Именно этот переключатель добавляет интеграцию в конструктор алертов.
- Сохраните. Внутренние интеграции устанавливаются в вашу организацию автоматически; шага OAuth нет.
Остальные подписки на вебхуки (issue, error, comment) не отмечайте. Pocket Alert превращает в push каждый полученный запрос, а эти ресурсы приходили бы push-уведомлениями почти с пустыми строками.
Шаг 3: отправляйте алерты в интеграцию
Текущий конструктор алертов Sentry находится в разделе Monitors > Alerts > Create Alert:
- Source: проекты, которые вас интересуют, или конкретные мониторы.
- Environment: выберите
production, чтобы шум со staging не попадал на телефон. - When: классический вариант — «A new issue is created». Стоит добавить «An issue escalates» и «A resolved issue regresses».
- Then: Send a notification via an integration и выберите интеграцию «Pocket Alert».
- Throttling: установите что-то вроде 30 минут, чтобы активная issue не отправляла push на каждое событие.
Перед сохранением нажмите Send Test Notification в блоке If/Then. Push с заголовком «Webhook Sentry» должен прийти на телефон через секунду-две.
Что приходит на телефон
Для алерта по issue payload Sentry передаёт ошибку в data.event. Ниже поля, которые использует шаблон, из задокументированного payload event_alert в Sentry:
| Поле | Пример | Для чего используется |
|---|---|---|
data.event.title | ReferenceError: heck is not defined | Первая строка push |
data.event.culprit | место, где было выброшено исключение | Вторая строка |
data.triggered_rule | Very Important Alert! | Какой алерт сработал |
data.event.web_url | https://sentry.io/organizations/…/issues/…/events/…/ | Кнопка «Open in Sentry» |
data.event.level | error | Необязательно, см. ниже |
В алерте по метрике поля 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 придёт к вам первой.