모니터링

엣지의 운영 상태를 확인하는 표준 경로.

---

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	필요	엣지 식별 / 버전 / 가동 시간 / 누적 송신 건수
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, 큐 깊이)

---

엣지 헬스 한 줄 점검

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

추가되면 본 페이지에 사용 예시를 갱신합니다.