智能制造与工业软件 / 系统课时
给设备采集到入库建立链路追踪
给设备采集到入库建立链路追踪
设备温度已经变化,平台却迟迟没有新数据时,单看 MQTT 连接状态无法判断消息卡在哪里。本课为每条采样事件建立跨设备、网关、消息代理、平台接入和时序库的统一标识与时间证据,再据此定位延迟、丢失及补传重复。
学习目标
- 为采样事件设置稳定的
event_id、trace_id和设备标识,避免把 MQTT 报文编号当成全局消息 ID。 - 在各处理边界记录可关联的事件与时间戳,并拆分链路耗时。
- 用脚本识别缺失阶段,设计断线、重试和去重验收方法。
让同一条采样数据拥有稳定身份
以设备 f01-l02-m01 的第 42 次温度上报为例,在设备或可信网关生成事件标识。事件标识用于业务去重,追踪标识用于把各阶段日志串成一条链;若一次采集生成多个下游消息,可以保持同一 trace_id,但为每条业务事件分别分配 event_id。
{
"device_id": "f01-l02-m01",
"event_id": "f01-l02-m01-boot7-000042",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"seq": 42,
"event_time": "2026-10-12T00:00:00.000Z",
"metric": "temperature_c",
"value": 86.2
}这是一份消息载荷示例,而不是 MQTT 固定字段。不能修改 PLC 报文时,由边缘网关封装这些字段;设备重启可能令序号归零,因此 event_id 需要包含持久化的启动世代或使用全局唯一 ID。断线补传时保留原 event_id 和 event_time,另记 attempt=2,不能把重发当成新采样。
MQTT 3.1.1 可以将标识放入 JSON 载荷;MQTT 5 也可使用 PUBLISH 的 User Properties 传递追踪上下文,但应实测 Broker 与订阅端是否完整保留。MQTT 的 Packet Identifier 只在相应连接和会话的报文交换中有意义,可能复用,不可用作跨系统唯一键。协议字段可查阅 MQTT 5.0 标准。
在真实处理边界留下六个检查点
每个组件记录一条结构化日志,至少包括 device_id、event_id、trace_id、stage、timestamp、status;重试另外记录 attempt。使用 UTC 时间,服务节点采用 NTP 或更严格的现场授时;同一进程内的耗时优先使用单调时钟,避免校时跳变。
检查点 stage |
记录时刻 | 主要排查对象 |
|---|---|---|
sampled |
设备完成采样;没有可靠设备时钟则只作事件时间参考 | 采样延迟、源时间偏差 |
gateway_received |
网关完成读取或接收 | 设备到网关 |
gateway_published |
网关调用 MQTT 发布接口 | 本地落盘队列、等待上传 |
broker_accepted |
Broker 的服务端接收钩子确认接纳 | 发布路径与 Broker 接入 |
platform_received |
平台订阅回调收到事件 | Broker 投递、订阅消费 |
db_committed |
数据库写事务成功提交 | 格式校验、去重、入库 |
broker_accepted 不是所有 Broker 自动提供的统一日志字段,需按所用产品接入插件、审计或钩子;如果没有该观测点,只能统计“网关发布至平台接收”的合并时延,不能凭空细分。QoS 1 的 PUBACK 也不代表平台已经入库;db_committed 应在真正提交成功后记录。

