返回博客

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

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

Webhookdefault_level接收内容
Prometheus critical2(critical)带有 severity="critical" 的触发中告警组
Prometheus warning0(默认)所有其他触发中的告警组
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 就会到达你的手机。

分享这篇文章