진단 / 점검
장애 / 이상 동작이 의심될 때 사용하는 진단 스크립트 모음.
2026.05+ 컨테이너 모드는 pe-doctor 가 표준
아래 절차는 native 박스 (bin/ps.sh, bin/log-viewer.sh) 용. 컨테이너 모드:
bash /opt/kopens/install/bin/status.sh # 한 줄 상태
bash /opt/kopens/install/bin/health.sh # 종합 헬스 (exit 0/1)
bash /opt/kopens/install/bin/logs.sh -f tomcat # 로그 follow
sudo bash /opt/kopens/install/bin/doctor.sh # 진단 일괄 tarball (support escalation)
상세: 컨테이너 모드 운영 가이드 + /opt/kopens/install/RUNBOOK.md.
1. 단계별 진단 절차
# 1. 누가 죽었나?
$PE_HOME/bin/ps.sh
# 2. 어디가 시끄러운가?
$PE_HOME/bin/log-viewer.sh
# (실시간 — Ctrl+C 로 빠져나옴)
# 3. Cassandra 의심
$PE_HOME/bin/node-info.sh
# 4. Disk 의심
df -h /data1
du -sh $PE_HOME/*/log/* /data1/* 2>/dev/null | sort -h | tail -20
# 5. 다 안 맞으면 — 안전하게 단계적 재시작
$PE_HOME/bin/restart.sh # 1차: Tomcat 만
# 그래도 이상 시
$PE_HOME/bin/stop.sh
$PE_HOME/bin/start.sh # 2차: 전체
# 그래도 이상 시
sudo $PE_HOME/bin/reboot.sh # 3차: OS 재부팅 (최후의 수단)
2. 주의 — 비대화형 셸에서는 log-viewer.sh 호출 금지
log-viewer.sh 는 무한 tail -f 입니다. CI / cron 같은 비대화형 환경 에서 호출하면 ssh 세션이 끝나지 않습니다. 대화형 셸 일 때만 사용하세요.
3. log-viewer.sh — 통합 로그 tail
$PE_HOME/bin/log-viewer.sh
7개 로그 를 실시간으로 한 화면에:
- Tomcat (
server/logs/catalina.out) - timeseries-engine
- Cassandra (
db/logs/system.log) - HiveMQ (
mqtt/log/hivemq.log) - Node-RED (
node/log/node-red.log) - Redis cache
- 기타
Ctrl+C 로 종료. 장애 발생 시 가장 먼저 실행 하는 도구.
4. ps.sh
$PE_HOME/bin/ps.sh
plantpulse 키워드로 살아있는 자바 프로세스 목록. 정상 상태에서는 다음이 모두 보여야 합니다:
| 프로세스 | 의미 | PID 환경 변수 |
|---|---|---|
apache.cassandra.service.CassandraDaemon | Cassandra | cassandra.pid |
hivemq.jar | MQTT | (없음) |
plantpulse.timeseries.engine.Main | 시계열 엔진 | (없음) |
org.apache.catalina.startup.Bootstrap | Tomcat | CATALINA_PID |
node-red (Node.js) | Node-RED | (없음) |
빠진 게 있으면 그 컴포넌트가 죽은 것 — start.sh 또는 해당 sub-component 의 bin/start.sh 로 되살립니다.
5. node-info.sh — Cassandra 상태
$PE_HOME/bin/node-info.sh
대표 출력 (nodetool info):
ID : 8a4d...
Gossip active : true
Native Transport active: true
Load : 1.21 GiB
Generation No : 1778176430
Uptime (seconds) : 1234
Heap Memory (MB) : 824.10 / 2048.00
| 점검 포인트 | 의미 |
|---|---|
Native Transport active : true | 9042 클라이언트 포트 listen 중 |
Heap > 80% | OOM 임박 — 데이터 정리 / heap 늘리기 |
Load 가 디스크의 80% 초과 | sstable 청소(node-cleanup.sh) 또는 디스크 증설 |
6. node-cql.sh — cqlsh 대화형
$PE_HOME/bin/node-cql.sh
cqlsh -u cassandra -p ... 가 자동으로 실행되어 keyspace pe 에 접속됩니다. 수동 데이터 점검 용 — 운영 중 직접 INSERT/UPDATE 는 권장하지 않습니다 (캐시 미반영, 복제 미일치 등).
자주 쓰는 조회 예:
USE pe;
SELECT count(*) FROM app_tag;
SELECT opc_id, opc_type FROM app_opc;
DESCRIBE TABLE app_tag;
7. network-speed-test.sh
$PE_HOME/bin/network-speed-test.sh
product.kopens.io 에서 speedtest.py 를 받아 실행해 외부 망 속도를 측정. 회선이 느리면 업그레이드 도 길어집니다 — 업그레이드 전 진단용.
8. 자주 빠지는 함정 — 종합
| 증상 | 원인 / 해결 |
|---|---|
restart.sh 후 OPC 가 0/N 연결 | 드물게 발생하는 시작 race. restart.sh 한 번 더 호출 |
clean.sh 후 ssh 세션 갑자기 끊김 | /tmp/* 가 ssh socket 까지 지움 — 다른 세션으로 재접속 |
upgrade.sh 도중 다운로드 실패 | 외부 망 / product.kopens.io 점검. network-speed-test.sh |
start.sh 가 너무 오래 멈춤 ([4] DB START) | Cassandra commitlog 회수 — 보통 30s+ 대기. 그래도 안 끝나면 db/logs/system.log 확인 |
| Tomcat 만 자꾸 죽음 | OOM 가능성 — server/logs/catalina.out 의 OutOfMemoryError / heapdump 디렉토리 확인 |
| Node-RED 가 Deploy 후 사라짐 | userDir 손상. $PE_HOME/node/conf 의 master 사본으로 복구되도록 설계 — node/bin/start.sh 가 자동 sync |
| 외부에서 게이트웨이 접속 안 됨 | 방화벽 (firewall-cmd --list-all 또는 iptables -L) / SELinux 정책 / 라우터 NAT 점검 |
9. 더 알아보기
- 디스크 부족 시: 정리 / 청소
- 단계적 장애 진단 시나리오: 운영 시나리오
- 모니터링 (REST 메트릭): 모니터링 (운영자/REST)