Sentry 告警推送到手机:错误推送通知,无需代码

Sentry 会在异常发生的那一刻捕获它。然后它会给你发邮件,或者发到一个 Slack 频道里,而这个频道还会收到部署消息、站会提醒和其他几百条信息。如果错误在凌晨两点出现,或者你不在电脑前,你往往要等到用户反馈才会知道。
Sentry 告警本可以做得更好,但 Sentry 自己并没有用于告警的推送应用。它能做的是在告警规则匹配时触发一个 Webhook。把它指向 Pocket Alert,每条告警都会变成你手机上的推送通知,包含错误标题、问题来源,以及一个可以打开该问题的按钮。无需服务器,也无需代码。
你需要准备
- 一个允许你创建集成和告警的 Sentry 组织。
- 一个 Pocket Alert 账户,并在你的 iPhone 或 Android 手机 上安装应用。免费套餐包含一个 Webhook,这个配置只需要一个。
- 如果想使用「Open in Sentry」按钮,需要一个来自 API 密钥 页面的 API 密钥(下文详述)。
Sentry 如何将告警发送到 Webhook
Sentry 有两种方式向 URL 发送告警 POST 请求,它们的 JSON 格式不同:
- 内部集成(Sentry 推荐)。你创建一个带有 Webhook URL 的私有集成,并打开它的 Alert Action 开关。之后它会作为一个操作出现在你的告警中。问题告警会带着
Sentry-Hook-Resource: event_alert请求头到达,错误信息位于data.event下;来自指标监控器的问题告警会以metric_alert形式到达,并在data.description_title中包含现成的标题。 - Webhooks(旧版)。项目设置下的一个按项目配置的插件。它仍然可用,但设置页面本身写明 Sentry 强烈推荐使用内部集成。它的负载是扁平结构:
project_name、culprit、level、url、triggering_rules,以及原始的event。
本指南使用内部集成,并在最后提供旧版 Webhook 的模板。
第一步:创建 Pocket Alert Webhook
Pocket Alert 会把每个 Webhook 推送的标题命名为 Webhook <name>,所以把它命名为 Sentry,锁屏上的标题就是「Webhook Sentry」。推送正文来自一个模板,它使用 %path% 占位符从 Sentry 的 JSON 中提取字段。
最快的方式是一次 API 调用,因为操作按钮模板只能通过 API 设置。它会创建带有消息模板、默认级别和「Open in 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,问题告警和指标告警都会发送到这里。如果某个占位符的路径在负载中不存在,它就会渲染为空字符串,所以 %data.event.title%%data.description_title% 对问题告警显示错误标题,对指标告警显示告警标题。同样的技巧也让按钮在两种情况下都能指向正确的链接。对于问题告警,Rule: 会显示告警的名称;在指标告警中,这一行保持为空。
如果你更喜欢点击操作,可以在控制台的 Webhooks 页面创建:名称填 Sentry,默认优先级选择高,然后粘贴消息模板:
%data.event.title%%data.description_title%
%data.event.culprit%%data.description_text%
Rule: %data.triggered_rule%
你会收到相同的推送,只是没有按钮。复制控制台显示的接收 URL(https://p4a.me/wh/...)。
第二步:在 Sentry 中创建内部集成
- 在 Sentry 中进入 Settings > Developer Settings,新建一个集成,并选择 Internal Integration。
- 为它取一个名字,例如「Pocket Alert」。
- 将接收 URL 粘贴到 Webhook URL 中。
- 打开 Alert Action。这个开关会让该集成出现在告警构建器中。
- 保存。内部集成会自动安装到你的组织中,无需 OAuth 步骤。
其他 Webhook 订阅项(issue、error、comment)保持不勾选。Pocket Alert 会把它收到的每个请求都转换为一条推送,而这些资源会以几乎全是空行的推送形式到达。
第三步:让告警发送到它
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」的推送。
手机上会收到什么
对于问题告警,Sentry 的负载把错误信息放在 data.event 下。以下是模板使用的字段,来自 Sentry 文档中的 event_alert 负载:
| 字段 | 示例 | 用途 |
|---|---|---|
data.event.title | ReferenceError: heck is not defined | 推送的第一行 |
data.event.culprit | 抛出错误的位置 | 第二行 |
data.triggered_rule | 非常重要的告警! | 触发的是哪条告警 |
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%。它只是文本;下一节会解释为什么它不会改变推送的提醒强度。
级别:究竟决定推送提醒强度的是什么
Pocket Alert 有五个级别:静默、低、默认、高和紧急。对于 Webhook,级别按以下顺序确定:传入 JSON 中的顶层 level 字段,然后是 Webhook 的默认级别,最后是应用的默认级别。
Sentry 的级别不会自动映射到这套体系,而且模板也无法转换取值:
- 内部集成的负载中没有顶层
level。Sentry 的级别位于data.event.level中,因此 Pocket Alert 会使用 Webhook 的默认级别。这就是为什么上面的 Webhook 创建时设置了default_level: 1(高),在 iPhone 上它会显示为时间敏感通知,并能穿透专注模式。 - 旧版 Webhook 确实会发送顶层
level,但使用的是 Sentry 的取值:fatal、error、warning、info、debug。它们都不是 Pocket Alert 的级别,因此会被忽略,改用默认级别。告警仍然会送达。
如果生产环境中的致命错误应该把你叫醒,而其他情况保持高级别,就需要在 Sentry 端进行拆分。在付费套餐中,创建第二个名为「Sentry critical」的 Pocket Alert Webhook,并设置 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 上都能穿透勿扰模式(参见优先级级别)。这是付费功能:在免费套餐中,紧急告警会按高级别发送。
旧版 Webhook:如果你已经在使用
在 Project Settings > Legacy Integrations 下启用了 Webhooks(旧版) 的项目,可以将它指向同类型的 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,所以这里没有问题,但使用表单编码的发送方会被拒绝。
- 每日上限。 免费套餐每天可投递 50 条消息。开启节流并只为生产环境设置告警时,这已经足够;但如果为「每个捕获的事件」设置告警,很快就会用完。
如果没有收到任何推送
- 查看 Webhook 历史。 发送到你的 Pocket Alert Webhook 的每个请求都会记录请求头、正文、渲染后的消息和状态。如果请求在那里,问题出在模板;如果不在,说明 Sentry 根本没有发送。
- 检查 Alert Action 开关。 没有打开它,该集成就不会出现在 Send a notification via an integration 下。
- 检查告警历史。 Sentry 中告警的详情页会列出最近的运行记录。环境或事件级别等过滤条件经常会排除你预期的事件。
- 推送中出现空行,说明某个路径与负载不匹配。请与 Webhook 历史中的正文对比,字段名区分大小写。
- 没有按钮,说明 URL 路径结果为空;无效的按钮会被丢弃,但消息仍会送达。
常见问题
我需要写任何代码吗?
不需要。Sentry 发送 Webhook,Pocket Alert 将其转换为推送。本指南中唯一的命令是可选的 API 调用,用于添加「Open in Sentry」按钮。
可以把生产环境和测试环境分开吗?
可以。按环境过滤告警,或者为每个环境创建一条告警,分别指向不同的集成和 Webhook,每个 Webhook 投递到各自的 Pocket Alert 应用,这样你就可以单独静音测试环境。
这适用于自托管的 Sentry 吗?
内部集成和告警操作本身就是 Sentry 的功能。只要自托管版本足够新、已经包含这些功能,并且能够通过互联网访问 p4a.me,它就可以用同样的方式发送到 Pocket Alert。
Rollbar、Bugsnag 和其他追踪工具呢?
同样的方法适用于任何能向 URL 发送 JSON 的追踪工具,只需要更改模板中的路径。关于更大的图景,请参阅错误追踪告警;关于模板的工作方式,请参阅 Webhook 工具和模板语法。
这个是免费的吗?
Pocket Alert 的免费套餐包含一个 Webhook、一台设备和每天 50 条消息,对于小型应用的生产错误告警来说已经足够。
免费注册账户,把 URL 粘贴到 Sentry 中,下一个生产环境错误就会第一时间通知你。