Monitoring

The standard way to check the operating status of an Edge.

---

REST Endpoints

Endpoint	Auth	Purpose
GET /api/v1/system/health	Not required	TCP probe of 8 components (cassandra/redis/mqtt/node_red/opc_ua/edge_core/tse/grafana) + overall status. HTTP 503 if DEGRADED — recommended for OTA / k8s probes
GET /api/v1/system/ready	Not required	monitor + V5 api_client readiness
GET /api/v1/system/version	Not required	Metadata.VERSION + BUILD_DATE + image_tag + container_mode — recommended for fleet inventory
GET /api/v1/edge	Required	Edge identity / version / uptime / cumulative transmission count
GET /api/v1/monitoring	Required	System metrics (CPU / memory / disk / network / JVM)
GET /api/v1/opc	Required	Per-OPC connection status / scan status / cumulative point count
GET /api/v1/opc/{opcId}/tag	Required	Tag last value / timestamp / read status
GET /api/v1/transfer	Required	Transmission channel health (API/MQTT/Sparkplug, queue depth)

---

One-line Edge Health Check

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"
}

If sended_count increases over time, the queue → transmission pipeline is running.

---

Per-OPC Status

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

Field	Possible values / meaning
connection_status	CONNECTED / DISCONNECTED / ERROR
scan_status	START / STOP (scheduler status)
tag_count	Number of registered tags
point_count	Cumulative collected points (reset on restart)

To quickly view only problematic OPCs:

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

---

Last Value per Tag

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": ""
  }
}

If value_read_status is ERROR, identify the cause in value_read_error_message.

---

System Metrics

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

Exposes all fields of MonitorBean as-is (varies with the field set at application build time).

---

Sparkplug Verification

If sparkplug.enable=true, you can verify by subscribing to spBv1.0/# with an external client such as paho-mqtt.

# 간단한 체크 스니펫 (참고용)
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()

Expected:

Topic	Frequency
spBv1.0/<group>/NBIRTH/<edge>	Once at boot
spBv1.0/<group>/DBIRTH/<edge>/<opc>	Once per OPC at boot
spBv1.0/<group>/DDATA/<edge>/<opc>	1 message per point
spBv1.0/<group>/NDEATH/<edge>	Once at shutdown (or automatically via will)

---

Log Keywords

grep patterns based on catalina.out:

Pattern	Meaning
Cassandra connected	DB OK
MQTT connected	MQTT broker OK
[SparkPlug] CONNECT / NBIRTH	SPB lifecycle
LS connect success / LS connect failed	LS driver connection
OPCUA connect	OPCUA driver connection
PLC_READ_TIMEOUT_EXCEPTION	Modbus timeout
restartCollector	Collector restart after OPC add/modify/delete
WARN	Threshold exceeded (connection_warn_ms etc.)

---

Transmission Statistics — /api/v1/transfer

This endpoint is already provided. Example response:

{
  "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 }
  ]
}

When more are added, usage examples on this page will be updated.