Sentry のアラートをスマホに届ける: エラーのプッシュ通知をコードなしで

Sentry は例外が発生した瞬間に捕捉します。ところが通知はメールか、デプロイ通知やスタンドアップのリマインダーなど何百件もの投稿が流れる Slack チャンネルに届くだけです。エラーが午前 2 時に起きたり、PC から離れているときに起きたりすると、ユーザーから連絡が来て初めて気づくことになります。
Sentry のアラートはもっと良くできるはずですが、Sentry にはアラート用のプッシュアプリがありません。代わりにあるのは、アラートルールに一致したときに発火する Webhook です。これを Pocket Alert に向ければ、すべてのアラートがスマホのプッシュ通知になり、エラーのタイトル、発生箇所、Issue を開くボタンが届くようになります。サーバーもコードも不要です。
必要なもの
- インテグレーションとアラートを作成できる Sentry の組織。
- iPhone または Android に Pocket Alert アプリを入れた Pocket Alert アカウント。無料プランには Webhook が 1 つ含まれており、この設定にはそれで十分です。
- 「Sentry で開く」ボタンを使う場合は API キー(詳しくは後述します)。
Sentry が Webhook にアラートを送る仕組み
Sentry には URL へアラートを POST する方法が 2 つあり、送られる JSON も異なります。
- 内部インテグレーション(Sentry が推奨する方法)。Webhook URL を指定したプライベートなインテグレーションを作成し、Alert Action のトグルをオンにします。すると、アラートのアクションとして表示されるようになります。Issue アラートは
Sentry-Hook-Resource: event_alertヘッダーと、data.event配下のエラー情報とともに届きます。メトリクスモニターによる Issue のアラートはmetric_alertとして届き、data.description_titleに完成したタイトルが入ります。 - Webhooks (Legacy)。プロジェクト設定の下にあるプロジェクト単位のプラグインです。まだ動作しますが、設定ページには内部インテグレーションの利用が強く推奨されると書かれています。ペイロードはフラットで、
project_name、culprit、level、url、triggering_rules、そして生のeventを含みます。
このガイドでは内部インテグレーションを使い、レガシー Webhook 用のテンプレートは最後に示します。
手順 1: Pocket Alert の Webhook を作成する
Pocket Alert は Webhook のプッシュすべてに Webhook <name> という名前を付けます。そのため、名前を Sentry にすると、ロック画面のタイトルは「Webhook Sentry」になります。本文は、%path% というプレースホルダーで Sentry の JSON から項目を取り出すテンプレートから生成されます。
最も手早いのは API を 1 回呼び出す方法です。アクションボタンのテンプレートは API からしか設定できないためです。このコマンドでメッセージテンプレート、デフォルトのレベル、「Sentry で開く」ボタンを備えた Webhook を作成し、受信 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 のインテグレーションには Webhook URL が 1 つしかなく、Issue アラートもメトリクスアラートもそこに届くからです。ペイロードに存在しないパスのプレースホルダーは空文字列になります。そのため %data.event.title%%data.description_title% は、Issue アラートならエラーのタイトルを、メトリクスアラートならアラートのタイトルを表示します。同じ仕組みで、どちらの場合もボタンに正しいリンクが入ります。Issue アラートでは Rule: にアラート名が表示され、メトリクスアラートではその行は空のままになります。
クリックで設定したい場合は、コンソールの Webhook で作成してください。名前は 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 の手順はありません。
ほかの Webhook サブスクリプション(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 分程度に設定すると、頻発する Issue でイベントごとにプッシュが届くことを防げます。
保存する前に、If/Then ブロックの Send Test Notification をクリックします。「Webhook Sentry」というタイトルのプッシュが 1、2 秒以内にスマホに届くはずです。
スマホに届く内容
Issue アラートの場合、Sentry のペイロードはエラー情報を data.event 配下に含みます。以下は、テンプレートで使う項目です。Sentry が公開している event_alert のペイロードに基づいています。
| 項目 | 例 | 用途 |
|---|---|---|
data.event.title | ReferenceError: heck is not defined | プッシュの 1 行目 |
data.event.culprit | エラーが投げられた場所 | 2 行目 |
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 の 5 段階です。Webhook の場合、レベルは次の順に決まります。受信 JSON のトップレベルにある level フィールド、次に Webhook のデフォルトレベル、最後にアプリケーションのデフォルトレベルです。
Sentry は自動ではこれに対応しませんし、テンプレートで値を変換することもできません。
- 内部インテグレーションのペイロードにはトップレベルの
levelがありません。Sentry のレベルはdata.event.levelにあるため、Pocket Alert は Webhook のデフォルトレベルを使います。上の Webhook がdefault_level: 1(high)で作成されているのはそのためです。これは iPhone では、集中モードを通過する時間に敏感な通知として表示されます。 - レガシー Webhook はトップレベルの
levelを送りますが、値は Sentry のもの、つまりfatal、error、warning、info、debugです。これらはどれも Pocket Alert のレベルではないため無視され、デフォルトレベルが適用されます。アラート自体は届きます。
本番環境の致命的なエラーだけで起こされたい一方、ほかはすべて high のままにしたい場合は、Sentry 側で分けてください。有料プランでは、default_level: 2 の「Sentry critical」という 2 つ目の Pocket Alert Webhook を作成し、それを指す 2 つ目の内部インテグレーションを用意します。そのうえで、同じアラートに 2 つの If/Then ブロックを設定します。
- ブロック 1: If none の条件として、Event level が
fatalと等しい。Then で「Pocket Alert」インテグレーションに通知。 - ブロック 2: If all の条件として、Event level が
fatalと等しい。Then で「Pocket Alert critical」に通知。
critical のアラートは iOS と Android の両方でおやすみモードを通過します(優先度レベルを参照)。これは有料機能で、無料プランでは critical は high として配信されます。
既存のレガシー Webhook を使っている場合
Project Settings > Legacy Integrations で Webhooks (Legacy) を有効にしているプロジェクトは、同じ種類の Pocket Alert Webhook を指定できます。ペイロードは異なるため、次のテンプレートを使ってください。
%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 のプッシュのタイトルを
Webhook <name>にし、エラーは本文に入ります。エラーをプッシュのタイトルにしたい場合は、Sentry と メッセージ API の間に小さな関数を挟んでください。 - 署名の検証なし。 内部インテグレーションは
Sentry-Hook-Signatureでリクエストに署名しますが、Pocket Alert はこれを検証しません。ランダムに生成された受信 URL が秘密情報になるため、公開しないでください。漏えいした場合は、Webhook を削除して新しく作成してください。 - JSON のみ。 Sentry の両方の仕組みは JSON を送るため、ここでは問題ありません。ただしフォームエンコードで送る送信元は拒否されます。
- 1 日の上限。 無料プランでは 1 日 50 件のメッセージが配信されます。スロットリングを有効にし、本番環境のアラートだけに絞れば十分です。「キャプチャされたすべてのイベント」に対するアラートでは、すぐに上限に達してしまいます。
何も届かない場合
- Webhook の履歴を開く。 Pocket Alert の Webhook へのすべてのリクエストは、ヘッダー、本文、レンダリング後のメッセージ、ステータスとともに記録されます。リクエストがあれば問題はテンプレートにあり、なければ Sentry が送信していません。
- Alert Action のトグルを確認する。 これがオフだと、Send a notification via an integration の下にインテグレーションが表示されません。
- アラートの履歴を確認する。 Sentry のアラートの詳細ページには最近の実行履歴が表示されます。環境やイベントレベルのフィルターによって、期待したイベントが除外されていることがよくあります。
- プッシュに空の行がある場合は、パスがペイロードと一致していないことを意味します。Webhook の履歴にある本文と比べてください。項目名は大文字と小文字を区別します。
- ボタンがない場合は、URL のパスが空になっています。無効なボタンは破棄されますが、メッセージは配信されます。
FAQ
コードを書く必要はありますか?
いいえ。Sentry が Webhook を送信し、Pocket Alert がそれをプッシュ通知に変換します。このガイドで使うコマンドは、「Sentry で開く」ボタンを追加する任意の API 呼び出しだけです。
本番環境とステージングを分けられますか?
はい。環境でアラートをフィルターするか、環境ごとにアラートを 1 つずつ作成し、それぞれ別のインテグレーションと Webhook に向けてください。そうすれば、それぞれを別の Pocket Alert アプリケーションに送り、ステージングだけを個別にミュートできます。
セルフホストの Sentry でも使えますか?
内部インテグレーションとアラートアクションは Sentry 本体の機能です。これらを備えられるほど新しいセルフホスト版であれば、インターネット経由で p4a.me に到達できる限り、同じ方法で Pocket Alert に送信できます。
Rollbar、Bugsnag などの他のトラッカーは?
JSON を URL に POST するトラッカーなら、同じ方法が使えます。変わるのはテンプレートのパスだけです。全体像は エラートラッキングのアラートを、テンプレートの仕組みについては Webhook ツールとテンプレートの構文をご覧ください。
無料で使えますか?
Pocket Alert の無料プランには、Webhook 1 つ、デバイス 1 台、1 日 50 件のメッセージが含まれます。小規模なアプリの本番エラーのアラートなら、これで十分です。
無料アカウントを作成して URL を Sentry に貼り付ければ、次に本番環境でエラーが発生したときに、真っ先に通知が届きます。