OneUptime 接入 Prometheus Alertmanager:把告警变成事件并触发值班升级的完整指南

原创2026-09-16 13:17:002,129 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

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、条件分支等。

判断依据很简单:只做"告警 → 事件"就选方案一;需要编排逻辑就选方案二。

前置条件

在动手之前,确认以下三条都满足:

  1. 有一套可以编辑 alertmanager.yml 的 Prometheus + Alertmanager 环境;
  2. Alertmanager 能够通过 HTTPS 访问你的 OneUptime 实例;
  3. 有一个可以创建监控器(或 Workflow)的 OneUptime 项目。

方案一:Incoming Request 监控器(推荐)

Incoming Request 监控器本身只有"接收 HTTP 请求并评估 Criteria"这一个职责,但通过不同 Criteria 组合可以覆盖两种截然不同的任务:心跳监控(请求停止到达即告警)与接收外部告警系统推送(如本文的 Alertmanager)。二者使用同一监控器类型,差别只在 Criteria 配置上(见 incoming-request-monitor.md)。

步骤 1:创建监控器并获取接收 URL

  1. 进入 监控器(Monitors)→ 创建监控器(Create Monitor),选择 入站请求(Incoming Request);
  2. 打开监控器,点击左侧菜单的 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 更合适。步骤:

  1. 打开 工作流(Workflows)→ 创建工作流(Create Workflow),命名为 Alertmanager → Incidents,进入 Builder(构建器);
  2. 添加一个 Webhook 触发器并复制其 URL,把该块重命名为 Alertmanager;
  3. 添加一个连接到触发器的 Conditions(条件) 块:
    • Left:{{Alertmanager.Request Body.status}}
    • Operator:==
    • Right:firing
  4. 从 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}} 分支);
  5. 保存,然后把上面方案一步骤 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 都被逐条评估,否则保持默认开启即可获得更好的抗突发能力。

深入阅读

登录后查看全文
oneuptime