企业官网建设流程全解析

OneUptime IoT 设备监控：基于遥测的逐设备告警、离线检测与无数据策略

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

本篇技术文章基于 OneUptime 官方文档（IoT Device Monitor）并结合仓库源码实现，讲解 IoT 设备监控器如何针对设备舰队（Fleet）上的iot_*遥测指标做逐设备告警：从五种快速配置模板的完整阈值定义，到 Device Registry 静默设备检测的底层"缺失序列合成"机制，再到无数据策略（No Data Policy）的三种语义。读完本文，你既能按步骤在 OneUptime 中创建 IoT 设备监控器，也能理解每条模板背后聚合方式、评估窗口与二进制指标处理的设计原理。

概述：逐设备分组的指标监控

IoT 设备监控器（IoT Device Monitor）监控的目标不是某个探针端点，而是你的设备舰队向 OneUptime 推送的遥测数据。它在一个滚动时间窗口上对指标查询求值（默认监控窗口为最近 1 分钟，由 MonitorStepIoTMonitorUtil.getDefault 中的RollingTime.Past1Minute确认；快速配置模板使用更长的窗口，见下文），并将结果按每台设备（device.id数据点标签）分组。

这带来两个关键语义：

• 逐设备事件：一个监控器只会为每台越过阈值的设备产生一个事件或告警——30 台传感器离线意味着 30 个各自带有设备 ID 印记的事件，而不是一个模糊的舰队级事件；
• 自动恢复：当某台设备的指标序列恢复正常（或改善后消失）时，其事件会自动解决。

由于监控器直接评估已接收的数据，设备无论通过 OpenTelemetry（OTLP）还是 MQTT 上报，行为完全一致——监控器端没有探针参与。

指标与标签的语义在源码中有明确约定（见 IotMetricCatalog.ts）：每台设备的系列（series）都携带device.id数据点标签，并由 IoT 代理/网关打上iot.scope（fleet | device）、iot.device.type与iot.device.kind等数据点属性。注意这些都是数据点属性，在 ClickHouse 中不带resource.前缀，过滤时直接按属性键匹配。

创建 IoT 设备监控器

操作步骤：

1. 在 OneUptime 仪表盘进入Monitors页面；
2. 点击Create Monitor；
3. 监控类型选择IoT Device；
4. 选择目标舰队（Fleet），然后通过以下三种方式之一完成配置：快速配置模板、自定义指标、高级模式。

创建监控器前，先确保设备已经在向 OneUptime 上报遥测数据——OTLP 与 MQTT 两种接入方式详见仓库中的 IoT 设备接入指南。

监控器内部结构对应MonitorStepIoTMonitor接口（源码）：