用一个事件编号还原时延与缺口
下面的 Python 3.10+ 示例使用模拟的 UTC 结构化日志数据,按事件 ID 聚合六个阶段,计算相邻阶段耗时,并报告缺失检查点。实际接入时,可将列表替换为日志平台按 event_id 导出的记录;同一阶段发生重试时,还需按 attempt 保留多条记录,不能简单覆盖。
from datetime import datetime
stages = [
("采样", "sampled"),
("网关接收", "gateway_received"),
("网关发布", "gateway_published"),
("代理接收", "broker_accepted"),
("平台收到", "platform_received"),
("入库提交", "db_committed"),
]
# 演示数据:两条采样事件,第二条尚无入库成功记录。
logs = [
("m01-42", "sampled", "2026-10-12T00:00:00.000Z"),
("m01-42", "gateway_received", "2026-10-12T00:00:00.040Z"),
("m01-42", "gateway_published", "2026-10-12T00:00:00.120Z"),
("m01-42", "broker_accepted", "2026-10-12T00:00:00.150Z"),
("m01-42", "platform_received", "2026-10-12T00:00:00.250Z"),
("m01-42", "db_committed", "2026-10-12T00:00:00.300Z"),
("m01-43", "sampled", "2026-10-12T00:00:01.000Z"),
("m01-43", "gateway_received", "2026-10-12T00:00:01.050Z"),
("m01-43", "gateway_published", "2026-10-12T00:00:01.130Z"),
("m01-43", "broker_accepted", "2026-10-12T00:00:01.160Z"),
("m01-43", "platform_received", "2026-10-12T00:00:01.250Z"),
]
# 以业务事件 ID 关联,避免将不同 MQTT 连接的报文编号混用。
events = {}
for event_id, stage, value in logs:
events.setdefault(event_id, {})[stage] = datetime.fromisoformat(
value.replace("Z", "+00:00")
)
# 缺失阶段要先核查日志与入库状态,不能直接认定丢包。
for event_id, times in sorted(events.items()):
missing = [name for name, key in stages if key not in times]
if missing:
print(f"{event_id}: 缺少{'、'.join(missing)}")
continue
total = round((times["db_committed"] - times["sampled"]).total_seconds() * 1000)
print(f"{event_id}: 总耗时 {total}ms")
for (left_name, left), (right_name, right) in zip(stages, stages[1:]):
elapsed = round((times[right] - times[left]).total_seconds() * 1000)
print(f" {left_name}→{right_name}: {elapsed}ms")预期输出:
m01-42: 总耗时 300ms
采样→网关接收: 40ms
网关接收→网关发布: 80ms
网关发布→代理接收: 30ms
代理接收→平台收到: 100ms
平台收到→入库提交: 50ms
m01-43: 缺少入库提交第一条事件的最大区间是“代理接收至平台收到”100ms,应继续检查订阅消费速率与消息积压。第二条只说明当前观测数据没有提交证据,不能直接判定消息丢失:还要按 event_id 查数据库唯一键、消费异常日志和待重试队列。若跨主机时间差出现负值,先检查时钟同步,再谈链路延迟。
用断线、重试和重复消息建立上线基线
用测试设备发送连续 100 条采样事件,以数据库中 100 个不同的 event_id 为验收目标,同时检查各阶段日志。以下阈值仅为本次演示基线,可按现场采样周期与链路 SLA 调整。
- 正常链路:确保 100 条事件在数据库各提交一次;完整追踪率为 100%,端到端 P95 不超过 500ms。这里的 P95 必须基于已经完成提交的事件计算,另报告超时与未完成数量。
- 断网补传:网关断网期间持久化 20 条事件,恢复后按原
event_id补传;应看到gateway_received早于后续gateway_published,并在日志中记录补传尝试次数。 - 制造重复投递:重发其中 5 条相同
event_id的消息;平台允许重复接收,但数据库使用(device_id, event_id)唯一约束或等价幂等写入,最终仍应只有 100 条业务事件。 - 模拟入库故障:短暂停止写入端,确认
platform_received有记录、db_committed暂缺,恢复后提交成功;同时验证失败日志、待重试消息与告警可以定位此区间。
生产中建议按 device_id、event_id 检索单条证据链,并统计各段 P95、队列积压数、追踪覆盖率与“收到但未提交”数量。对于设备时钟未同步的情况,单独展示事件时间和网关接收时间,避免把设备时钟漂移误报成网络延迟。