边缘与 IoT 可观测性：弱网缓冲、设备侧采集与带宽约束

原则一：默认离线，联网是"增强"
  采集与缓冲路径不能依赖网络，网络只影响"何时上传"
原则二：采集极轻，聚合靠上
  设备侧只做最必要的采样与预处理，复杂聚合放边缘网关
原则三：传输有预算
  给每个站点/设备设带宽与流量配额，超预算时按优先级丢弃
原则四：时间必须可追溯
  每条数据带设备本地时间、时基偏移与置信度
原则五：无人值守要自愈
  agent 崩溃自恢复、磁盘写满自动清理、配置变更不依赖人工

设备层（MCU / 嵌入式 Linux）
  采集原始信号：传感器读数、运行状态、错误码、电量
  极轻量 agent（通常 < 5MB 内存），本地环形缓冲
       ↓ MQTT / CoAP（可能是间歇的）
边缘层（网关 / 边缘服务器 / k3s 节点）
  汇聚多设备数据，本地存储与聚合，跑本地告警规则
  可承载 OTel Collector 做批处理、压缩、脱敏
       ↓ 上行（可能有带宽预算）
云端
  长期存储、全局聚合、跨站点对比、模型训练

一、生存信号（必须有，即使断网也要留）
  心跳 / 在线状态、电量与供电状态、固件版本、重启次数
二、健康信号（本地可判断，用于边缘告警）
  CPU/内存占用、温度、磁盘剩余、网络信号强度（RSSI/RSRP）
  关键外设状态（传感器在线、执行器响应）
三、业务信号（数据量大，需采样）
  传感器读数、图像/音频、事件日志

内存：常驻 < 5~10MB，缓冲区用固定大小环形队列，不动态增长
存储：本地缓冲使用固定配额（如 64MB），写满后按 FIFO 覆盖
CPU：采集周期 ≥ 5s，避免唤醒休眠 CPU；用事件驱动而非轮询
依赖：不引入重型 runtime，优先静态编译的单二进制

agent:
  interval: 15s
  buffer:
    path: /var/lib/edge-agent/buffer
    max_bytes: 67108864        # 64MiB 环形缓冲
    policy: drop_oldest        # 写满后覆盖最旧
  metrics:
    - name: device_cpu_percent
      source: /proc/stat
      interval: 15s
    - name: device_mem_used_bytes
      source: /proc/meminfo
      interval: 15s
    - name: sensor_temperature_celsius
      source: modbus:0x01:0x0000
      interval: 30s
    - name: sensor_reading
      source: modbus:0x01:0x0010
      interval: 1s
      sample: every_10th       # 高频数据只留 1/10
      aggregate: [min, max, avg]   # 其余聚合成统计量
  uplink:
    protocol: mqtt
    endpoint: mqtts://edge-gw.site-a:8883
    qos: 1
    priority:
      - survival: 0        # 最高优先级
      - health: 1
      - business: 2

对每个指标评估：
  价值：是否参与告警？是否用于容量规划？故障时是否有用？
  成本：字节数 × 频率 × 设备数 × 上行单价

示例（1000 台设备，上行 0.5 元/MB）：
  指标 A：1 条 200B，每 15s 一次
    = 200B × 4/min × 1440 × 1000 / 1024^2 = 约 1.1 GB/月 ≈ 0.55 元/月
  指标 B：原始波形 4KB，每 1s 一次
    = 4KB × 60 × 1440 × 1000 / 1024^2 = 约 330 GB/月 ≈ 165 元/月
  结论：指标 B 必须本地聚合后再传

选择依据：
  状态类指标（CPU、温度）→ drop oldest，旧数据价值低
  计费/审计类数据 → 落盘持久化 + 磁盘水位告警
  事件类（告警、故障）→ 落盘，且优先级最高

消息标识：
  每条消息带 (device_id, seq_no)，seq_no 单调递增
  后端按 (device_id, seq_no) 做幂等去重
  或使用消息级 UUID，后端保留近期 ID 集合

顺序：
  MQTT QoS 1 保证"至少一次"，不保证顺序
  带 seq_no 后，后端可按 seq_no 排序与检测缺口
  缺口检测是重要的可观测信号——它量化了"丢了多少数据"

重放限速：
  恢复后按"追赶速率"上传（如 10 倍实时速率），避免打爆后端
  超过追赶窗口仍未追平，则按优先级丢弃低优先级数据

# 后端检测数据缺口（示意）
# 期望连续 seq，实际缺口即为丢失量
curl -s 'http://edge-backend/api/gaps?device=sensor-0421&window=1h' | jq
# {"device":"sensor-0421","expected":240,"received":231,"gaps":[{"from":118,"to":123}]}

背压信号：
  缓冲区水位（buffer_utilization）持续 > 80%
  → 说明上行能力不足或后端不可达，需告警

自愈动作（agent 内置）：
  水位 > 90% 且持续 5 分钟 → 按优先级丢弃最低优先级数据
  磁盘剩余 < 10% → 清理归档日志，触发磁盘告警
  连续 N 次连接失败 → 指数退避重连，并本地记录连接失败计数
  agent 进程崩溃 → systemd/supervisor 自动重启，重启次数上报

三个理由：
  带宽：1000 台设备各自上报原始数据 vs 网关聚合成 1 条
  延迟：本地告警可在 100ms 内响应，云端往返可能数秒且依赖网络
  成本：云端存储与计算按量计费，边缘算力已付费但常闲置

聚合维度：
  按设备聚合（多指标 → 一条记录）
  按时间聚合（高频 → 降采样统计量）
  按空间聚合（同站点多设备 → 站点级指标）

# 边缘侧聚合规则（示意，Prometheus recording rule 风格）
groups:
- name: edge-aggregation
  interval: 60s
  rules:
  - record: site:device_online_ratio
    expr: |
      count(up{job="edge-devices"} == 1)
      / count(up{job="edge-devices"})

  - record: site:temperature_max
    expr: max by (site) (sensor_temperature_celsius)

  - record: device:reading_avg_5m
    expr: avg_over_time(sensor_reading[5m])

本地（边缘）告警 —— 低延迟、断网可用：
  设备离线、温度超限、磁盘满、本地服务不可用
  动作：本地声光、继电器动作、短信（若网关有 4G 模块）

云端告警 —— 跨站点、需全局视野：
  多站点同一故障模式、容量趋势、版本回归
  动作：工单、电话、值班群

关键：本地告警规则必须与云端规则**分开管理**
  云端规则下推到边缘（GitOps 同步），避免两套配置漂移
  边缘断网时无法拉取新规则，需内置默认规则兜底

组合建议（典型 IoT 场景）：
  生存/健康指标：本地聚合 + 批量 + Protobuf → 压缩比可达 50x 以上
  业务高频数据：本地聚合统计量 + 1 分钟批量
  事件日志：实时单条 + 优先级最高

给每个站点分配预算（如 50MB/天），并在边缘侧计量：
  budget_used_bytes / budget_total_bytes

超预算行为：
  < 80%   正常全量上传
  80~100% 降级：降低业务数据采样率
  > 100%  只保生存/健康/告警数据，业务数据丢弃并记录丢弃计数

丢弃必须可观测：
  记录 dropped_messages_total{priority="business"} 
  这是"数据完整性"的核心指标，比"传了多少"更重要

典型现象：
  设备掉电重启后时钟回到 1970 或固件烧录时间
  长时间无 NTP 导致漂移（廉价晶振每天可漂移数秒）
  多站点时钟不一致，云端按时间对齐时数据错位

后果：
  时序数据写入被拒（时间戳过旧）
  跨设备关联失败（同一事件的日志对不上时间）
  聚合结果错误（乱序数据）

每条遥测数据建议携带：
  device_ts        设备本地时间
  clock_offset_ms  与上一次成功同步的偏移估计
  clock_synced     布尔：是否在同步窗口内
  ingest_ts        网关/云端接收时间（作为兜底时基）

后端策略：
  clock_synced=true  → 使用 device_ts 作为事件时间
  clock_synced=false → 使用 ingest_ts，并标记 time_quality=degraded
  偏差超过阈值的数据进入"待校正"队列，不直接参与告警

# 时钟失同步的设备比例
count(edge_clock_synced == 0) / count(edge_clock_synced)

数据完整性：received / expected（按 seq_no 缺口计算）
数据及时性：ingest_ts - device_ts 的分布
数据新鲜度：now - max(ingest_ts)（发现静默失联的设备）
时钟健康度：失同步设备比例、平均偏移

两级联邦：
  边缘网关：本地 Prometheus/Collector，短期存储（如 7 天）
  区域中心：汇聚区域内站点，做区域聚合
  全局：跨区域查询，长期存储（对象存储 + 索引）

关键设计：
  上行采用远端写（remote_write），而非云端拉取
    —— 边缘在 NAT 后，云端通常无法主动连接
  上行带站点标签（site_id / region / tenant），便于分片
  断网期间边缘本地存储兜底，恢复后回填
  跨站点对比查询靠全局层，本地查询靠边缘层

□ 采集路径不依赖网络，本地缓冲固定配额
□ 每条数据带 device_ts / clock_synced / seq_no
□ 后端按 (device_id, seq_no) 幂等去重并检测缺口
□ 高频数据本地聚合，只传统计量
□ 传输优先级分级，超预算按优先级丢弃并计数
□ 本地告警规则由云端统一下推，边缘内置默认规则
□ 监控"数据质量"本身：完整性、及时性、新鲜度、时钟健康度
□ 站点上行用 remote_write，适配 NAT 与断网回填