OneUptime Incoming Request Monitor 完整实战指南:心跳监控、死键检测与 Alertmanager/Grafana 告警接入

原创2026-09-18 09:01:501,676 阅读
文章标签:可观测性后端运维前端云原生微服务AI Agent

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 仪表盘中按以下步骤创建:

  1. 进入 Monitors 页面
  2. 点击 Create Monitor
  3. 监控类型选择 Incoming Request
  4. OneUptime 会为这个监控生成一个 Secret Key 和一个专属地址
  5. 打开该监控,在左侧菜单点击 Documentation,复制该地址
  6. 将你的服务配置为向该地址发送请求
  7. 按下方说明配置监控标准

创建完成后,监控状态与事件流转完全由入站请求驱动:请求内容决定在线/降级/离线状态,请求缺失(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 Contains error)能让无请求体的心跳 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 绝不会因为某个键不再出现而自动恢复事件。事件只有在负载显式声明该键已恢复时才会被解决。两个条件必须同时成立:

  1. 表示恢复的字段与表示已恢复的值都已设置,并且与负载匹配。比较是精确且区分大小写的——Resolved 不会匹配 resolved。
  2. 该标准的事件(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。

集成实践

最佳实践

  1. 设置合适的时间窗口——如果你的 cron 任务每 5 分钟运行一次,请把 Not Recieved In Minutes 阈值设为 10–15 分钟,以容忍偶发的调度延迟。
  2. 携带有意义的数据——在请求体中发送状态信息,这样才能构建细粒度的监控标准。
  3. 使用 Content-Type: application/json 的 POST——所有读取请求体内部字段的功能都依赖它。
  4. 不要在一个监控上混用两种职责——接收事件驱动告警的监控没有固定节奏,Not Recieved In Minutes 标准会在其上抖动误报。请为死键场景单独使用一个监控。
  5. 监控发送方——确保发送请求的服务具备正确的错误处理,不要让失败的请求悄无声息地消失。

进一步阅读

登录后查看全文
oneuptime