OneUptime 接入 Prometheus Alertmanager:把告警变成事件并触发值班升级的完整指南
OneUptime 接入 Prometheus Alertmanager:把告警变成事件并触发值班升级的完整指南
Prometheus 负责评估告警规则,Alertmanager 负责路由与去重,而 OneUptime 负责把这套告警链路变成可追踪、可升级、可自动恢复的事件(Incident)。本文基于 OneUptime 官方文档(prometheus-alertmanager.md),完整讲解两种接入方式:推荐的**入站请求监控器(Incoming Request Monitor)**与灵活的 Workflow + Webhook 触发器,并覆盖分组规则、事件模板、死亡开关与故障排查。读完你可以直接把 Alertmanager 的 webhook 指向 OneUptime,实现"每一条告警一个事件、恢复自动关闭、值班人员被自动通知"的生产级告警闭环。
集成概览:告警如何流进 OneUptime
这条集成是**入站(inbound)**方向,核心数据流如下:
Prometheus rule fires ──► Alertmanager webhook receiver ──► OneUptime ──► Incident + on-call
Prometheus 根据告警规则产生告警,Alertmanager 对告警做分组、抑制、静默后,通过 webhook receiver 把告警通知以 JSON POST 到 OneUptime;OneUptime 按监控器配置的 Criteria 判定后创建事件并触发值班(On-Call)升级。
官方提供了两种构建方式,适用场景完全不同:
| 方式 | 何时使用 |
|---|---|
| Incoming Request 监控器(推荐) | 你希望告警变成事件:带值班升级、每条告警一个事件、恢复时自动解决。无需维护任何自定义逻辑。 |
| Workflow + Webhook 触发器 | 你需要 OneUptime 原生不提供的路由逻辑——调用其他系统、改造 payload、条件分支等。 |
判断依据很简单:只做"告警 → 事件"就选方案一;需要编排逻辑就选方案二。
前置条件
在动手之前,确认以下三条都满足:
- 有一套可以编辑
alertmanager.yml的 Prometheus + Alertmanager 环境; - Alertmanager 能够通过 HTTPS 访问你的 OneUptime 实例;
- 有一个可以创建监控器(或 Workflow)的 OneUptime 项目。
方案一:Incoming Request 监控器(推荐)
Incoming Request 监控器本身只有"接收 HTTP 请求并评估 Criteria"这一个职责,但通过不同 Criteria 组合可以覆盖两种截然不同的任务:心跳监控(请求停止到达即告警)与接收外部告警系统推送(如本文的 Alertmanager)。二者使用同一监控器类型,差别只在 Criteria 配置上(见 incoming-request-monitor.md)。
步骤 1:创建监控器并获取接收 URL
- 进入 监控器(Monitors)→ 创建监控器(Create Monitor),选择 入站请求(Incoming Request);
- 打开监控器,点击左侧菜单的 Documentation,复制接收 URL:
https://oneuptime.com/heartbeat/YOUR_SECRET_KEY
如果自托管(self-hosted),请把主机名换成你自己的实例地址。路径中的 Secret Key 是唯一的凭据——不需要 Header 或 Token。因此务必把它当作机密对待:任何知道该 URL 的人都能把监控器标记为健康。
值得注意:OneUptime 会对每个请求先返回一个空的
200,随后才在队列里处理。这个200是在任何校验之前写出的,所以收到200不代表 payload 被接受——错误的 Secret Key、已删除/已禁用的监控器同样返回200。要确认请求真的落地,请查看监控器自己的时间线(timeline)。
步骤 2:把 Alertmanager 指向这个 URL
编辑 alertmanager.yml,新增一个 webhook receiver 并配置默认路由:
receivers:
- name: oneuptime
webhook_configs:
- url: "https://oneuptime.com/heartbeat/YOUR_SECRET_KEY"
send_resolved: true
route:
receiver: oneuptime
group_by: ["alertname", "instance"]
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
两个关键点:
send_resolved: true是必需的——正是它告诉 OneUptime 某条告警已恢复(resolved),事件才能被自动关闭。没有它,恢复通知永远不会发出来。- Alertmanager 会发送
Content-Type: application/json,这是 OneUptime 从 payload 中读取字段(如requestBody.status)的前提。根据 incoming-request-monitor.md 的说明,只有application/json(以及扁平化解析的application/x-www-form-urlencoded)会被解析;其他 Content-Type 不会被解析,所有requestBody引用都会落空。
改完配置后重新加载 Alertmanager:
curl -X POST http://localhost:9093/-/reload
或者直接重启 Alertmanager。
步骤 3:配置 Criteria(过滤器、动作与事件分组)
打开监控器的 Criteria(条件),编辑第一个条件。
过滤器(Filter)
- Filter Type:
JavaScript Expression - Filter Condition:
Evaluates To True - Value:
"{{requestBody.status}}" === "firing"
占位符两边的引号是做字符串比较所必需的。如果你不想写表达式,也可以用 Request Body / Contains / "status":"firing" 过滤器——注意这里的匹配是紧凑 JSON 的子串匹配,必须写成不带空格的 "status":"firing",从美化打印的 payload 里复制的 "status": "firing" 永远不会命中(见 incoming-request-monitor.md 的说明)。
动作(Actions)
- 打开 When filters match, change monitor status(过滤器匹配时更改监控器状态),设为 Offline(或 Degraded);
- 打开 When filters match, declare an incident(过滤器匹配时声明事件),填写 标题(Title)、严重级别(Severity) 以及需要通知的 On-Call 值班策略(On-Call Policies);
- 在事件的 Advanced Options(高级选项) 下打开 Auto Resolve Incident(自动解决事件)。不开它,恢复通知会被忽略,事件将永远保持打开。
Settings → Group incidents and alerts by a payload field(按 payload 字段分组事件与告警)
打开它,让同一个 endpoint 能容纳多个并行事件——每条告警一个事件,而不是每条通知一个事件:
| 字段 | 值 |
|---|---|
| Open a separate incident for each…(为每个…打开独立事件) | requestBody.alerts[*].fingerprint |
| Field that signals recovery(表示恢复的字段) | requestBody.alerts[*].status |
| Value that means recovered(表示已恢复的值) | resolved |
| Max incidents per request(每个请求的最大事件数) | 100 |
[*] 会展开 Alertmanager 的 alerts 数组,为每个去重后的提取值打开一个事件。由于两个路径都使用了 [*],恢复是按单条告警判定的:在一个 payload 中,如果一条告警已 resolved、两条仍在 firing,则只关闭已恢复的那条。
Warning(关键陷阱): 分组必须依据对每条告警真正唯一的字段。Alertmanager 的
fingerprint是告警完整标签集的哈希,天然唯一。而标签只有当它在单次通知内部变化时才有效——任何出现在你路由group_by里的标签都永远不会变化,因为那恰恰就是聚合组的定义。以上面的group_by: ["alertname", "instance"]为例,如果按requestBody.alerts[*].labels.alertname分组,会从 payload 里每条告警提取出相同值,所有告警塌缩成一个事件。更糟的是,重复值只保留第一次出现的记录,所以若 payload 中第一条告警是resolved,它会关闭整个事件,而其余告警其实还在 firing。
步骤 4:编写事件标题与描述
分组键会作为一个变量暴露出来,变量名取自路径的最后一段:requestBody.alerts[*].fingerprint 给你 {{fingerprint}}。但 fingerprint 是哈希,不适合展示给值班人员——应该用通知内共享的 labels 来命名事件。commonLabels 携带你路由 group_by 中的每一个 label,因此按上面的配置,alertname 和 instance 都可直接用:
-
Title:
{{requestBody.commonLabels.alertname}} on {{requestBody.commonLabels.instance}} -
Description:
{{requestBody.commonAnnotations.summary}} {{requestBody.commonAnnotations.description}} Severity: {{requestBody.commonLabels.severity}} Alertmanager: {{requestBody.externalURL}}
要点与限制:
commonLabels与commonAnnotations存放的是通知内共享的字段;- 形如
requestBody.alerts[0].annotations.summary的按告警路径,永远只读取 payload 中的第一条告警,而不是为该事件打开的那一条——所以如果希望每个事件携带各自的注解文本,务必把group_by收紧; - 无法解析的路径会原样输出,包括花括号本身,而不是留空。想查全部可用变量,见 Incident & Alert Dynamic Templating(事件与告警动态模板)。
步骤 5:(可选)把监控器恢复到 Operational
Criteria 只在匹配时生效,所以请新增第二个条件,避免一切平息后监控器一直停留在 Offline:
- Filter Type:
JavaScript Expression,Value:"{{requestBody.status}}" === "resolved" - 动作设为 Change monitor status to Operational(将监控器状态更改为 Operational),并且不创建事件。
步骤 6:测试整个链路
先用 curl 模拟一条带两条告警的 Alertmanager 通知:
curl -X POST https://oneuptime.com/heartbeat/YOUR_SECRET_KEY \
-H "Content-Type: application/json" \
-d '{
"version": "4",
"status": "firing",
"commonLabels": { "alertname": "HighCPU", "severity": "critical" },
"commonAnnotations": { "summary": "CPU above 90% for 5m" },
"externalURL": "http://alertmanager:9093",
"alerts": [
{
"status": "firing",
"labels": { "alertname": "HighCPU", "instance": "web-1" },
"fingerprint": "a1b2c3d4e5f60001"
},
{
"status": "firing",
"labels": { "alertname": "HighCPU", "instance": "web-2" },
"fingerprint": "a1b2c3d4e5f60002"
}
]
}'
预期结果:得到两个事件,每个 fingerprint 一个。把两个告警的 status 都改成 resolved 重发一次,两个事件都应关闭。
也可以用 amtool 从 Alertmanager 侧触发一条真实告警:
amtool alert add test_alert severity=warning \
--annotation=summary="Test from Alertmanager" \
--alertmanager.url=http://localhost:9093
方案二:Workflow + Webhook 触发器
当你需要"告警变事件"之外的逻辑(调用第三方系统、改造 payload、条件分支)时,用 Workflow 更合适。步骤:
- 打开 工作流(Workflows)→ 创建工作流(Create Workflow),命名为
Alertmanager → Incidents,进入 Builder(构建器); - 添加一个 Webhook 触发器并复制其 URL,把该块重命名为
Alertmanager; - 添加一个连接到触发器的 Conditions(条件) 块:
- Left:
{{Alertmanager.Request Body.status}} - Operator:
== - Right:
firing
- Left:
- 从 Yes 分支添加 Create Incident(创建事件) 块:
- Titel(标题):
{{Alertmanager.Request Body.commonAnnotations.summary}} - Beskrivelse(描述):
{{Alertmanager.Request Body.commonAnnotations.description}}\nAlert: {{Alertmanager.Request Body.commonLabels.alertname}} - Alvorlighed(严重级别):选择一个(或者先按
{{Alertmanager.Request Body.commonLabels.severity}}分支);
- Titel(标题):
- 保存,然后把上面方案一步骤 2 中
webhook_configs的 URL 改成这个 Workflow 的 URL。
如需"每条告警一个事件",添加一个 Custom Code(自定义代码) 块遍历 Request Body.alerts;配合 send_resolved: true,再加一个 status == resolved 的 Conditions 分支,用 Update Incident(更新事件) 找到匹配事件并移动到你的已解决状态。
死亡开关(Dead Man's Switch):探测 Prometheus 本身的故障
两种方案都有同一个盲区:当 Prometheus 自己挂掉时,不会有任何告警到达——"没有告警"看起来和"一切正常"一模一样。常规做法是一条永远触发的告警,路由到一个按计划等待它的监控器上。
- 使用 kube-prometheus-stack 时,它自带一个叫
Watchdog的告警; - 普通 Prometheus 上,添加一条表达式恒为真(
vector(1))的告警规则即可。
然后创建第二个 Incoming Request 监控器,把 Watchdog 用较短的 repeat_interval 路由过去,并给该监控器配置一个 Filter Type: Incoming Request / Filter Condition: Not Recieved In Minutes(在 X 分钟内未收到请求) 的条件。这是"缺失请求"类条件唯一应该用在告警接收者上的场景——因为它探测的正是"发送方是否还活着"。
完整配置:把 watchdog 的路由与 receiver 合并进步骤 2 的配置。子路由优先于父路由自身的 receiver 匹配,所以 Watchdog 进入第二个监控器,其余告警仍走第一个:
receivers:
- name: oneuptime
webhook_configs:
- url: "https://oneuptime.com/heartbeat/YOUR_SECRET_KEY"
send_resolved: true
- name: oneuptime-watchdog
webhook_configs:
- url: "https://oneuptime.com/heartbeat/WATCHDOG_SECRET_KEY"
route:
receiver: oneuptime
group_by: ["alertname", "instance"]
group_wait: 30s
group_interval: 5m
repeat_interval: 4h
routes:
- receiver: oneuptime-watchdog
matchers:
- alertname = "Watchdog"
group_wait: 0s
group_interval: 5m
repeat_interval: 5m
最佳实践提示(见 incoming-request-monitor.md):不要把"心跳"和"接收告警"两件事混在同一个监控器上。事件驱动的告警接收者没有固定节奏,给它配 "Not Recieved In Minutes" 条件会持续抖动。死亡开关请单独使用一个监控器。
故障排查:7 个高频问题
-
什么都没进来 —— 确认 Alertmanager 能访问该 URL,查看其日志中的投递错误。OneUptime 在任何校验之前就对每个请求返回空
200,所以200不代表 payload 被接受,应查看监控器的时间线。 -
事件打开了但永远不关闭 —— 依次检查:Alertmanager 里的
send_resolved: true;Criteria 上的恢复字段与恢复值(比较区分大小写);事件 Advanced Options 里的 Auto Resolve Incident。还有两个更隐蔽的原因:- 如果 payload 携带的唯一键数量超过 Max incidents per request,超出上限的键对恢复也是不可见的;
- 如果恰好是
resolved通知被 ingest 阶段的合并丢弃(见下条),事件将永久搁浅——因为 Alertmanager 会重发 firing 通知,但不会重发 resolved 通知。这种情况只能手动关闭。
-
完全没有事件,监控器状态也不变 —— 分组路径必须以字面量
requestBody.开头,且路径中只有第一个[*]是通配符。这两种错误都会静默失败。 -
事件文本显示原始
{{...}}占位符 —— 路径没有解析成功,OneUptime 会把未解析的占位符原样保留而不是清空。不同的告警规则会设置不同的注解,请引用你的规则中真实存在的字段(commonAnnotations与按告警的annotations是两回事)。 -
payload 里一堆告警却只有一个事件 —— 你按某个在通知内部不变更的 label 分组了,最常见的原因是该 label 也出现在路由的
group_by里。请改按requestBody.alerts[*].fingerprint分组。 -
事件太多 —— 放宽
group_by/group_interval,让 Alertmanager 把相关告警合并批处理。调低 Max incidents per request 可以封顶,但同时也会把超出上限的键从恢复判定中隐藏掉。 -
高峰期部分通知像是被跳过了 —— 发往同一监控器的请求在 ingest 阶段会被合并(coalesce),防止单个发送方压垮监控器;当通知紧挨着到达时,中间的 payload 可能被丢弃。加大
group_wait和group_interval可以拉开间隔。该合并行为由应用容器的环境变量INCOMING_REQUEST_INGEST_COALESCE_ENABLED控制,默认开启;需要每条 payload 都被评估的自托管运维人员可以在该容器上把它设为false。
这个环境变量的实现可以在仓库中直接验证:配置解析位于 App/FeatureSet/Telemetry/Config.ts,逻辑是"只要环境变量不等于字符串 false 就启用";实际合并行为发生在 Telemetry 队列服务的 ingest 阶段(App/FeatureSet/Telemetry/Services/Queue/TelemetryQueueService.ts)。因此,除非你确实需要每条 payload 都被逐条评估,否则保持默认开启即可获得更好的抗突发能力。
深入阅读
- Incoming Request Monitor(入站请求监控器) —— 该监控器类型的完整文档:请求 URL 规范、全部 Filter Type 与 Filter Condition、事件分组路径语法与恢复的事件驱动语义;
- Integrations Overview(集成总览) —— 入站与出站集成模式全览;
- Grafana 集成 —— 同一思路,面向 Grafana 告警;
- Webhook 触发器 —— Workflow 接收 URL 的工作原理;
- Incident & Alert Dynamic Templating —— 事件标题与描述可用的全部变量;
- JavaScript Expressions —— 表达式语法与引号规则。