Sentry 알림을 휴대폰으로: 코드 없이 에러 푸시 알림 받기

Sentry는 예외가 발생하는 순간 이를 잡아냅니다. 그다음 이메일을 보내거나, 배포 알림, 스탠드업 리마인더 등 수백 가지 메시지가 함께 올라오는 Slack 채널에 글을 올리죠. 에러가 새벽 2시에 발생하거나 노트북에서 떨어져 있을 때 발생하면, 사용자가 알려줄 때까지 모르게 됩니다.
Sentry 알림은 이보다 더 나을 수 있지만, Sentry에는 알림 전용 푸시 앱이 없습니다. 대신 알림 규칙이 조건에 맞을 때 호출되는 웹훅이 있습니다. 이 웹훅을 Pocket Alert로 향하게 하면, 모든 알림이 휴대폰의 푸시 알림으로 도착하고, 에러 제목, 원인 위치, 이슈를 여는 버튼이 함께 표시됩니다. 서버도, 코드도 필요 없습니다.
준비물
- 통합과 알림을 만들 수 있는 권한이 있는 Sentry 조직.
- 아이폰 또는 안드로이드 휴대폰에 앱을 설치한 Pocket Alert 계정. 무료 플랜에는 웹훅 하나가 포함되어 있으며, 이 설정에는 그것으로 충분합니다.
- "Sentry에서 열기" 버튼을 쓰려면 API 키 페이지에서 발급받은 API 키(자세한 내용은 아래에서 설명합니다).
Sentry가 웹훅으로 알림을 보내는 방식
Sentry가 알림을 URL로 POST하는 방법은 두 가지이며, 두 방법은 서로 다른 JSON을 보냅니다.
- 내부 통합(Sentry가 권장하는 방식). 웹훅 URL을 지정한 비공개 통합을 만들고 Alert Action 토글을 켭니다. 그러면 알림에서 액션으로 표시됩니다. 이슈 알림은
Sentry-Hook-Resource: event_alert헤더와 함께data.event아래에 에러 정보를 담아 도착하며, Metric Monitor에서 발생한 이슈 알림은metric_alert로 도착하고data.description_title에 완성된 제목이 담겨 있습니다. - 웹훅(레거시). 프로젝트 설정 아래의 프로젝트별 플러그인입니다. 여전히 동작하지만, 설정 페이지에서도 Sentry가 내부 통합을 강력히 권장한다고 안내합니다. 페이로드는 평평한 구조이며
project_name,culprit,level,url,triggering_rules와 원본event를 담고 있습니다.
이 가이드는 내부 통합을 사용하며, 마지막에 레거시 웹훅용 템플릿을 제공합니다.
1단계: Pocket Alert 웹훅 만들기
Pocket Alert는 모든 웹훅 푸시의 제목을 Webhook <name> 형식으로 지정하므로, 이름을 Sentry로 지정하면 잠금 화면에 "Webhook Sentry"라고 표시됩니다. 본문은 %path% 플레이스홀더로 Sentry JSON의 필드를 가져오는 템플릿에서 만들어집니다.
액션 버튼 템플릿은 API로만 설정할 수 있으므로, 가장 빠른 방법은 API 호출 한 번입니다. 이 호출은 메시지 템플릿, 기본 중요도, "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이 하나만 있고, 이슈 알림과 메트릭 알림이 모두 이 URL로 전송되기 때문입니다. 페이로드에 존재하지 않는 경로의 플레이스홀더는 빈 문자열로 렌더링됩니다. 따라서 %data.event.title%%data.description_title%는 이슈 알림에서는 에러 제목을, 메트릭 알림에서는 알림 제목을 보여 줍니다. 같은 방식으로 두 경우 모두 버튼에 올바른 링크가 들어갑니다. 이슈 알림의 Rule:에는 알림 이름이 표시되고, 메트릭 알림에서는 이 줄이 비어 있습니다.
클릭으로 설정하고 싶다면 웹훅 콘솔에서 웹훅을 만드세요. 이름은 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"처럼 이름을 지정합니다.
- Webhook URL에 수신 URL을 붙여넣습니다.
- Alert Action을 켭니다. 이 토글이 통합을 알림 빌더에 나타나게 합니다.
- 저장합니다. 내부 통합은 조직에 자동으로 설치되며, OAuth 단계가 없습니다.
다른 웹훅 구독(issue, error, comment)은 선택하지 않은 상태로 두세요. Pocket Alert는 받은 요청을 모두 푸시로 바꾸는데, 이 리소스들은 대부분 빈 줄만 있는 푸시로 도착하게 됩니다.
3단계: 알림 보내기
Sentry의 현재 알림 빌더는 Monitors > Alerts > Create Alert에 있습니다.
- Source: 관심 있는 프로젝트, 또는 특정 모니터를 선택합니다.
- Environment:
production을 선택하면 스테이징 알림이 휴대폰에 오지 않습니다. - When: 기본 선택지는 "A new issue is created"입니다. "An issue escalates"와 "A resolved issue regresses"도 추가할 만합니다.
- Then: Send a notification via an integration을 선택한 뒤 "Pocket Alert" 통합을 고릅니다.
- Throttling: 30분 정도로 설정하면, 자주 발생하는 이슈가 이벤트마다 푸시를 보내지 않습니다.
저장하기 전에 If/Then 블록의 Send Test Notification을 클릭하세요. "Webhook Sentry" 제목의 푸시가 1~2초 안에 휴대폰에 도착해야 합니다.
휴대폰에 도착하는 내용
이슈 알림의 경우, Sentry 페이로드는 data.event 아래에 에러 정보를 담습니다. 아래는 Sentry 문서에 정리된 event_alert 페이로드에서 템플릿이 사용하는 필드입니다.
| 필드 | 예시 | 용도 |
|---|---|---|
data.event.title | ReferenceError: heck is not defined | 푸시의 첫 줄 |
data.event.culprit | 에러가 발생한 위치 | 둘째 줄 |
data.triggered_rule | Very Important Alert! | 발동된 알림 |
data.event.web_url | https://sentry.io/organizations/…/issues/…/events/…/ | "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%를 추가하세요. 이는 텍스트일 뿐이며, 푸시가 얼마나 강하게 울리는지는 바꾸지 않습니다. 이유는 다음 섹션에서 설명합니다.
중요도 수준: 푸시의 세기를 실제로 결정하는 것
Pocket Alert에는 silent, low, default, high, critical의 다섯 가지 중요도 수준이 있습니다. 웹훅의 중요도는 다음 순서로 정해집니다. 들어오는 JSON의 최상위 level 필드, 그다음 웹훅의 기본 중요도, 마지막으로 애플리케이션의 기본 중요도입니다.
Sentry 값은 이 체계와 자동으로 맞지 않으며, 템플릿으로는 값을 변환할 수 없습니다.
- 내부 통합 페이로드에는 최상위
level이 없습니다. Sentry의 수준은data.event.level에 있으므로, Pocket Alert는 웹훅의 기본 중요도를 사용합니다. 그래서 위 웹훅은default_level: 1(high)로 만들어지며, iPhone에서는 집중 모드를 통과하는 시간 민감 알림으로 표시됩니다. - 레거시 웹훅은 최상위
level을 보내지만, 값은 Sentry 것입니다.fatal,error,warning,info,debug입니다. 이 값들은 Pocket Alert 수준이 아니므로 무시되고 기본 중요도가 적용됩니다. 알림은 여전히 전달됩니다.
운영 환경의 치명적 에러에만 깨어나고 나머지는 high로 유지하고 싶다면, Sentry 쪽에서 나눠서 설정하세요. 유료 플랜에서는 "Sentry critical"이라는 이름으로 default_level: 2를 설정한 두 번째 Pocket Alert 웹훅을 만들고, 이를 가리키는 두 번째 내부 통합을 만듭니다. 그다음 같은 알림에 If/Then 블록 두 개를 사용합니다.
- 블록 1: If none 조건, Event level이
fatal과 같음. Then "Pocket Alert" 통합에 알림. - 블록 2: If all 조건, Event level이
fatal과 같음. Then "Pocket Alert critical"에 알림.
critical 알림은 iOS와 안드로이드 모두에서 방해 금지 모드를 통과합니다(중요도 수준 참고). 이는 유료 기능입니다. 무료 플랜에서는 critical이 high로 전달됩니다.
이미 사용 중이라면: 레거시 웹훅
Project Settings > Legacy Integrations에서 **Webhooks (Legacy)**를 켠 프로젝트는 같은 종류의 Pocket Alert 웹훅을 가리키도록 설정할 수 있습니다. 페이로드가 다르므로 다음 템플릿을 사용하세요.
%project_name%: %event.title%
%culprit%
Rule: %triggering_rules.0%
그리고 위 API 호출에서 사용할 버튼 템플릿은 다음과 같습니다.
[{ "type": "view", "label": "Open in Sentry", "value": "%url%" }]
최상위 %event.title% 대신 %message%을 사용하세요. 레거시 페이로드에서 message는 이벤트의 로그 메시지인데, 일반적인 예외에서는 비어 있습니다. 레거시 플러그인은 알림에 프로젝트의 레거시 통합에 알리는 액션이 있을 때만 전송하며, 설정 페이지에는 Send Test Event 버튼이 있습니다.
솔직한 한계
- 모든 알림에 같은 제목. Pocket Alert는 웹훅 푸시의 제목을
Webhook <name>으로 지정하고, 에러 내용은 본문에 들어갑니다. 에러를 푸시 제목으로 쓰고 싶다면 Sentry와 메시지 API 사이에 작은 함수를 두세요. - 서명 검증 없음. 내부 통합은
Sentry-Hook-Signature로 요청에 서명하지만, Pocket Alert는 이를 검증하지 않습니다. 무작위로 만들어진 수신 URL이 곧 비밀이므로 공개적으로 게시하지 마세요. 유출되면 웹훅을 삭제하고 새로 만드세요. - JSON만 지원. Sentry의 두 방식 모두 JSON을 보내므로 여기서는 문제없지만, form 인코딩으로 보내는 발신자는 거부됩니다.
- 일일 한도. 무료 플랜은 하루 50개 메시지를 전달합니다. 스로틀링을 켜고 운영 환경 알림만 받는다면 충분합니다. 하지만 "캡처된 모든 이벤트"에 대한 알림을 설정하면 금방 소진됩니다.
아무것도 도착하지 않는다면
- 웹훅 기록 확인. Pocket Alert 웹훅으로 들어온 모든 요청은 헤더, 본문, 렌더링된 메시지, 상태와 함께 기록됩니다. 요청이 기록되어 있다면 문제는 템플릿입니다. 기록이 없다면 Sentry가 아예 보내지 않은 것입니다.
- Alert Action 토글 확인. 이 토글이 꺼져 있으면 Send a notification via an integration 아래에 통합이 나타나지 않습니다.
- 알림 기록 확인. Sentry에서 알림의 상세 페이지에는 최근 실행 기록이 나옵니다. environment나 event level 같은 필터 때문에 기대한 이벤트가 제외되는 경우가 많습니다.
- 푸시에 빈 줄이 있다면 경로가 페이로드와 맞지 않는다는 뜻입니다. 웹훅 기록의 본문과 비교하세요. 필드 이름은 대소문자를 구분합니다.
- 버튼이 없다면 URL 경로가 비어 있다는 뜻입니다. 잘못된 버튼은 제외되지만 메시지는 여전히 전달됩니다.
자주 묻는 질문
코드를 작성해야 하나요?
아니요. Sentry가 웹훅을 보내고, Pocket Alert가 이를 푸시 알림으로 바꿉니다. 이 가이드에서 유일한 명령어는 "Sentry에서 열기" 버튼을 추가하는 선택 사항인 API 호출뿐입니다.
운영 환경과 스테이징을 분리할 수 있나요?
네. environment로 알림을 필터링하거나, 환경마다 알림을 하나씩 만들어 서로 다른 통합과 웹훅을 가리키게 하세요. 각 웹훅은 별도의 Pocket Alert 애플리케이션으로 보내면 스테이징만 따로 음소거할 수 있습니다.
셀프 호스팅 Sentry에서도 되나요?
내부 통합과 알림 액션은 Sentry 자체의 기능입니다. 따라서 이를 지원할 만큼 최신 버전의 셀프 호스팅 설치라면, 인터넷을 통해 p4a.me에 접근할 수 있는 한 같은 방식으로 Pocket Alert에 보낼 수 있습니다.
Rollbar, Bugsnag 등 다른 트래커는요?
JSON을 URL로 보내는 트래커라면 같은 방식이 적용됩니다. 바뀌는 것은 템플릿의 경로뿐입니다. 전체 그림은 에러 추적 알림을, 웹훅 사용법은 웹훅 도구를, 템플릿 작동 방식은 템플릿 문법을 참고하세요.
무료인가요?
Pocket Alert 무료 플랜은 웹훅 하나, 기기 하나, 하루 50개 메시지를 제공합니다. 작은 앱의 운영 에러 알림에는 충분합니다.
무료 계정 만들기를 하고 URL을 Sentry에 붙여넣으세요. 다음 운영 에러는 가장 먼저 여러분에게 도착할 것입니다.