OneUptime IoT 设备监控接入指南通过 OTLP 与 MQTT 上报iot_*指标构建设备舰队实时观测【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读本文是 OneUptime 开源可观测平台的IoT 设备接入ingestion指南讲解如何让传感器、网关、控制器和边缘盒子edge box把遥测数据送入 OneUptime从而自动生成按**舰队Fleet**归组的实时设备清单并跟踪每台设备的电池、信号、温度、CPU、内存与在线状态。读完本文你将掌握三条完整的上报路径直接使用 OpenTelemetry SDK、通过 OpenTelemetry Collector 网关聚合以及使用 OneUptime 内置 MQTT 端点直连上报同时掌握iot_*指标命名约定、MQTT 主题契约、认证与 Last Will 离线检测机制以及自托管环境的端点配置方法。说明本文面向设备侧的数据上报。在数据之上配置离线、低电量、弱信号、高温、高 CPU 等告警请参阅 IoT 设备监控器文档。一、OneUptime 如何建模 IoT舰队Fleet与设备DeviceOneUptime 用两个核心概念来组织 IoT 遥测数据二者均由 OpenTelemetry 资源属性resource attribute推导而来概念来源属性说明舰队Fleetiot.fleet.name设备的逻辑分组例如building-a-sensors、field-gateways。在 OneUptime 中呈现为遥测服务iot/fleet设备Devicedevice.id舰队内的单台设备。OneUptime 按device.id为每个舰队维护独立的设备清单除两个必填属性外以下可选属性用于细化设备分类方便后续在监控器中筛选属性必填说明iot.fleet.name是设备所属舰队映射为 OneUptime 服务iot/fleetdevice.id是舰队内稳定且唯一的设备 IDiot.device.kind否设备类别如Device、Sensor、Gateway缺省为Deviceiot.device.type否更细的设备型号用于监控器过滤如temp-sensoriot.device.firmware否设备上报的固件版本源码视角舰队的自动发现与存储模型从源码结构看IoT 监控是 OneUptime 基础设施监控体系克隆自 Proxmox 基础设施产品的独立模块其落库结构在迁移脚本 1782900000000-AddIoTFleetAndDeviceTables.ts 中有完整定义IoTFleet表一个父级舰队表。name列就是与iot.fleet.name资源属性对齐的连接键join key由 OTel 摄入时自动发现auto-discovered也可手工注册表上带有UNIQUE(projectId, name)级别的并发竞态防护索引IoTDevice表子级设备清单表。externalId即数据点上的device.id标签kind为设备类别并保存latestBatteryPercent、latestSignalStrengthDbm、latestTemperatureCelsius、latestCpuPercent、latestMemoryBytes、isUp、uptimeSeconds等最新快照列配有唯一身份索引(projectId, iotFleetId, kind, externalId)。对应模型定义见 IoTFleet.ts 与 IoTDevice.ts。其中IoTDevice被标记为只读清单——「由遥测摄入流水线填充用户不可编辑」见 IoTDevice.ts 的tableDescription这印证了文档所述设备清单完全由上报数据驱动。舰队的自动创建由服务层完成。在 IoTFleetService.ts 的findOrCreateByName中舰队以iot.fleet.name为键进行大小写不敏感的查找与创建时保留用户书写大小写——这意味着只要设备带上了正确的资源属性舰队就会在数据到达后自动出现无需任何手工前置建表。二、前置条件开始上报前请确认以下三项一台支持向 OneUptime 发送 OTLP/HTTP 的设备、网关或 Collector设备/网关到 OneUptime 实例的网络连通性一个OneUptime Telemetry Ingestion Token遥测摄取令牌在控制台项目设置 → Telemetry and APM → Ingestion Keys中创建并复制其中的x-oneuptime-token值。三、接入方式一通过 OpenTelemetry SDK 直接上报如果设备上直接运行 OpenTelemetry SDK只需将导出器指向 OneUptime并通过标准的OTEL_*环境变量打上 IoT 资源属性。以下为示例将 token、endpoint、舰队名、设备 ID 替换为实际值export OTEL_EXPORTER_OTLP_ENDPOINThttps://oneuptime.com/otlp export OTEL_EXPORTER_OTLP_HEADERSx-oneuptime-tokenYOUR_TELEMETRY_INGESTION_TOKEN export OTEL_RESOURCE_ATTRIBUTESiot.fleet.namebuilding-a-sensors,device.idsensor-001,service.nameiot/building-a-sensors环境变量必填说明OTEL_EXPORTER_OTLP_ENDPOINT是OneUptime 的 OTLP 端点https://oneuptime.com/otlp自托管为http(s)://YOUR-ONEUPTIME-HOST/otlpOTEL_EXPORTER_OTLP_HEADERS是x-oneuptime-tokenYOUR_TELEMETRY_INGESTION_TOKENOTEL_RESOURCE_ATTRIBUTES是逗号分隔的资源属性列表必须包含iot.fleet.name、device.id与service.nameiot/fleet之后按下文「指标约定」中的iot_*名称发送指标。约一分钟后设备会出现在 OneUptime 控制台的IoT板块下。注意service.name的作用service.nameiot/fleet是关键它让日志与指标落在同一个服务下从而保证舰队详情页能同时展示日志与指标。从 ResourceEntityFilter.ts 的实现看iotFleetId这一资源 facet 通过resource.iot.fleet.name属性与IoTFleetService的name列做解析映射服务名与资源属性的对齐直接影响后续监控器、面板的筛选语义。四、接入方式二通过 OpenTelemetry Collector 网关聚合当大量设备经由一台网关上报时在网关上运行 OpenTelemetry Collector用resource处理器统一为数据打上舰队属性再把指标转发给 OneUptimereceivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: send_batch_size: 512 timeout: 5s resource: attributes: - key: iot.fleet.name value: field-gateways action: upsert - key: service.name value: iot/field-gateways action: upsert exporters: otlphttp: endpoint: https://oneuptime.com/otlp headers: x-oneuptime-token: YOUR_TELEMETRY_INGESTION_TOKEN service: pipelines: metrics: receivers: [otlp] processors: [resource, batch] exporters: [otlphttp]要点解读resource处理器为每一条记录统一打上舰队属性。按网关设置iot.fleet.name及其对应的service.nameiot/fleet即可让该网关下所有设备落入正确的舰队保留设备身份device.id以及可选的iot.device.kind/iot.device.type/iot.device.firmware必须保留在每个数据点上OneUptime 才能据此在舰队内定位单台设备otlphttp导出器通过 HTTPS 携带摄取令牌发送到 OneUptime。标准 protobuf 编码与encoding: json均被接受。源码视角摄入侧如何处理这批数据OneUptime 摄入侧对iot_*指标的落库逻辑集中在 IoTSnapshotScan.ts该模块维护IOT_SNAPSHOT_METRIC_NAMES白名单IoTSnapshotScan.ts只对iot_device_up、iot_device_info及 7 个「最新值镜像」指标做快照折叠其余指标名不会进入设备清单列设备身份取自数据点的device.id标签而非资源前缀合并映射iot.device.kind缺失时回退为Device超过 100 字符的device.id会在摄入时截断避免单条畸形数据拖垮整批写入iot_cpu_usage_ratio是真实的 0~1 比值摄入时直接× 100存为百分比latestCpuPercent rawValue * 100无需像 Kubernetes 那样维护分配分母缓存快照折叠采用「身份标签 first-non-null-wins、状态/指标 newest-observedAt-wins」语义并在批量中缺某条身份序列时绝不将计数清零COALESCE-per-column 契约保证列表页计数与侧边栏徽标不会漂移。五、接入方式三通过 MQTT 直连上报OneUptime 内置 MQTT 端点已支持 MQTT 的设备无需 OpenTelemetry SDK、Collector 或桥接即可直连上报。经 MQTT 发布的数据与 OTLP 走完全相同的流水线舰队自动创建、设备清单自动更新、所有 IoT 监控器与告警模板行为不变。5.1 端点传输方式地址说明MQTT over WebSocketwss://your-host/mqtt适用于所有部署形态——经 OneUptime ingress 运行在常规 HTTPS 端口上MQTT over TCPapp-host:1883MQTT_INGEST_PORT自托管场景默认仅在集群/Compose 网络内部可达可按需对外暴露5.2 认证两种方式方式一项目级令牌Project-wide将Telemetry Ingestion Token作为 MQTT 密码发送用户名被忽略若客户端只有用户名字段则把令牌放入用户名。适合代表多台设备发布消息的网关。方式二按设备凭据Per-device推荐直连设备使用在控制台舰队页面的Device Registry标签页中注册设备。注册会为每台设备签发一组凭据——凭据 ID 作为 MQTT用户名密钥作为密码。按设备认证带来三个关键收益主题隔离设备认证的客户端只能向属于自己的oneuptime/fleet/device/…主题发布单点吊销某台设备被攻破时可直接在控制台吊销其凭据不影响舰队其余设备吊销约一分钟后生效对已连接会话同样有效静默死亡检测silent death已注册设备停止上报时仍会以Offline状态保留在清单中而非消失且即使没有 Last WillDevice Offline告警模板也会被触发。从源码看按设备凭据的落库由迁移 1783780000000-AddIoTDeviceCredentialTable.ts 中的IoTDeviceCredential表实现表中externalId对应设备 IDsecretKeyUUID即 MQTT 密码并带有UNIQUE(projectId, iotFleetId, externalId)唯一索引与isEnabled启用开关——这正是文档所述「注册、吊销、隔离」三能力的存储底座。认证失败行为无效凭据会在 CONNECT 阶段以返回码 4用户名或密码错误被拒绝使配置错误的设备快速、显式地失败。5.3 主题契约所有主题必须使用固定的oneuptime/前缀。舰队段与设备段不得包含/、、#且每段不超过 100 字符主题Payloadoneuptime/fleet/device/telemetry携带指标的 JSON 对象——如{ metrics: { iot_temperature_celsius: 21.5 } }也可用扁平对象此时数值字段即指标oneuptime/fleet/device/metrics/metricName单个数值——裸数字23.4或{ value: 23.4 }oneuptime/fleet/device/statusonline或offline也接受1/0、true/false、up/down——映射为iot_device_upTelemetry payload 还可携带attributes字符串映射会打在每个数据点上——可用于iot.device.kind、iot.device.type、iot.device.firmware或自定义标签timestampISO-8601 或 Unix 秒/毫秒缺省时使用摄入时间。5.4 Last Will 离线检测在oneuptime/fleet/device/status主题上注册 MQTT Last Willpayload 为offline。当设备死亡或断网、会话结束时broker 会立即代为发布iot_device_up 0——从而无需轮询、无需等待丢失的抓取直接触发默认的Device Offline告警模板并将设备置为 Down。设备重连后向同一主题发布online即可恢复 Up 状态。5.5 客户端示例mosquitto_pub裸 TCP自托管mosquitto_pub -h YOUR-ONEUPTIME-APP-HOST -p 1883 \ -u oneuptime -P YOUR_TELEMETRY_INGESTION_TOKEN \ -t oneuptime/building-a-sensors/sensor-001/telemetry \ -m {metrics:{iot_device_up:1,iot_battery_percent:87,iot_temperature_celsius:21.5},attributes:{iot.device.type:temp-sensor,iot.device.firmware:1.4.2}}Node.jsmqtt库WebSocket兼容云版与自托管const mqtt require(mqtt); const client mqtt.connect(wss://oneuptime.com/mqtt, { username: oneuptime, // 被忽略——真正用于认证的是下面的 token password: YOUR_TELEMETRY_INGESTION_TOKEN, will: { topic: oneuptime/building-a-sensors/sensor-001/status, payload: offline, }, }); client.on(connect, () { client.publish(oneuptime/building-a-sensors/sensor-001/status, online); setInterval(() { client.publish( oneuptime/building-a-sensors/sensor-001/telemetry, JSON.stringify({ metrics: { iot_device_up: 1, iot_battery_percent: readBattery(), iot_temperature_celsius: readTemperature(), }, }), ); }, 60 * 1000); });Pythonpaho-mqtt库WebSocketimport json import paho.mqtt.client as mqtt client mqtt.Client(transportwebsockets) client.username_pw_set(oneuptime, YOUR_TELEMETRY_INGESTION_TOKEN) client.tls_set() client.will_set(oneuptime/building-a-sensors/sensor-001/status, offline) client.ws_set_options(path/mqtt) client.connect(oneuptime.com, 443) client.publish(oneuptime/building-a-sensors/sensor-001/status, online) client.publish( oneuptime/building-a-sensors/sensor-001/telemetry, json.dumps({metrics: {iot_device_up: 1, iot_temperature_celsius: 21.5}}), )5.6 MQTT 端点注意事项端点为**仅摄入ingest-only**设计订阅会被拒绝SUBACK 错误。若需要 broker 确认接收请使用 QoS 1投递语义为至少一次QoS 1/2 在丢失确认后的重传可能产生重复数据点不符合主题契约或 payload 畸形的发布会被接受后丢弃MQTT 3.1.1 没有按消息的错误响应服务器会记录带原因警告——若数据迟迟未到请检查 OneUptime 应用日志WebSocket 端点上 MQTT keepalive 必须低于 5 分钟OneUptime ingress 会在 300 秒后关闭空闲 WebSocket 连接从而触发 Last Will 导致虚假的 Device Offline 告警。mqtt与paho-mqtt库默认 60 秒 keepalive 是安全的裸 TCP 端点无此限制单次发布 payload 上限为128 KB 且最多 100 个指标超限的包会导致连接被断开。六、指标约定iot_*命名OneUptime 识别以下iot_*指标名。每个数据点都应携带device.id标签以便指标归属到正确的设备。只需发送对设备有意义的指标即可——缺失的指标不会出现在图表中指标名含义iot_device_up设备可用性1 在线/可用0 离线。驱动 IoT 设备监控器iot_device_info纯身份信号。携带device.id/ kind / type / firmware使设备在尚未上报任何指标前就出现在清单中iot_battery_percent电池电量范围0–100%iot_signal_strength_dbm无线信号强度dBm如 Wi-Fi / LoRa / 蜂窝 RSSIiot_temperature_celsius设备或传感器温度°Ciot_cpu_usage_ratioCPU 利用率比值0–1OneUptime 以百分比形式存储iot_memory_usage_bytes当前已用内存字节iot_memory_size_bytes设备可用总内存字节iot_uptime_seconds设备自上次启动以来的秒数源码视角iot_device_info与快照列的对应关系在 IoTSnapshotScan.ts 中iot_device_info被专门处理为「纯身份序列」它从数据点属性中读取人类可读的name并将sawDeviceIdentity置位——这解释了文档所述「设备先出现在清单、指标后到」的行为只要批量中出现了iot_device_info或iot_device_up舰队就会写入deviceCount出现了iot_device_up才会写入onlineDeviceCountIoTSnapshotScan.ts。七、验证接入是否成功确认设备/网关导出无报错检查 SDK/Collector 日志中的导出错误及 HTTP401/403响应在 OneUptime 控制台打开IoT板块——约一分钟后舰队应以iot/fleet形式出现打开舰队的Devices标签页——每个发送过的device.id都应列出并带其最新电池、信号、温度、CPU、内存与在线状态打开舰队下的Metrics为上述任意iot_*序列绘制图表。八、故障排查8.1 舰队未出现确认iot.fleet.name是作为资源属性而非数据点标签设置的且service.name为iot/fleet确认导出端点确为https://oneuptime.com/otlp或自托管的…/otlp且x-oneuptime-token头携带有效令牌若使用 MQTT确认主题严格遵循oneuptime/fleet/device/…——是主题中的舰队段创建了舰队。8.2 设备未出现在清单确保每个数据点都带device.id标签——设备以此为主键对尚未上报指标的设备先发送iot_device_info纯身份使其仍出现在清单中检查device.id是否跨报告稳定——变化的 ID 会生成重复设备行。8.3 导出端返回 HTTP 401 / 403摄取令牌无效、被吊销或缺失。请在项目设置 → Telemetry and APM → Ingestion Keys重新生成并更新x-oneuptime-token头。8.4 指标未出现在图表中确认使用了上文「指标约定」表中的精确iot_*名称——未知名称会被存为通用指标无法填充 IoT 图表记住iot_cpu_usage_ratio是0–1比值请发送原始比值OneUptime 会以百分比形式呈现设备开始上报后最多等待一分钟首批数据点才会出现。九、自托管 OneUptime 的端点配置自托管时将端点指向自己的实例export OTEL_EXPORTER_OTLP_ENDPOINThttps://your-oneuptime-host.example.com/otlpCollector 中对应为exporters: otlphttp: endpoint: https://your-oneuptime-host.example.com/otlp headers: x-oneuptime-token: YOUR_TELEMETRY_INGESTION_TOKENMQTT 方面连接wss://your-oneuptime-host.example.com/mqtt若设备不支持 WebSocket可暴露 app 服务的裸 MQTT TCP 端口MQTT_INGEST_PORT默认1883。如需彻底关闭 MQTT 监听器可在 app 服务上将MQTT_INGEST_ENABLEDfalse。若实例仅以 HTTP 运行将协议切换为http://MQTT 对应ws://并使用相应端口。十、下一步配置IoT 设备监控器针对设备离线、低电量、弱信号、高温、高 CPU 条件告警——参见 IoT 设备监控器非容器化主机Linux / macOS / Windows 虚拟机及物理机请使用 Host OpenTelemetry Collector 指南深入了解底层 OTLP 集成参见 将 OpenTelemetry 集成到 OneUptime。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考