Prometheus Alertmanager 告警推送到手机:按严重级别路由、告警分组与静默恢复通知

Prometheus 很擅长发现问题出了状况。把这个消息告诉真人,则是 Alertmanager 的工作。在很多部署里,这条消息最后只落进了一个没人会在凌晨 3 点去看的邮件文件夹或 Slack 频道。
Alertmanager 没有自己的推送应用,但它有一个通用的 Webhook 接收器,这就够用了,你可以把告警推送到手机上。本指南会配置严重级别路由:critical 告警以响亮的方式到达,警告以普通通知到达,"已恢复"则安静地到达。这里的所有内容都在 Docker 中使用 Alertmanager 0.34.2 和 Prometheus 3.15.1 测试过。负载内容已被捕获,并通过 Pocket Alert 自己的模板代码运行过。
你需要准备
- 完整配置需要 Alertmanager 0.31 或更高版本。较旧的版本在下文中也有说明。
- 你的 iPhone 或 Android 手机上安装 Pocket Alert 应用,并在 API 密钥 页面获取一个 API 密钥。
- 三个 Webhook 的配置需要付费套餐,因为免费套餐只包含一个 Webhook。文末有单 Webhook 的版本。
Alertmanager 发送什么
Alertmanager 不会为每条告警单独发送一次请求。它会按 group_by 中的标签把告警收集成组,每组发送一条通知:一个 POST 请求,请求体是固定的 JSON,其中 "version": "4"。当 group_by: ['alertname'] 下两台主机同时宕机时,只会发出一次请求。下面是稍作裁剪后的内容:
{
"receiver": "pocketalert-critical",
"status": "firing",
"alerts": [
{
"status": "firing",
"labels": {"alertname": "InstanceDown", "instance": "web-1:9100", "job": "node", "severity": "critical"},
"annotations": {"summary": "web-1:9100 is down"},
"startsAt": "2026-10-31T16:17:04.374Z",
"generatorURL": "http://prometheus.example.com:9090/graph?g0.expr=up%7Bjob%3D%22node%22%7D+%3D%3D+0&g0.tab=1"
},
{
"status": "firing",
"labels": {"alertname": "InstanceDown", "instance": "web-2:9100", "job": "node", "severity": "critical"},
"annotations": {"summary": "web-2:9100 is down"}
}
],
"notification_reason": "first notification",
"groupLabels": {"alertname": "InstanceDown"},
"commonLabels": {"alertname": "InstanceDown", "job": "node", "severity": "critical"},
"commonAnnotations": {},
"routeLabels": {},
"externalURL": "http://alertmanager.example.com:9093",
"version": "4",
"groupKey": "{}/{severity=\"critical\"}:{alertname=\"InstanceDown\"}",
"truncatedAlerts": 0
}
这种负载结构有四点会影响配置:
- 每组推送一条。 各条告警位于
alerts数组中,因此消息模板必须能处理数组。 commonAnnotations经常是空的。 它只包含组内每条告警都相同的注解。提到实例名的摘要在每条告警上都不同,所以不会出现在这里。status属于整个组。 只有组内所有告警都已恢复时,它才是resolved。当一台主机恢复而另一台仍在宕机时,状态保持为firing,已恢复的告警会列在内部,并带有各自的"status": "resolved"。- 顶层没有
level字段,而 Pocket Alert 的 Webhook 正是从这里查找优先级。因此优先级来自 Webhook 的默认级别,这也是本指南为每种响亮程度各配一个 Webhook 的原因。
第 1 步:创建 Pocket Alert Webhook
| Webhook | default_level | 接收内容 |
|---|---|---|
| Prometheus critical | 2(critical) | 带有 severity="critical" 的触发中告警组 |
| Prometheus warning | 0(默认) | 所有其他触发中的告警组 |
| Prometheus resolved | -1(low) | 组内所有告警均已恢复的告警组 |
按钮只能通过 API 设置,因此用一个脚本创建全部三个 Webhook:
PA_KEY='your-api-key'
FIRING='%groupLabels.alertname%: %alerts.#(status=="firing")#|#% firing
%alerts.#(status=="firing").annotations.summary%
Firing: %alerts.#(status=="firing")#.labels.instance%'
RESOLVED='Resolved: %groupLabels.alertname% (%commonLabels.severity%)
%alerts.#.labels.instance%'
BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"}]'
create_webhook() {
jq -n --arg name "$1" --argjson level "$2" --arg message "$3" --arg actions "$4" \
'{name: $name, default_level: $level, message: $message, actions: $actions}' |
curl -sS https://api.pocketalert.app/v1/webhooks \
-H "Token: $PA_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- |
jq -r '"\(.name): https://p4a.me/wh/\(.url)"'
}
create_webhook 'Prometheus critical' 2 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus warning' 0 "$FIRING" "$BUTTONS"
create_webhook 'Prometheus resolved' -1 "$RESOLVED" ''
脚本会输出三个接收 URL。请保留每个 URL 末尾的 slug,你之后要把这些 slug 填入 alertmanager.yml。
%...% 占位符是 GJSON 路径,而 GJSON 可以查询数组:
alerts.#(status=="firing")#|#统计组内仍在触发的告警数量。alerts.#(status=="firing").annotations.summary是第一条触发中告警的摘要。alerts.#(status=="firing")#.labels.instance列出所有触发中告警的实例。它会渲染为 JSON 数组,例如["web-1:9100","web-2:9100"],因为没有字符串拼接函数。
不存在的路径会渲染为空字符串,所以路径写错只会得到一个空行,而不会丢失告警。Pocket Alert 会把每条 Webhook 推送的标题设为 Webhook <name>,因此标题显示为 "Webhook Prometheus critical",告警名称则位于消息的第一行。critical 需要付费套餐,而这个配置本来就需要付费套餐才能使用三个 Webhook。在 iPhone 上,它会无视静音开关和勿扰模式播放;在 Android 上则会占满屏幕。如果你不希望告警覆盖勿扰模式,改用 1(high)。
第 2 步:alertmanager.yml
把三个 *_SLUG 占位符替换为你的 slug:
route:
receiver: pocketalert-warning
group_by: ['alertname']
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
routes:
- matchers: ['severity="critical"']
receiver: pocketalert-critical
group_wait: 10s
repeat_interval: 1h
- matchers: ['severity="info"']
receiver: blackhole
receivers:
- name: pocketalert-critical
webhook_configs:
- url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}CRITICAL_SLUG{{ end }}'
send_resolved: true
max_alerts: 20
- name: pocketalert-warning
webhook_configs:
- url: 'https://p4a.me/wh/{{ if eq .Status "resolved" }}RESOLVED_SLUG{{ else }}WARNING_SLUG{{ end }}'
send_resolved: true
max_alerts: 20
- name: blackhole
inhibit_rules:
- source_matchers: ['severity="critical"']
target_matchers: ['severity="warning"']
equal: ['alertname', 'instance', 'mountpoint']
各部分的工作方式如下:
- 按严重级别路由。
severity="critical"进入响亮的接收器,info被丢弃,其他所有告警(包括没有severity标签的告警)都落到警告接收器。 - URL 决定使用哪个 Webhook。 从 0.31.0 开始,Webhook 的
url是模板。状态为resolved的告警组会发往安静的 Webhook,其他一切都发往该接收器自己的 Webhook。Webhook 的send_resolved默认就是true,这里把它写出来,是为了让人不会在不知情的情况下把它关掉。 max_alerts: 20限制一次请求中包含的告警数量。在测试中,25 台主机同时宕机,结果产生了一条显示 "20 firing" 的推送,负载中的truncatedAlerts: 5表示还有 5 条被省略。- 抑制。 当某文件系统的 critical
DiskSpaceLow触发时,同一alertname、instance和mountpoint的警告会被静音。amtool alert query --inhibited会将其显示为suppressed。
重新加载前,先检查配置和路由:
amtool check-config alertmanager.yml
amtool config routes test --config.file=alertmanager.yml severity=critical alertname=Test
第二条命令会输出 pocketalert-critical。
启动 Alertmanager 时,请将 --web.external-url 设为你能在手机上打开的地址。如果不设置,externalURL 就只是裸主机名。在 Docker 中,它是 http://de48ea5ffc29:9093,这样生成的按钮毫无用处。
先检查版本
alertmanager --version 必须显示 0.31 或更高版本,模板化 URL 才能生效。0.30.1 版本可以接受这份完全相同的配置,amtool check-config 也会报告 SUCCESS,但它不会渲染模板。它会把请求发送到 /wh/%7B%7B%20if%20eq%20.Status...,而这与任何 Webhook 都不匹配。在较旧的版本上,请为每个接收器填写其对应 Webhook 的普通 URL。这样恢复通知就会以该 Webhook 的级别到达。
第 3 步:带有 severity 标签的规则
上面的路由只有在你的规则设置了 severity 时才有效。这里给出两个示例(更多值得监控的内容可参考服务器监控页面)。其中 DiskSpaceLow 设置了两个阈值,这样抑制规则才有作用:
groups:
- name: node
rules:
- alert: InstanceDown
expr: up{job="node"} == 0
for: 2m
labels:
severity: critical
annotations:
summary: '{{ $labels.instance }} is down'
- alert: DiskSpaceLow
expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 15
for: 10m
labels:
severity: warning
annotations:
summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'
- alert: DiskSpaceLow
expr: node_filesystem_avail_bytes{fstype!~"tmpfs|overlay"} / node_filesystem_size_bytes * 100 < 5
for: 5m
labels:
severity: critical
annotations:
summary: '{{ $labels.instance }} {{ $labels.mountpoint }} has {{ printf "%.0f" $value }}% free'
promtool check rules rules.yml 可以校验该文件。在 prometheus.yml 中让 Prometheus 指向该文件以及 Alertmanager:
rule_files: [rules.yml]
alerting:
alertmanagers:
- static_configs:
- targets: ['alertmanager:9093']
用 amtool 测试
触发一条测试告警,等待 group_wait(critical 路由上为 10 秒),然后将其恢复:
amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
--annotation='summary="Test alert from amtool"'
amtool --alertmanager.url=http://localhost:9093 alert add alertname=PocketAlertTest severity=critical instance=test:9100 \
--annotation='summary="Test alert from amtool"' --end="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
注解中的内层双引号要保留,否则 amtool 会警告它已回退到旧的解析器。恢复推送会在下一个 group_interval 周期到达,在此配置下最多可能需要 5 分钟。
手机上会收到什么
以下是 Pocket Alert 根据测试中的真实负载渲染出的消息。测试中 Prometheus 观察到 web-1 和 web-2 宕机并恢复:
Webhook Prometheus critical
InstanceDown: 2 firing
web-1:9100 is down
Firing: ["web-1:9100","web-2:9100"]
当 web-1 恢复时,Alertmanager 会在下一个 group_interval 发送一次更新。该组仍在触发,因此它会发往 critical Webhook:
Webhook Prometheus critical
InstanceDown: 1 firing
web-2:9100 is down
Firing: ["web-2:9100"]
两者都恢复后,会收到一条低优先级推送:
Webhook Prometheus resolved
Resolved: InstanceDown (critical)
["web-1:9100","web-2:9100"]
计时器:避免推送风暴
| 设置 | 作用 | 本配置中的值 |
|---|---|---|
group_wait | 新告警组在发出第一条推送前等待更多告警的时长 | 30s,critical 为 10s |
group_interval | 告警内容发生变化的告警组,两次推送之间的最短间隔 | 5m |
repeat_interval | 仍在触发且内容未变化的告警组的提醒间隔 | 4h,critical 为 1h |
一个告警组每个 group_interval 最多推送一次,因此一个反复抖动的告警在 5m 间隔下每小时最多产生 12 条推送。持续一天的故障,在 1h 的 repeat_interval 下会产生 24 次提醒。分组承担了大部分工作:一台交换机故障导致 40 台主机宕机,只会产生一条推送,而不是 40 条。不要使用 group_by: ['...'],它会按每个标签分组,这样又会退回到每条告警一条推送。各套餐都有每日消息上限(Starter 为每天 1,000 条),而每一次生成消息的 Webhook 请求都会计入上限。
按钮:Alertmanager 与 Grafana
上面的 BUTTONS 模板会添加一个 "Alertmanager" 按钮。你最多可以添加三个操作按钮。下面这个示例会为第一个触发中的实例打开 Grafana 仪表板:
BUTTONS='[{"type":"view","label":"Alertmanager","value":"%externalURL%"},{"type":"view","label":"Grafana","value":"https://grafana.example.com/d/YOUR_DASHBOARD?var-instance=%alerts.#(status=="firing").labels.instance%"}]'
占位符内未转义的引号看起来有问题,但实际可以正常工作:Pocket Alert 会先替换占位符,之后再解析 JSON。
注意空值。value 为空的按钮会从该条推送中被丢弃,其他按钮和消息仍会正常到达。%alerts.0.generatorURL%(Prometheus 图表链接)很适合用于来自 Prometheus 的告警,但通过 amtool 发送的告警没有 generator URL,因此不会带有该按钮。操作按钮是付费功能。
Alertmanager 0.32+:直接调用 API
较旧的指南说 Alertmanager 无法修改 Webhook 请求体。这一点在 0.32.0 中发生了变化,该版本为 payload 新增了 webhook_configs 选项。再配合可以发送 http_config.http_headers 请求头的 Token,Alertmanager 就可以直接 POST 到 https://api.pocketalert.app/v1/messages,并使用它自己的标题和级别。
这里有一个陷阱。Alertmanager 会把渲染后的每个值当作 YAML 解析。在测试中,逐字段构造的负载 message: '{{ range .Alerts }}{{ .Annotations.summary }}...' 把摘要 web-1:9100: / has 12% free 变成了对象 {"web-1:9100": "/ has 12% free"}。API 会以 400 拒绝它。Alertmanager 不会立即重试 4xx,而是在每个 group_interval 反复发送同一个错误的请求体,因此告警永远不会到达。
使用 dict 和 toJson 构造整个请求体可以避免这个问题:
receivers:
- name: pocketalert-api
webhook_configs:
- url: https://api.pocketalert.app/v1/messages
http_config:
http_headers:
Token:
files: [/etc/alertmanager/pocketalert.key]
payload: >-
{{ $msg := "" }}{{ range .Alerts }}{{ $msg = printf "%s%s: %s\n" $msg .Status .Annotations.summary }}{{ end }}
{{ $level := "default" }}{{ if eq .Status "resolved" }}{{ $level = "low" }}{{ else if eq .CommonLabels.severity "critical" }}{{ $level = "critical" }}{{ end }}
{{ dict "title" (printf "[%s] %s" (toUpper .Status) .GroupLabels.alertname) "message" $msg "level" $level | toJson }}
当摘要中包含冒号和引号时,它发送了:
{"level":"critical","message":"firing: web-1:9100: / has 4% free, \"quoted\"\nfiring: web-2:9100 / has 3% free\n","title":"[FIRING] DiskSpaceLow"}
恢复版本则以 "level":"low" 到达。
那么该选哪一种?直接调用 API 可以为每条通知提供真实的标题和级别,所有通知都来自同一个接收器,且不需要 Webhook。Webhook 方式在 Alertmanager 中完全不需要 API 密钥,并且可在任何版本上运行(即普通 URL 的变体)。错误的路径会渲染为空行,而不是被拒绝的请求,而且每个请求都会出现在 Webhook 历史中。Alertmanager 自己的文档将 payload 标注为"风险自担",因此在依赖它之前,请先用 amtool 测试。
免费套餐
免费套餐包含一个 Webhook、每天 50 条消息、没有按钮,并且 critical 会以 high 级别投递。创建一个 default_level: 1 的 Webhook,将其普通 URL 填入单个接收器,并删除严重级别路由。这样恢复通知也会以 high 级别到达,除非你设置 send_resolved: false。在 Alertmanager 0.32+ 上,免费套餐更适合使用上面的直接 API 配置,因为它不需要 Webhook,并且可以为每条通知设置级别。
如果没有收到任何消息
- 查看 Alertmanager 日志。 投递失败时会记录
Notify for alerts failed以及状态码。404表示 slug 错误,或者在 0.31 之前的版本上使用了模板化 URL。 - 打开 Pocket Alert 中的 Webhook 历史。 如果请求在那里,问题出在模板。如果不在,说明 Alertmanager 根本没有发送。
- 空行意味着某个路径与负载不匹配。字段名区分大小写。
- 紧挨占位符前的
%需要双写。%后面跟空格时是普通文本,因此CPU over 90% on %groupLabels.alertname%可以正常工作。当%%紧贴其他文本时需要写成%,例如%commonLabels.usage%%%。 - 在编写模板之前,使用 Webhook 测试工具捕获你的 Alertmanager 实际发送的内容。
常见问题
这能用于 kube-prometheus-stack 吗?
可以。接收器是普通的 Alertmanager 配置,因此像其他接收器一样放入 chart 的 Alertmanager 配置中即可。在使用模板化 URL 或 payload 之前,请先确认该 chart 部署的是哪个 Alertmanager 版本。集群相关内容见 Kubernetes 告警。
我用的是 Grafana 告警,而不是 Alertmanager,有什么不同?
Grafana 会发送它自己的 Webhook 格式。请参阅 Grafana 指南。
创建免费账户,运行脚本,将三个 slug 填入 alertmanager.yml,下一次 InstanceDown 就会到达你的手机。