export default interface MonitorStepIoTMonitor { fleetIdentifier: string; // 目标舰队标识 resourceFilters: IoTDeviceFilters; // 设备级过滤（Scope / Device ID / Device Type） metricViewConfig: MetricsViewConfig; // 指标查询 + 公式 rollingTime: RollingTime; // 滚动评估窗口 }

快速配置：五个一键模板

五个模板覆盖最常见的告警场景。每个模板都将一个告警条件与一个恢复条件配对，并支持自动解决（源码实现见 IotAlertTemplates.ts）：

所有阈值在应用模板后都可以编辑——打开监控器条件即可调整。

模板背后的源码级细节

从 IotAlertTemplates.ts 的实现可以看到，每个模板并不是简单地"套一个阈值"，而是精心选择了聚合方式、评估窗口与量化方式：

1. Device Offline 使用 30 分钟窗口 + Min 聚合 + AnyValue 量化（模板定义）。这个 30 分钟窗口不是检测延迟，而是静默宽限期：对已注册但停止上报的设备，系统会为其合成一条空序列，再经 Treat as Zero 策略折叠为 0 从而触发< 1；空值到达比较器时是标量而非数组，因此持续评估不会给它任何保护，窗口长度就是唯一可调旋钮。30 分钟正好是库存层允许设备静默 15 分钟（IoTDeviceService.getStaleThresholdMinutes）的两倍，能覆盖约 15 分钟以内的上报周期。其余四个模板使用 5 分钟窗口。
2. 温度模板刻意用 Max 而非目录默认的平均值：同一分钟内的低温读数不能掩盖一次高温读数，否则热点会被平均掉。它只是逐分钟归约，条件本身再按持续（sustained）评估跨分钟量化，所以"单点尖峰"不会呼叫值班。
3. iot_device_up是严格二值指标（0 或 1）：恢复条件显式设置isBinaryMetric: true退出 10% 恢复死区——否则恢复阈值会变成不可达的>= 1.1，监控器永远无法回到健康态。相应地，告警侧采用AnyValue（窗口内任一分钟出现< 1即触发），因为 Last Will 路径要求"无轮询、无漏采延迟"，若用 AllValues 则会被整个窗口拖延。
4. 单位语义：buildIoTMonitorConfig会从指标目录（IotMetricCatalog）继承单位（%、dBm、°C、ratio），确保根因信息读出 "is -103.2 dBm which is less than -100 dBm" 而不是裸数字；对设备声明为无量纲、却上报 0-1 电池比例的系列，%单位转换还能纠正阈值比较（源码注释明确指出 0-1 分数型电池值会永久满足< 20的坑）。

每个模板生成的事件标题带有固定前缀，例如[IoT] Device Offline - <监控器名>、[IoT] High Temperature (>70°C) - <监控器名>，并附默认事件描述（检查受影响设备 ID 的根因、确认电源与网络状态、验证网关是否仍在转发遥测等）。

自定义指标：从目录选指标、聚合与过滤

在Custom Metric方式下，你可以从 IoT 指标目录中选择任意指标，指定聚合方式（平均/最小/最大/和/计数/分位数）、滚动窗口，并用属性过滤器收窄范围。

OneUptime 内置的 IoT 指标目录定义在 IotMetricCatalog.ts，共 7 个指标：

过滤器对应IoTDeviceFilters接口（源码），每一项都映射为数据点属性等值条件：

注意device.id标签在存储时是逐字节精确的（不像host.name会在摄入时做规范化），缺失序列合成时也因此逐字处理，否则指纹会与设备真实序列分叉，破坏事件去重与自动恢复——这一约束见 IoTDeviceAbsenceSeries.ts 的注释。

高级模式：跨别名公式

Advanced 方式提供完整的指标查询构造器，可针对舰队的任意上报内容做查询——包括你自己的自定义指标名——并支持跨查询别名的公式。典型用例：将内存已用（iot_memory_usage_bytes）除以总内存，以百分比表达内存压力。

公式机制由buildIoTRatioMonitorConfig（源码）承担，其生成的公式形如(numerator / denominator) * 100，并可选择按 OpenTelemetry 属性（如device.id）分组，使每个分组各产生一个事件。源码注释中说明了聚合契约：每台设备的指标都来自该设备的同一次推送，因此分子分母同接收方，Sum/Sum聚合下抓取次数在比值中相互抵消，比值计算是安全的。

离线检测：三条路径与"注册设备"的静默检测

Device Offline 模板在设备报告iot_device_up = 0时触发。一台沉默或宕机的设备可以通过三条路径落入该检测：

1. 网关上报：当网关或采集器无法再触达某些设备时，由网关发布iot_device_up = 0；
2. MQTT Last Will：通过 OneUptime 的 MQTT 端点连接的设备可以在自己的status主题上注册 Last Will。设备宕机时，broker 在会话断开的瞬间代为发布iot_device_up = 0——无轮询、无漏采延迟；
3. 已注册设备（静默死亡检测）：在舰队的Device Registry标签页中注册过的设备属于"预期在列"。当某台已注册设备在整个评估窗口内没有产生任何数据时，监控器会为它合成一条空序列，再由 Device Offline 模板的 "Treat as Zero" 无数据策略将其折算为iot_device_up = 0——每台沉默设备各产生一个事件，设备恢复上报时事件自动解决。

第 3 条路径的实现链条在源码中清晰可见：

• IoTDeviceAbsenceSeries.ts 提供纯函数助手：buildAbsentIoTDeviceSeries为当前窗口序列中缺失的每一台已注册设备构造一条空"无数据"系列，其标签与指纹与该设备真实在场系列完全一致，从而让事件去重与自动恢复正常工作；getIoTDeviceAbsenceGroupByKey保证只有当查询恰好按device.id单键分组时才启用该机制。
• 预期设备清单来自 IoTDeviceCredential 数据库模型（Device Registry 即其持久化）；与主机缺失序列不同，这里没有时效老化——注册是显式的预期清单，已注册但沉默的设备将持续告警，直到其凭证被禁用或删除，这是设计语义而非缺陷。

两个重要的边界条件：

• 该检测要求至少还有另一台设备在舰队中正常上报。若整个舰队变黑（例如网关整体中断），产生的是监控器级事件，而不是逐设备事件——因为无数据策略只在"整条查询返回数据"时按系列触发。
• 未注册的设备若无 Last Will 或网关上报而沉默，只会让数据序列停止；按设备分组的监控器无法把它分离出来（无数据策略只在整条查询无数据时触发）。要堵住这个缺口：要么把关键设备注册到 Device Registry，要么为单台关键设备建一个仅限定到该设备（Custom Metric → Device ID 过滤器）且无数据策略设为 Trigger 的监控器。
• 已注册设备在库存中不会在沉默 15 分钟后被清除，而是以Offline状态保留在舰队库存中。

升级提示：Device Offline 监控器必须携带iot_device_up条件的Treat as Zero无数据策略才具备静默检测能力。当前通过 Quick Setup 模板创建的监控器已内置该策略，但在引入 Device Registry 之前手工创建的 Device Offline 监控器需要按模板重建（或在其条件上手动启用 Treat as Zero）才有效。

无数据语义（No Data Policy）

每个指标条件都支持逐系列的无数据策略，行为定义如下：

Device Offline 模板正是在告警条件上使用 Treat as Zero（treatNoDataAsZero: true，见 模板源码），使"已注册但沉默"的设备能被逐台点名，而不是被默认策略静默跳过。

告警与通知管道

IoT 设备监控器接入 OneUptime 的标准事件/告警管道：值班排班（on-call）、告警升级、Slack、Microsoft Teams、邮件、短信与 Webhook 通知，行为与其他类型监控器完全一致。

延伸阅读

• IoT 设备接入指南——通过 OTLP 与 MQTT 让设备开始上报数据；
• 指标监控器——通用指标监控器，用于对非 IoT 遥测数据告警；
• 源码参考：IotAlertTemplates.ts（五个模板的完整构造器）、IotMetricCatalog.ts（指标目录）、MonitorStepIoTMonitor.ts（监控器数据结构与过滤器）、IoTDeviceAbsenceSeries.ts（静默设备缺失序列合成）。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime