变电站 / 电力边缘 AI 可观测性（日志 / 指标 / 追踪）手册

调研日期：约 2026-10-25（Asia/Shanghai）
定位：边缘盒上如何采指标、打结构化日志、发出运维告警事件；与 MQTT telemetry、D60/D90、授时、证据仓、多路 RTSP、VLAN 对齐；不进保护网。
衔接：edge-ai-mqtt-hardening-offline-buffer.md、edge-ai-time-sync-ntp-ptp.md、edge-ai-evidence-store-snapshot-retention.md、edge-ai-multistream-rtsp-scheduling.md、edge-ai-d60-d90-acceptance-checklist.md、edge-ai-vlan-network-isolation.md、edge-ai-substation-gateway-bom.md、edge-ai-event-schema-acceptance.md。
公开工具可引用：Prometheus、OpenTelemetry、Grafana、VictoriaMetrics、Loki、Promtail/Alloy；站端具体型号与既有 SIEM unknown。本文不编造未公开站规。

0. 一句话结论与红线

结论：边缘 AI 可观测性以 Metrics + 结构化 JSON 日志 为主、Traces 可选；指标经本机 scrape / MQTT telemetry 上报，运维事件走 events/ops；全部落在 AI / MQ / MGMT VLAN，禁止进入保护二层或过程层。

1. 三大支柱（边缘简化）

原则：先能看水位与否决项，再谈分布式追踪。站内带宽与 SSD 有限时，优先 Metrics + INFO 以上结构化日志。

2. 核心指标清单

命名建议：edgeai_* 前缀；单位用秒/字节/比值的 Prometheus 惯例；cam/task 仅作低基数 label。

禁止：label{event_id=…}、label{uri=…}、每帧新建时间序列。Histogram bucket 站内钉死一版，避免看板爆炸。

3. 导出路径

3.1 本机 Prometheus 文本（推荐默认）

• Agent 暴露 http://127.0.0.1:9108/metrics（端口示例；生产仅 MGMT / 本机 可达，防火墙默认 deny）。
• 可选旁路 node_exporter（系统盘、网卡、温度）；AI 业务指标由 Agent 自暴露，避免与业务进程争锁。
• scrape 间隔建议 15～30 s（边缘）；站内 VictoriaMetrics / Prometheus 单节点即可，保留 7～15 天（更长进地市，unknown 业主策略）。

3.2 OpenTelemetry（可选）

3.3 MQTT telemetry 周期字段表

Topic：edgeai/{org}/{site}/{device_id}/telemetry，QoS0，周期 2～5 s（对齐多路手册）；水位紧时最先丢。

勿在 telemetry 中塞 bbox、人脸图、完整证据路径清单。

3.4 站内 Grafana / VictoriaMetrics 部署注意

3.5 scrape 与告警路由（站内最小）

[边缘盒 Agent :9108/metrics]
        |  scrape 仅 MGMT 源 IP
        v
[VictoriaMetrics 或 Prometheus 单节点] ----> [Grafana 大盘]
        |
        +--> Alertmanager（可选）--> 站内短信/工单 webhook（unknown：业主通道）
        |
        + 并行：MQTT telemetry --> 地市/站控只读订阅（非保护）

Prometheus 告警与 MQTT ops 可双轨：前者给站内值班看大盘，后者进事件总线与审计；二者 code 字段应对齐，避免两套话术。

3.6 采集侧伪代码要点（防堵推理）

# 热路径：decode -> infer -> event_q
# 旁路：metrics registry 无锁或分片；log/telemetry 写入有界 channel
on_tick_2s:
  snapshot = copy_gauges()          # 不持推理锁
  try_send_mqtt_telemetry(snapshot) # 满则 drop；永不 join 推理线程
  maybe_flush_json_log()            # 异步
scrape_handler:
  return registry.text()            # 只读；超时快速失败

硬门禁：人为断开 Broker 与故意打满 log 盘时，推理线程不得出现同步 fsync/网络 send。

4. 结构化日志

4.1 JSON 字段约定

每行一条 JSON（newline-delimited）：

{
  "ts": "2026-10-25T01:05:00.123Z",
  "device_id": "box-rk3588-07",
  "site": "SS-220-01",
  "task": "ops",
  "event_id": null,
  "level": "WARN",
  "code": "STREAM_DOWN",
  "cam": "bay3-camA",
  "msg": "rtsp reconnect exhausted",
  "ctx": { "fail_count": 5, "last_error": "timeout" }
}

4.2 轮转、保留与分盘

5. 运维告警事件码（ops）

走 MQTT：edgeai/{org}/{site}/{device_id}/events/ops，QoS1；event.code 用下表；禁止映射为保护动作。

业务告警码（如 PPE_NO_HELMET）仍走 events/{task}，与 ops 分 topic，看板分面板。

6. 两周落地清单

7. 可勾选验收门禁

8. 衔接索引

9. unknown / 边界声明

• 业主现网 SIEM、syslog 服务器地址与保留年限：unknown（对接时补）。
• 具体 NPU 利用率 sysfs/API 路径随芯片而异：unknown，以板卡 BSP 为准。
• 合同级 P95 延迟与温度阈：unknown，须试点实测写入 SOW，禁止抄 Zoo。
• 电力二次安防细则、等保测评条款：不由本文替代；分区与出口须安监终审。
• OpenTelemetry / Grafana / Loki 等 SPDX 与商用插件许可以官网为准，嵌入发行前过许可台账。

文末：可观测性是「能报、能断线、能追责」的运维面——看得到 FPS 与水位，叫得应 ops 事件，且永远不进保护网。