OneUptime 集成 Prometheus Alertmanager:把告警转成带值班升级与自动恢复的 Incident 完整实战指南
OneUptime 集成 Prometheus Alertmanager:把告警转成带值班升级与自动恢复的 Incident 完整实战指南
导读
本篇技术指南讲解如何将 Prometheus Alertmanager 的通知接入 OneUptime,让告警自动落地为 Incident(事件),并触发值班(On-Call)升级、在恢复时自动关闭事件。文章以 OneUptime 官方集成为骨架,提供入站请求监控器(Incoming Request Monitor)与工作流(Workflow)Webhook两种完整可复制的实现方案,并补充源码级的底层原理解读。读完你将掌握:alertmanager.yml 的接收器(receiver)配置、监控器条件(Criteria)与按告警分组(incident grouping)的写法、标题/描述的动态模板语法、死手开关(dead man's switch)的搭建,以及 6 类常见故障的定位方法。
集成概览:两种接入方式的选型
Prometheus 负责评估告警规则,Alertmanager 负责路由与去重,OneUptime 负责把最终的通知记录为 Incident 并执行升级。这是一条**入站(inbound)**集成链路:
Prometheus rule fires ──► Alertmanager webhook receiver ──► OneUptime ──► Incident + on-call
OneUptime 为该集成提供了两种构建方式,选型依据如下:
| 方式 | 适用场景 |
|---|---|
| 入站请求监控器(Incoming Request Monitor,推荐) | 希望告警变成带值班升级的 Incident、一个告警对应一个事件、恢复后自动关闭;无需维护任何自定义逻辑 |
| 工作流(Workflow)+ Webhook 触发器 | 需要 OneUptime 原生不提供的路由逻辑——调用其他系统、改写负载(payload)、做条件分支 |
两种方式复用同一条通知链路,区别只在 OneUptime 侧的处理逻辑。下文按官方文档顺序分别展开。
前提条件
在开始之前,确认以下三件事:
- 有一套可以编辑
alertmanager.yml的 Prometheus + Alertmanager 环境; - Alertmanager 能够通过 HTTPS 访问到你的 OneUptime 实例(自托管时请使用自己的主机名);
- 有一个可以创建监控器(或工作流)的 OneUptime 项目。
方式一:入站请求监控器(推荐)
入站请求监控器会为你的监控器生成一个唯一 URL,其他系统向该 URL 发送 HTTP 请求,OneUptime 对每次请求按你的条件进行评估,进而改变监控器状态、声明 Incident 并呼叫值班人员。它同时覆盖两种职责:心跳监控(定时 ping,停止即报警)与接收外部系统告警(Prometheus Alertmanager、Grafana 等 POST JSON 进来转成 Incident)。详见 入站请求监控器文档。
第 1 步:创建监控器
-
进入 Monitors → Create Monitor,选择 Incoming Request 类型;
-
打开该监控器,点击左侧菜单的 Documentation,复制给出的 URL:
https://oneuptime.com/heartbeat/YOUR_SECRET_KEY自托管时替换为你自己的主机名。路径中的 Secret Key 是唯一的凭据——不需要任何 Header 或 Token。
从 OneUptime 侧看,这条 URL 的语义很直接:任何人只要知道该 URL 就能把监控器标记为健康,因此必须像对待密码一样保管它。此外,发送到该端点的每个 Header 都会被存储在监控器上,任何能读取监控器的人都能看到,切勿在 Header 中携带 API Key 或 Token。
第 2 步:把 Alertmanager 指向该 URL
在 alertmanager.yml 中配置:
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 读取负载字段所必需的格式(详见后文“请求体解析”)。
修改配置后,用以下命令热重载 Alertmanager(或直接重启进程):
curl -X POST http://localhost:9093/-/reload
第 3 步:配置监控器条件(Criteria)
打开监控器的 Criteria,编辑第一条条件。
Filter(过滤器)
- Filter Type:
JavaScript Expression - Filter Condition:
Evaluates To True - Value:
"{{requestBody.status}}" === "firing"
占位符两侧的引号是字符串比较所必需的。如果不想写表达式,使用 Request Body / Contains / "status":"firing" 过滤器同样可行。
Actions(动作)
- 开启 When filters match, change monitor status,设置为 Offline(或 Degraded)。
- 开启 When filters match, declare an incident,填写 Title、Severity 以及需要被呼叫的 On-Call Policies。
- 在该事件(Incident)的 Advanced Options 下,开启 Auto Resolve Incident。不开启它,恢复通知会被忽略,事件将永远保持打开状态。
Settings → Group incidents and alerts by a payload field(按负载字段分组)
开启该选项后,同一个端点可以同时承载多个并发事件——每个告警一个事件,而不是每次通知只产生一个事件。配置项如下:
| 字段 | 值 |
|---|---|
| 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 数组,为每个去重后的取值各打开一个事件。因为分组键与恢复字段两个路径都用了 [*],恢复判断是逐条告警进行的:在一个负载里,若一条告警已 resolved、另外两条仍 firing,则只有 resolved 的那条对应事件会被关闭。
警告:务必按每条告警真正唯一的字段分组。 Alertmanager 的
fingerprint是告警完整标签集合的哈希值,因此它天然唯一。而某个标签只有在同一条通知内部发生变化时才能用作分组键——凡是出现在路由group_by中的标签永远不会变化,因为它恰恰定义了聚合组。以上面的group_by: ["alertname", "instance"]为例,如果按requestBody.alerts[*].labels.alertname分组,负载中每条告警都会提取出相同的值,所有告警会坍缩成一个事件;更糟的是,重复值只保留第一次出现,若负载中第一条告警是resolved,该事件会被关闭,而其余告警仍在 firing。
源码印证:在 IncomingRequestIncidentGrouping.ts 的 extractItems 实现中,可以看到 [*] 通配符(ARRAY_WILDCARD)只取路径中的第一处出现,去重通过 seenFingerprints 集合完成(“Same key twice in one payload — keep the first occurrence”),单请求最多提取的键数由 DEFAULT_MAX_KEYS_PER_PAYLOAD = 100 兜底,这些都与文档中“仅保留第一次出现”“Max incidents per request 上限”的描述一一对应。
第 4 步:编写事件标题与描述
分组键会以“路径最后一段”命名暴露为变量,因此 requestBody.alerts[*].fingerprint 会给你 {{fingerprint}}。但 fingerprint 是哈希值,不适合直接展示给值班人员——标题应使用整条通知共享的标签。commonLabels 携带路由 group_by 中的全部标签,所以按上文配置,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)永远读的是负载里的第一条告警,而不是为该事件打开的那个具体告警——因此若希望每个事件携带各自的注释文本,务必保持group_by紧致(分组维度少而稳定); - 无法解析的路径会原样输出(连花括号一起),而不是留空——排查时看到字面量
{{...}}就说明路径写错了; - 完整变量清单参见 Incident & Alert 动态模板文档。
第 5 步:让监控器恢复 Operational(可选)
条件只在“匹配”时生效,因此需要追加第二条条件,避免一切恢复正常后监控器停留在 Offline:
- Filter Type:
JavaScript Expression,Value:"{{requestBody.status}}" === "resolved" - Change monitor status to Operational,且不声明任何事件。
第 6 步:测试
先模拟一条含两条告警的 firing 通知:
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 触发一条真实告警来做端到端验证:
amtool alert add test_alert severity=warning \
--annotation=summary="Test from Alertmanager" \
--alertmanager.url=http://localhost:9093
请求体解析的底层细节
为什么必须发送 application/json?这与 OneUptime 的负载解析逻辑直接相关。从 IncomingRequestCriteria.ts 与 IncomingRequestIncidentGrouping.ts 的实现看:请求体要么已被解析为 JSON 对象,要么是原始 JSON 字符串,getRequestBodyObject 会尝试 JSON.parse;只有 application/json(或可被解析的 JSON 文本)才能得到结构化对象,requestBody.* 引用才有值。此外,application/x-www-form-urlencoded 的请求体也会被解析,但只会被展平成顶层字段;其他或缺失的 Content-Type 不会被解析,所有 requestBody 引用都解析为空。请求体上限为 50 MB,且不要用 Content-Encoding: gzip 压缩——压缩后的请求体会被原样存储,路径无法解析。
关于 200 响应的重要认知
OneUptime 在任何校验之前就会对每次请求立即返回一个空的 200,然后才把请求放入队列处理。因此 200 并不能证明负载被接受——错误的 Secret Key、已删除的监控器、被禁用的监控器同样返回 200。确认请求是否真正落地的唯一方式是查看监控器自身的 Timeline。
方式二:工作流(Workflow)Webhook
当需求超出“一条告警变成一个事件”时使用工作流。工作流是 OneUptime 的无代码自动化画布:一个触发器决定何时运行,若干组件(component)执行动作,连线决定执行顺序。详见 工作流概览 与 触发器文档。
- 打开 Workflows → Create Workflow,命名为
Alertmanager → Incidents,进入 Builder; - 添加 Webhook 触发器并复制其 URL,将块重命名为
Alertmanager; - 添加一个 Conditions 块,连接到触发器:
- Left:
{{Alertmanager.Request Body.status}} - Operator:
== - Right:
firing
- Left:
- 从 Yes 分支添加 Create Incident 块:
- Title:
{{Alertmanager.Request Body.commonAnnotations.summary}} - Description:
{{Alertmanager.Request Body.commonAnnotations.description}}\nAlert: {{Alertmanager.Request Body.commonLabels.alertname}} - Severity:直接选一个(或先按
{{Alertmanager.Request Body.commonLabels.severity}}分支)
- Title:
- 保存,然后把第 2 步里
webhook_configs的 URL 指向工作流的接收 URL。
工作流的 Webhook 触发器同样只认 URL 本身,任何拿到该 URL 的人都能启动工作流,因此也要视为密码。请求的 Header、Query 参数与 Body 会作为触发器输出传给后续块(Request Headers、Request Query Params、Request Body),调用方会立刻收到一个快速确认,工作流本身在后台运行。
按告警拆分的进阶做法:若需要一个告警对应一个事件,可添加一个 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))的告警规则即可。
具体配置:创建第二个入站请求监控器,把 Watchdog 以较短的 repeat_interval 路由过去,并给该监控器配置 Filter Type: Incoming Request / Filter Condition: Not Recieved In Minutes 的条件。这是“缺请求”条件唯一适合用在告警接收端的地方——其余情况下它都会因正常的告警沉寂而产生误报。
把第 2 步的配置扩展为同时包含 watchdog 路由与接收器(子路由会先于父路由自身的接收器被匹配,因此 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
故障排查(Troubleshooting)
按现象逐条对照,是快速定位的关键:
- 什么也没到达——确认 Alertmanager 能访问该 URL,并查看其日志中的投递错误。记住 OneUptime 在验证前就返回空
200,200不代表被接受,请查看监控器的 Timeline。 - 事件打开了但永远不关闭——依次检查 Alertmanager 的
send_resolved: true、条件上的恢复字段与恢复值(比较是大小写敏感的)、事件 Advanced Options 里的 Auto Resolve Incident。两个更隐蔽的原因:负载中不同的键数超过 Max incidents per request 时,超出上限的那些键同样无法被恢复;以及若那条resolved通知恰好被摄取合并(见下文)丢弃,事件会被永久搁浅——因为 Alertmanager 会重复发送 firing 通知,却不会重复发送 resolved 通知。这类事件需要手动关闭。 - 完全没有事件,监控器状态也没变——分组路径必须以字面量
requestBody.开头,且一条路径中只有第一个[*]是通配符。这两种错误都会静默失败。 - 事件文本显示原始
{{...}}占位符——路径未解析成功,OneUptime 会把未解析的占位符原样保留而不是清空。不同规则设置的注释字段不同(commonAnnotations与单条告警的annotations),请引用你的规则中真实存在的字段。 - 一条负载只产生一个事件——你按一个在同一条通知内部不变化的标签分组了,最常见的是它也出现在路由的
group_by里。改为按requestBody.alerts[*].fingerprint分组。 - 事件太多——放宽
group_by/group_interval,让 Alertmanager 把相关告警合并成批次。调低 Max incidents per request 能限制数量,但同样会让超出上限的键无法被恢复。 - 高突发时部分通知看起来被跳过——发往同一监控器的请求会在摄取入口被合并(coalesced),防止单个发送方压垮监控器;当通知背靠背到达时,中间负载可能被丢弃。增大
group_wait与group_interval可以让它们错开。合并行为由应用容器的INCOMING_REQUEST_INGEST_COALESCE_ENABLED环境变量控制(默认开启),自托管运维方若需要逐条评估每条负载,可在该容器上将其设为false。该变量在仓库中的定义位于 Telemetry/Config.ts。
延伸阅读
- 入站请求监控器——该监控器类型的完整说明、全部 Filter Type 与事件分组机制;
- Incident & Alert 动态模板——
requestBody.*变量全表; - 集成总览——入站/出站两种集成模式;
- Grafana 集成——同样的思路,对接 Grafana Alerting;
- Webhook 触发器——工作流接收 URL 的工作原理与输出变量。