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 印记的事件而不是一个模糊的舰队级事件自动恢复当某台设备的指标序列恢复正常或改善后消失时其事件会自动解决。由于监控器直接评估已接收的数据设备无论通过 OpenTelemetryOTLP还是 MQTT 上报行为完全一致——监控器端没有探针参与。指标与标签的语义在源码中有明确约定见 IotMetricCatalog.ts每台设备的系列series都携带device.id数据点标签并由 IoT 代理/网关打上iot.scopefleet | device、iot.device.type与iot.device.kind等数据点属性。注意这些都是数据点属性在 ClickHouse 中不带resource.前缀过滤时直接按属性键匹配。创建 IoT 设备监控器操作步骤在 OneUptime 仪表盘进入Monitors页面点击Create Monitor监控类型选择IoT Device选择目标舰队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模板条件严重级别分类Device Offlineiot_device_up最小值 1CriticalAvailabilityLow Batteryiot_battery_percent平均值 20WarningPowerWeak Signaliot_signal_strength_dbm平均值 -100WarningConnectivityHigh Temperatureiot_temperature_celsius最大值 70CriticalEnvironmentHigh CPUiot_cpu_usage_ratio平均值 0.9WarningSystem所有阈值在应用模板后都可以编辑——打开监控器条件即可调整。模板背后的源码级细节从 IotAlertTemplates.ts 的实现可以看到每个模板并不是简单地套一个阈值而是精心选择了聚合方式、评估窗口与量化方式Device Offline 使用 30 分钟窗口 Min 聚合 AnyValue 量化模板定义。这个 30 分钟窗口不是检测延迟而是静默宽限期对已注册但停止上报的设备系统会为其合成一条空序列再经 Treat as Zero 策略折叠为 0 从而触发 1空值到达比较器时是标量而非数组因此持续评估不会给它任何保护窗口长度就是唯一可调旋钮。30 分钟正好是库存层允许设备静默 15 分钟IoTDeviceService.getStaleThresholdMinutes的两倍能覆盖约 15 分钟以内的上报周期。其余四个模板使用 5 分钟窗口。温度模板刻意用 Max 而非目录默认的平均值同一分钟内的低温读数不能掩盖一次高温读数否则热点会被平均掉。它只是逐分钟归约条件本身再按持续sustained评估跨分钟量化所以单点尖峰不会呼叫值班。iot_device_up是严格二值指标0 或 1恢复条件显式设置isBinaryMetric: true退出 10% 恢复死区——否则恢复阈值会变成不可达的 1.1监控器永远无法回到健康态。相应地告警侧采用AnyValue窗口内任一分钟出现 1即触发因为 Last Will 路径要求无轮询、无漏采延迟若用 AllValues 则会被整个窗口拖延。单位语义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 个指标指标名含义分类默认聚合单位iot_device_up设备是否在线1 在线 / 0 离线AvailabilityMin—iot_battery_percent剩余电量0–100PowerAvg%iot_signal_strength_dbm无线信号强度越接近 0 越强越负越弱ConnectivityAvgdBmiot_temperature_celsius设备报告的摄氏温度EnvironmentAvg°Ciot_cpu_usage_ratioCPU 使用率0–1 的比值1 满载SystemAvgratioiot_memory_usage_bytes设备当前使用的内存字节SystemAvgbytesiot_uptime_seconds设备运行时长重启时归零SystemMaxs过滤器对应IoTDeviceFilters接口源码每一项都映射为数据点属性等值条件过滤器底层键效果Scopeiot.scope逐Device评估或横跨整个FleetDevice IDdevice.id限定到单台设备Device Typeiot.device.type限定到报告了该设备类型值的设备注意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时触发。一台沉默或宕机的设备可以通过三条路径落入该检测网关上报当网关或采集器无法再触达某些设备时由网关发布iot_device_up 0MQTT Last Will通过 OneUptime 的 MQTT 端点连接的设备可以在自己的status主题上注册 Last Will。设备宕机时broker 在会话断开的瞬间代为发布iot_device_up 0——无轮询、无漏采延迟已注册设备静默死亡检测在舰队的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每个指标条件都支持逐系列的无数据策略行为定义如下策略当系列未返回任何数据点时的行为Ignore默认该系列跳过本次评估Treat as Zero该系列按0参与评估Trigger条件直接触发Device Offline 模板正是在告警条件上使用 Treat as ZerotreatNoDataAsZero: 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考