OneUptime Incoming Request Monitor 完整实战指南:心跳监控、死键检测与 Alertmanager/Grafana 告警接入
OneUptime Incoming Request Monitor 完整实战指南:心跳监控、死键检测与 Alertmanager/Grafana 告警接入
Incoming Request Monitor(入站请求监控)是 OneUptime 平台中一种特殊的监控类型:它不是让 OneUptime 主动探测你的服务,而是提供一个唯一 URL,让你自己的系统(cron 任务、后台 Worker、防火墙内服务、Prometheus Alertmanager、Grafana 等)主动向它发送 HTTP 请求。OneUptime 会依据你配置的监控标准(Criteria)对每一次入站请求进行评估,进而切换监控状态、开启事件(Incident)并触发值班轮换。读完本文,你将掌握 Incoming Request Monitor 的完整配置方法、请求地址与请求体规范、监控标准(Filter Type / Filter Condition / Value)的语义与源码级实现原理,以及如何借助事件分组(Incident Grouping)将 Alertmanager/Grafana 的多条告警映射为独立事件。
概述:两种截然不同的用途,同一种监控类型
Incoming Request Monitor 同时覆盖两类差异很大的场景,而它们共用同一个监控类型,区别只在于你配置的监控标准:
- 心跳监控(Heartbeat Monitoring)——定时任务、Worker 或设备按固定时间表 ping 一个 URL;当 ping 停止时,OneUptime 触发事件。典型场景包括:跟踪定时任务与 cron 任务、确认后台 Worker 是否存活、监控位于防火墙之后从外部不可达的服务。
- 接收其他系统的告警(Alert Ingestion)——Prometheus Alertmanager、Grafana 或任何能发送 JSON POST 的系统把告警推送到该 URL,OneUptime 将每条告警转换为一个事件,并支持值班升级(Escalation)与自动恢复(Auto Resolve)。
从代码层面看,这两类场景最终都落入同一条入站请求处理链路:Probe 侧的 Probe/API/IncomingRequestIngress.ts 接收 /heartbeat/:secretkey 与 /incoming-request/:secretkey 路由(GET/POST 均注册),转发到 OneUptime 后端;后端再交由 Common/Server/Utils/Monitor/Criteria/IncomingRequestCriteria.ts 依据监控标准逐条评估。
创建 Incoming Request Monitor
在 OneUptime 仪表盘中按以下步骤创建:
- 进入 Monitors 页面
- 点击 Create Monitor
- 监控类型选择 Incoming Request
- OneUptime 会为这个监控生成一个 Secret Key 和一个专属地址
- 打开该监控,在左侧菜单点击 Documentation,复制该地址
- 将你的服务配置为向该地址发送请求
- 按下方说明配置监控标准
创建完成后,监控状态与事件流转完全由入站请求驱动:请求内容决定在线/降级/离线状态,请求缺失(Dead Man's Switch 场景)则由时间窗口标准触发。
请求地址解析:路径、方法与响应语义
每个 Incoming Request Monitor 拥有一个唯一地址,格式如下:
https://oneuptime.com/heartbeat/YOUR_SECRET_KEY
如果你自托管(Self-Hosted)OneUptime,请将 https://oneuptime.com 替换为你自己实例的地址。
HTTP 方法与认证
- 支持向该地址发送 GET 或 POST 请求;HEAD 也会被接受,并如同 GET 一样处理;其他 HTTP 方法一律返回 404。
- Secret Key 是唯一的凭据,直接放在 URL 路径中——不需要任何 Header 或 Token。这从路由注册中可以得到印证:Probe 入口同时注册了
router.post("/incoming-request/:secretkey", ...)与router.get("/incoming-request/:secretkey", ...)(见 Probe/API/IncomingRequestIngress.ts)。
安全警告:任何知道该 URL 的人都可以把你的监控标记为“在线”,所以请像对待密钥一样对待它。此外,你发送的所有 Header 都会被存储在监控上,任何能读取该监控的人都可见——绝对不要把 API Key 或 Token 放在 Header 中发送到这个端点。
关于 200 响应的重要语义
OneUptime 会立即返回一个空的 200,并把请求放入处理队列。这个响应在任何校验之前就已写出,因此:
200并不代表请求已被接受;- 即使 Secret Key 错误、监控已被删除或监控处于禁用状态,也都会返回
200。
要确认请求是否真正到达,请查看监控自身的时间线(Timeline)。这一“先响应、后处理”的设计在 Probe 转发实现中同样可见:forwardToOneUptime 在 Response.sendEmptySuccessResponse 之后才异步执行 forwardWithRetry(带指数退避重试),确保客户端感知到的延迟极低。
发送请求体(Request Body)
如果你需要寻址请求体内部的字段——例如在事件标题中使用 {{requestBody.status}}、在事件分组中使用 JSON 路径、或使用 JavaScript 表达式类型的标准——请发送 Content-Type: application/json。本文档中的所有示例均基于这一格式。
application/x-www-form-urlencoded的请求体也会被解析,但只会解析顶层扁平字段。- 其他任何 Content-Type、或完全没有 Content-Type 的请求,请求体不会被解析,所有
requestBody引用都会解析为空。 - 请求体最大接受 50 MB。
- 不要使用
Content-Encoding: gzip压缩请求体——它会以未解析的状态被存储,内部的路径也无法解析。
从源码看,请求体最终以 requestBody?: string | JSONObject | undefined 的形式进入评估层(见 Common/Types/Monitor/IncomingMonitor/IncomingMonitorRequest.ts),评估时字符串类型的 body 会被 JSON.stringify 归一化后参与比较。
发送心跳:curl、cron 与程序代码
使用 curl
# Simple GET request
curl https://oneuptime.com/heartbeat/YOUR_SECRET_KEY
# POST request with custom body
curl -X POST https://oneuptime.com/heartbeat/YOUR_SECRET_KEY \
-H "Content-Type: application/json" \
-d '{"status": "healthy", "version": "1.2.3"}'
从 cron 任务发送
# Add to crontab to send heartbeat every 5 minutes
*/5 * * * * curl -s https://oneuptime.com/heartbeat/YOUR_SECRET_KEY > /dev/null
从程序代码发送
// Node.js example
const https = require("https");
https.get("https://oneuptime.com/heartbeat/YOUR_SECRET_KEY");
# Python example
import requests
requests.get('https://oneuptime.com/heartbeat/YOUR_SECRET_KEY')
监控标准(Criteria):如何判定在线、降级与离线
你可以配置多条监控标准,以决定你的服务何时被视为在线(Online)、降级(Degraded)或离线(Offline)。每条过滤标准由三部分组成:
- Filter Type(看什么)——检查对象
- Filter Condition(怎么比)——比较方式
- Value(比较值)——阈值或匹配内容
新监控自带的默认标准
新建的 Incoming Request Monitor 会自带两条基于请求体的标准:
| 标准 | 过滤类型 | 过滤条件 | 值 | 效果 |
|---|---|---|---|---|
| Offline | Request Body | Contains | error |
将监控标记为离线,并打开一个事件 |
| Online | Request Body | Not Contains | error |
将监控标记为在线 |
这套默认配置覆盖了最常见的场景:发送方在负载(Payload)中自报健康状况——请求体包含 error 的请求会让监控离线,下一条不含 error 的请求则会把它恢复在线。完全没有请求体的请求会被视为“不包含 error”,所以单纯的心跳 ping 也能让监控保持在线。
请把值改成你的发送方实际发出的内容(例如 "status":"firing"、FAILED 等)——匹配是区分大小写的子串匹配。
注意:这些默认标准不是死键(Dead Man's Switch)。当请求停止到达时,这里没有任何标准会触发。如果你想针对“沉默”告警,需要按下方说明添加一条 Incoming Request 类型的
Not Recieved In Minutes标准。
可用的 Filter Type 一览
| 过滤类型 | 检查什么 | 备注 |
|---|---|---|
| Incoming Request | 在某个时间窗口内是否收到了请求 | 唯一能在“没有请求到达”时触发的检查类型 |
| Request Body | 请求体 | 子串匹配。对象型请求体按压缩后的 JSON 比较 |
| Request Header | 请求中的 Header 名称 | 与 Header 名称精确匹配,且转为小写 |
| Request Header Value | 请求中 Header 的值 | 与 Header 值精确匹配,且转为小写 |
| JavaScript Expression | 针对 requestBody 与 requestHeaders 的任意表达式 |
最灵活的选择——参见 JavaScript 表达式文档 |
Filter Condition 一览
每种 Filter Type 提供各自的条件集合。
Incoming Request(按仪表盘中的拼写呈现):
- Recieved In Minutes——在指定分钟数内收到了请求
- Not Recieved In Minutes——在指定分钟数内未收到任何请求
Request Body、Request Header 与 Request Header Value:Contains 和 Not Contains。
JavaScript Expression:Evaluates To True。
注意:Header 名称与值在比较前都会转为小写,且匹配是针对完整名称或值,而非子串。请写
content-type而不是Content-Type,写application/json而不是application/JSON。只有 Request Body 是真正的子串匹配。
对象型请求体按去空格压缩后的 JSON 进行比较,因此 Request Body / Contains 过滤必须写成 "status":"firing"——直接复制美化后(pretty-printed)负载中的 "status": "firing" 永远不会匹配。
源码级的匹配实现
这些语义在 Common/Server/Utils/Monitor/Criteria/IncomingRequestCriteria.ts 中逐条实现,可作为你编写标准的“行为契约”:
- Recieved In Minutes / Not Recieved In Minutes:用
incomingRequestReceivedAt(最近一次请求到达时间)与checkedAt计算分钟差,differenceInMinutes <= value时 Recieved 命中,differenceInMinutes > value时 Not Recieved 命中。 - Request Body:空请求体被归一化为
""(而不是“未知”),这正是默认 Online 标准(Not Containserror)能让无请求体的心跳 ping 命中的根本原因;Contains 不受影响(空字符串不含任何内容)。 - Request Header / Request Header Value:比较时两侧都转小写,且是数组级别的整体包含判断(
headerKeys.includes(...)/headerValues.includes(...)),即精确匹配而非子串。 - 相关的枚举定义(
CheckOn、FilterType)集中在 Common/Types/Monitor/CriteriaFilter.ts,其中IncomingRequest = "Incoming Request"、RequestBody = "Request Body"、RequestHeader = "Request Header"、RequestHeaderValue = "Request Header Value"、JavaScriptExpression = "JavaScript Expression",NotRecievedInMinutes/RecievedInMinutes也在此定义。
标准配置示例
10 分钟没有心跳即标记离线(死键)
- Filter Type: Incoming Request
- Filter Condition: Not Recieved In Minutes
- Value: 10
依据请求体内容标记降级
- Filter Type: Request Body
- Filter Condition: Contains
- Value:
"status":"degraded"
警告:一个监控只有在至少一条标准检查 Incoming Request 时,才会在后台被重新评估。如果监控的标准只检查 Request Body、Request Header 或 JavaScript 表达式,它只会在有请求到达时被评估,其他时间一概不会——因此它永远无法自行离线。如果你需要“心跳丢失”告警,就必须添加一条 Incoming Request 类型的标准。
另外请注意:从未收到过请求的监控,会被当作“在创建时收到了最后一次请求”。因此,Not Recieved In Minutes: 10 的标准会在新监控创建 10 分钟后触发,即使发送方从未接入——这是首次搭建时的常见“惊吓点”。
接收其他系统的告警:Alertmanager、Grafana 与事件分组
Alertmanager、Grafana 以及类似的工具会 POST 一个描述一条或多条告警的 JSON 文档。默认情况下,一条命中(Criteria Match)只打开一个事件——所以一个携带 5 条告警的负载只会产生一个事件。事件分组(Incident Grouping)可以改变这一点:它从负载中提取一个值,并为每个不同的值打开一个独立事件,这些事件可以同时保持开启状态。
启用事件分组
打开标准(Criteria),展开 Settings,开启 Group incidents and alerts by a payload field。此时会出现四个字段:
| 字段 | 示例 | 作用 |
|---|---|---|
| 为每个……打开独立事件 | requestBody.alerts[*].labels.alertname |
其不同取值用于区分事件的路径 |
| 表示恢复的字段 | requestBody.alerts[*].status |
用于判断某条告警是否恢复的路径 |
| 表示已恢复的值 | resolved |
精确标记恢复的值 |
| 每个请求的最大事件数 | 100(默认) |
安全上限,防止高基数字段打开无限数量的事件 |
“每个请求的最大事件数”这一默认值 100 在源码中有直接对应:IncomingRequestIncidentGrouping 中定义了 DEFAULT_MAX_KEYS_PER_PAYLOAD = 100(见 Common/Server/Utils/Monitor/IncomingRequestIncidentGrouping.ts)。
路径语法
- 路径必须以字面量前缀
requestBody.开头。缺少该前缀的路径(如alerts[*].labels.alertname)会静默地什么都不匹配。 {{ }}包裹是可选的:requestBody.status与{{requestBody.status}}行为相同。[*]通配符会展开一个数组——每个不同的值生成一个事件。两个产生相同值的元素会合并到同一个事件,该事件的触发/恢复状态取自第一个匹配的元素。只有路径中的第一个[*]会被展开;requestBody.groups[*].alerts[*].name不会匹配任何内容。[0]与[last]选择单个元素,并且可以出现在[*]之后。- 对象与数组类型的值、空字符串和 null 会被忽略;
0与false是有效的键值。
恢复是事件驱动的(Event-Driven Resolution)
Webhook 只描述它携带的负载中的内容,因此 OneUptime 绝不会因为某个键不再出现而自动恢复事件。事件只有在负载显式声明该键已恢复时才会被解决。两个条件必须同时成立:
- 表示恢复的字段与表示已恢复的值都已设置,并且与负载匹配。比较是精确且区分大小写的——
Resolved不会匹配resolved。 - 该标准的事件(Incident)在 Advanced Options(事件表单下方)中开启了 Auto Resolve Incident 选项。否则恢复事件会被忽略,事件将一直保持开启。(这一点对告警与 Auto Resolve Alert 同样适用。)
每个请求的最大事件数限制的不只是提取,还包括恢复:超过上限的键对恢复也不可见。因此,在一个包含超过上限个不同键的负载中,即使某个告警报告了 resolved,它的事件也不会被关闭。
警告:如果表示恢复的字段包含
[*]而为每个……打开独立事件不包含,那么永远不会恢复任何内容。要么两者都用[*],要么两者都不用。不带[*]的恢复路径会针对整个负载进行判断,因此负载级别的status: resolved会恢复该负载中的每一个键——包括那些自身状态仍为 firing 的告警。
事件命名
分组键会作为变量提供给事件与告警模板,变量名取路径的最后一段:
| 路径 | 变量 |
|---|---|
requestBody.alerts[*].labels.alertname |
{{alertname}} |
requestBody.alerts[*].fingerprint |
{{fingerprint}} |
requestBody.commonLabels.severity |
{{severity}} |
完整负载也一并可用,所以标题设为 {{alertname}}、描述引用 {{requestBody.commonAnnotations.summary}} 的事件可以同时工作。更多细节见 事件与告警的动态模板化。
警告:变量名是 OneUptime 用于把恢复事件与已打开事件匹配的身份标识的一部分。把分组路径改成结尾段不同的路径,会让当前在该旧路径下已打开的所有事件“孤儿化”——它们将无法被自动恢复,必须手动关闭。
请注意,[*] 只在上述两个分组路径字段中生效。在其他地方它不会被展开,且未展开的通配符会原样打印而非留空——例如标题为 {{requestBody.alerts[*].labels.alertname}} 会连同花括号一起渲染出来。标题为 {{requestBody.alerts[0].annotations.summary}} 会被展开,但它永远读取负载中的第一条告警,而不是为当前事件打开的那条告警。建议优先使用分组变量以及负载的公共字段 commonAnnotations。
集成实践
- 完整的 Alertmanager 配置请参阅 Prometheus Alertmanager 集成。
- Grafana 的配置请参阅 Grafana 集成。
最佳实践
- 设置合适的时间窗口——如果你的 cron 任务每 5 分钟运行一次,请把
Not Recieved In Minutes阈值设为 10–15 分钟,以容忍偶发的调度延迟。 - 携带有意义的数据——在请求体中发送状态信息,这样才能构建细粒度的监控标准。
- 使用
Content-Type: application/json的 POST——所有读取请求体内部字段的功能都依赖它。 - 不要在一个监控上混用两种职责——接收事件驱动告警的监控没有固定节奏,
Not Recieved In Minutes标准会在其上抖动误报。请为死键场景单独使用一个监控。 - 监控发送方——确保发送请求的服务具备正确的错误处理,不要让失败的请求悄无声息地消失。
进一步阅读
- Prometheus Alertmanager 集成——完整的入站告警接入指南
- Grafana 集成——Grafana 告警的同类接入
- 事件与告警的动态模板化——标题与描述中可用的所有变量
- JavaScript 表达式——表达式语法与引号规则