监控

查看 Edge 运行状态的标准途径。

---

REST 端点

端点	认证	用途
GET /api/v1/system/health	不需要	8 个组件 (cassandra/redis/mqtt/node_red/opc_ua/edge_core/tse/grafana) TCP probe + 综合 status。HTTP 503 if DEGRADED — 推荐用于 OTA / k8s probe
GET /api/v1/system/ready	不需要	monitor + V5 api_client 就绪状态
GET /api/v1/system/version	不需要	Metadata.VERSION + BUILD_DATE + image_tag + container_mode — 推荐用于 fleet inventory
GET /api/v1/edge	需要	Edge 标识 / 版本 / 运行时间 / 累计发送条数
GET /api/v1/monitoring	需要	系统指标 (CPU / 内存 / 磁盘 / 网络 / JVM)
GET /api/v1/opc	需要	各 OPC 的连接状态 / 扫描状态 / point 累计数
GET /api/v1/opc/{opcId}/tag	需要	标签最后值 / 时间 / read status
GET /api/v1/transfer	需要	传输通道健康状态 (API/MQTT/Sparkplug、队列深度)

---

Edge 健康状态一行巡检

curl -s http://<edge-host>/api/v1/edge | jq '{started, uptime_ms, sended_count, version}'

{
  "started": true,
  "uptime_ms": 124500,
  "sended_count": 8063,
  "version": "2025"
}

若 sended_count 随时间增加，说明队列 → 传输管道正在运行。

---

各 OPC 状态

curl -s http://<edge-host>/api/v1/opc \
  | jq '.data.data[] | {opc_id, opc_type, connection_status, scan_status, tag_count, point_count}'

字段	可能值 / 含义
connection_status	CONNECTED / DISCONNECTED / ERROR
scan_status	START / STOP (调度器状态)
tag_count	已注册标签数
point_count	累计采集 Point (重启时重置)

仅快速查看有问题的 OPC：

curl -s http://<edge-host>/api/v1/opc \
  | jq '.data.data[] | select(.connection_status != "CONNECTED")'

---

各标签的最后值

curl -s http://<edge-host>/api/v1/tag/<TAG_ID>/value | jq

{
  "result": "OK",
  "data": {
    "tag_id": "TAG_UA_0004",
    "value": "28.9688",
    "value_time": "2026-05-06 20:59:39.000",
    "value_read_status": "SUCCESS",
    "value_read_error_message": ""
  }
}

若 value_read_status 为 ERROR，请在 value_read_error_message 中排查原因。

---

系统指标

curl -s http://<edge-host>/api/v1/monitoring | jq '.data | {cpu_usage, memory_usage, disk_usage, thread_count}'

原样暴露 MonitorBean 的全部字段 (随应用构建时点的字段 set 而变化)。

---

Sparkplug 验证

若为 sparkplug.enable=true，可使用 paho-mqtt 等外部客户端订阅 spBv1.0/# 进行确认。

# 간단한 체크 스니펫 (참고용)
import os
import paho.mqtt.client as mqtt

def on_message(c, u, m):
    print(m.topic, len(m.payload))

c = mqtt.Client()
c.username_pw_set(os.environ["MQTT_USER"], os.environ["MQTT_PASSWORD"])
c.on_message = on_message
c.connect("<edge-host>", 1883)
c.subscribe("spBv1.0/#")
c.loop_forever()

预期值：

主题	频率
spBv1.0/<group>/NBIRTH/<edge>	启动时 1 次
spBv1.0/<group>/DBIRTH/<edge>/<opc>	启动时按 OPC 数量
spBv1.0/<group>/DDATA/<edge>/<opc>	每 1 Point 1 条
spBv1.0/<group>/NDEATH/<edge>	关闭时 1 次 (或 will 自动触发)

---

日志关键字

基于 catalina.out 的 grep 模式：

模式	含义
Cassandra connected	DB OK
MQTT connected	MQTT broker OK
[SparkPlug] CONNECT / NBIRTH	SPB 生命周期
LS connect success / LS connect failed	LS 驱动连接
OPCUA connect	OPCUA 驱动连接
PLC_READ_TIMEOUT_EXCEPTION	Modbus 超时
restartCollector	OPC 增加/修改/删除后 collector 重启
WARN	超出阈值 (connection_warn_ms 等)

---

传输统计 — /api/v1/transfer

该端点已提供。响应示例：

{
  "queue_depth": 1234,
  "queue_capacity": 10000,
  "transfers": [
    { "type": "API",       "status": "OK",  "sent": 12345, "errors": 0 },
    { "type": "MQTT",      "status": "OK",  "connected": true, "topic": "/edge/point" },
    { "type": "Sparkplug", "status": "OK",  "connected": true, "bdSeq": 3, "seq": 142, "devices": 10 }
  ]
}

如有新增，本页将更新使用示例。