> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/user/system.md).
# 시스템
## 목차
* [개요](#overview)
* [화면 구성 — System 그룹](#layout)
* [모니터링 화면 (`/monitoring/index`)](#monitoring)
* [상단 — 서버 시작 시각](#mon-top)
* [인프라 헬스 (6분할 패널)](#mon-infra)
* [데이터 파이프라인 다이어그램](#mon-pipeline)
* [연결 히트맵](#mon-heatmap)
* [엔진 메트릭 6 패널](#mon-metrics)
* [로그 화면 (`/log/index`)](#log)
* [상단 검색 영역](#log-search)
* [타임라인 + 빠른 시간 범위](#log-timeline)
* [로그 테이블 (6컬럼)](#log-table)
* [설정 화면 (`/config/index`)](#config)
* [상단 도구](#config-top)
* [설정 목록 테이블](#config-list)
* [설정 추가/수정 양식](#config-form)
* [환경정보 화면 (`/env/view`)](#env)
* [활용 시나리오](#use-cases)
* [자주 묻는 질문](#faq)
* [관련 화면](#related)
***
## 개요
시스템 메뉴는 플랫폼 자체의 운영 상태, 보안 계정, 설정, 로그, 환경정보, 클러스터, 외부 고급 모니터링을 모아 둔 영역입니다. 현재 좌측 메뉴의 **System** 그룹은 다음 항목을 포함합니다.
| 하위 메뉴 | 내부 URL / 외부 포트 | 용도 |
| ----------- | --------------------- | ----------------------------------- |
| **사용자** | `/user/index` | 사용자 계정 관리 |
| **보안 정책** | `/security/index` | 비밀번호·접근 보안 정책 |
| **API 토큰** | `/token/index` | 외부 연동용 API 토큰 |
| **모니터링** | `/monitoring/index` | 인프라 헬스·데이터 파이프라인·엔진 메트릭 실시간 대시보드 |
| **진단** | `/diagnostic/index` | 시스템 진단 이벤트 조회 |
| **로그** | `/log/index` | 서버 애플리케이션 로그(클래스·메소드·라인 단위)를 시간순 조회 |
| **설정** | `/config/index` | 시스템 동작 키-값 설정 관리 (재적용/재시작) |
| **환경정보** | `/env/view` | 프로퍼티 파일별 환경 설정 값을 탭별로 조회 |
| **클러스터** | `/cluster/index` | 클러스터 노드 상태 |
| **고급 모니터링** | `http://[현재호스트]:3000` | 외부 모니터링 대시보드 |
이 문서는 그중 **모니터링 / 로그 / 설정 / 환경정보**를 중심으로 설명합니다. 사용자·보안·토큰은 [보안 관리](/plantpulse-platform/user/security.md), 진단은 [진단](/plantpulse-platform/user/diagnostic.md), 외부 도구는 [표준 및 외부 도구](/plantpulse-platform/user/tools.md) 를 함께 참고하세요.
***
## 화면 구성 — System 그룹
| 화면 | 주된 사용자 | 한줄 요약 |
| ----------- | ------- | ---------------------------------------------- |
| **모니터링** | 시스템 관리자 | 6분할 인프라 헬스 + 파이프라인 + 6 엔진 메트릭 |
| **진단** | 운영자/관리자 | 시스템 진단 이벤트와 INFO/WARN/ERROR 흐름 |
| **로그** | 운영자/관리자 | 클래스·메소드·라인 정보까지 포함된 상세 애플리케이션 로그 |
| **설정** | 시스템 관리자 | 시스템 키-값 설정 추가·수정·캐시 재적용 |
| **환경정보** | 시스템 관리자 | 프로퍼티 파일(엔진/애플리케이션/메시지큐/스토리지/메일/웹소켓) 조회 (읽기 전용) |
| **클러스터** | 시스템 관리자 | 클러스터 노드, 모드, 지연, 리소스 상태 |
| **고급 모니터링** | 시스템 관리자 | 외부 포트 `3000` 의 장기/상세 메트릭 대시보드 |
***
## 모니터링 화면 (`/monitoring/index`)
플랫폼 자체의 실시간 운영 메트릭을 대시보드 형태로 표시합니다.
### 상단 — 서버 시작 시각
```
🩺 모니터링 YYYY-MM-DD HH:MM:SS 에 서버가 시작됨 [↻]
```
| 항목 | 표시 |
| ------ | -------------------------------------------------------------------- |
| 페이지 제목 | 🩺 "모니터링" |
| 보조 정보 | 서버 시작 시각 (회색 작은 글씨) — `EngineManager.getInstance().getStartedDate()` |
| 새로고침 | 빨강 버튼 + ↻ — 모든 메트릭 다시 불러오기 |
### 인프라 헬스 (6분할 패널)
상단 패널의 6분할 구성. 각 셀은 같은 폭(약 16.66%) 으로 배치됩니다.
| 셀 | 아이콘 | 라벨 | 표시값 ID |
| - | ---------- | ----------- | ----------------------- |
| 1 | 💾 (메모리) | **캐시** | `side_jmx_h_redis` |
| 2 | 🔌 (플러그) | **웹소켓** | `side_jmx_h_stomp` |
| 3 | 📡 (위성 접시) | **MQTT** | `side_jmx_h_mqtt` |
| 4 | 🌊 (스트림) | **KAFKA** | `side_jmx_h_kafka` |
| 5 | 🗄️ (DB) | **이벤트 스토어** | (헬스 ID — 이벤트 영구 저장소 상태) |
| 6 | 🕐 (시계) | **시계열 엔진** | `side_jmx_h_timeseries` |
각 셀은 정상/이상 상태를 색상 텍스트로 표시합니다. 모두 정상이면 운영이 안정 상태입니다.
### 데이터 파이프라인 다이어그램
| 항목 | 설명 |
| ------ | ------------------------------------------------------------------------ |
| **헤더** | ⚡ "데이터 파이프라인" |
| **본문** | `pipeline_diagram` — 580px 높이 다이어그램 — 인입 → 검증 → 변환 → 저장 흐름의 노드와 처리량을 시각화 |
각 노드 위에 처리량(초당 건수)·대기·드롭 지표가 표시됩니다.
### 연결 히트맵
```
🌐 연결 히트맵 N 에이전트
[■][■][■][■][■][■]... ← 24×24px 색 블록 그리드
─────────────────────────
🟢 정상 N 🟠 지연 N 🔴 이상 N ⬜ 미연결 N
```
| 항목 | 의미 |
| -------- | ------------------------------------ |
| 헤더 | 🌐 "연결 히트맵 " + N 에이전트 (등록된 OPC 수) |
| 격자 본문 | 데이터소스별 색 블록 (`eq-block` 24×24px) |
| 블록 hover | 데이터소스명·타입 툴팁 |
| 블록 클릭 | `/connect/view?opc_id=...` 상세 화면 새 창 |
#### 색상 의미 (요약)
| 색상 | 의미 | ID 카운터 |
| ----- | --- | ----------------- |
| 🟢 녹색 | 정상 | `heatmap_ok` |
| 🟠 주황 | 지연 | `heatmap_warn` |
| 🔴 빨강 | 이상 | `heatmap_error` |
| ⬜ 회색 | 미연결 | `heatmap_unknown` |
### 엔진 메트릭 6 패널
3열×2행 격자에 6개 메트릭 패널. 각 패널은 좌측 키-값 표 + 우측/하단 작은 차트로 구성됩니다.
#### 1) PPS (초당 수집 · 최근 1분)
| 항목 | ID | 설명 |
| ------ | ----------------------------- | ----------------- |
| 현재 PPS | `side_pps_current` | 초당 수집 포인트 (`p/s`) |
| 최대 PPS | `side_pps_max` | 최근 1분 최대값 (`p/s`) |
| 차트 | `side_realtime_chart` (220px) | 1분 라인 차트 |
#### 2) JVM 힙
| 항목 | ID |
| -- | ----------------------- |
| 사용 | `side_jmx_heap_used` |
| 전체 | `side_jmx_heap_total` |
| GC | `side_jmx_gc` (밀리초) |
| 차트 | `mon_jvm_chart` (150px) |
#### 3) 파이프라인
| 항목 | ID |
| ----- | ---------------------------- |
| 태스크 | `side_jmx_pipe_task` |
| 처리 완료 | `side_jmx_pipe_processed` |
| 큐 대기 | `side_jmx_pipe_pending` |
| 차트 | `mon_pipeline_chart` (100px) |
#### 4) 스토리지
| 항목 | ID |
| ----- | --------------------------- |
| 총 저장 | `side_jmx_store_saved` |
| 쓰기/초 | `side_jmx_store_wps` |
| 버퍼 대기 | `side_jmx_store_buf` |
| 활성 배치 | `side_jmx_store_batch` |
| 차트 | `mon_storage_chart` (100px) |
#### 5) 메세징
| 항목 | ID |
| ----- | -------------------------- |
| 총 수신 | `side_jmx_msg_total` |
| 초당 수신 | `side_jmx_msg_rate` (`/s`) |
| KAFKA | `side_jmx_msg_kafka` |
| MQTT | `side_jmx_msg_mqtt` |
| 차트 | `mon_msg_chart` (100px) |
#### 6) 스트리밍·비동기·진단
화면 다른 영역에 연속해서 스트리밍·비동기 실행기·진단 카운트가 표시됩니다 ([대시보드 — 우측 헬스 레일](/plantpulse-platform/user/summary.md#health-rail) 과 동일한 운영 지표 계열).
***
## 로그 화면 (`/log/index`)
서버 애플리케이션의 코드 레벨 로그(클래스·메소드·라인)를 시간순으로 조회합니다. `/diagnostic/index` 의 진단 로그와 달리 **개발자/관리자가 디버깅에 사용** 하는 상세 로그입니다.
### 상단 검색 영역
```
📋 로그 [기간 ▭▭▭▭] [레벨 ▼] [건수 ▼] [조회] [전체 출력] [↻]
```
| 컨트롤 | 폭 | 설명 |
| -------------------------- | ------------- | ----------------------------------- |
| **기간** (`search_time`) | 280px | 시작\~종료 (가운데 정렬, 굵은 글씨) |
| **레벨** (`level`) | 100px | 전체 레벨/INFO/WARN/ERROR |
| **메세지** (`message`) | 250px (숨김 기본) | 키워드 검색. 운영 환경에 따라 노출 |
| **건수** (`limit`) | 130px | 50/100/200/300/500/1,000 |
| **조회** | 빨강 + 🔍 | `search()` |
| **전체 출력** | 빨강 + 📄 | `downloadCSV()` — 검색 조건의 전체 로그를 CSV |
| **새로고침** (`realtime_icon`) | 빨강 + ↻ | `refresh()` |
> hidden 필드 `app_name` 의 기본값은 `SERVER` 입니다. 즉 이 화면은 서버 애플리케이션 로그만 조회합니다.
### 타임라인 + 빠른 시간 범위
진단 화면과 동일한 6 버튼 빠른 시간 범위(`10M`/`30M`/`1H`/`6H`/`12H`/`ALL`) 와 타임라인(`alarm_timeline`).
### 로그 테이블 (6컬럼)
진단 화면보다 한 단계 더 깊은 코드 레벨 정보를 표시합니다.
| 컬럼 | 폭 | 설명 |
| ---------- | ----- | -------------------------- |
| **레벨** | 80px | INFO/WARN/ERROR 색상 뱃지 |
| **시간** | 160px | 로그 발생 시각 |
| **로그 클래스** | 200px | 자바 클래스 풀네임 |
| **메소드 명** | 120px | 호출된 메소드 |
| **라인 넘버** | 80px | 소스 코드의 라인 번호 |
| **메세지** | 자동 | 로그 본문 + stack trace (있을 때) |
> 로그 클래스/메소드/라인 정보는 시스템 관리자가 코드 위치를 정확히 짚어 디버깅할 때 유용합니다. 일반 운영 이상 신호 추적은 [진단](/plantpulse-platform/user/diagnostic.md) 화면이 더 적합합니다.
***
## 설정 화면 (`/config/index`)
시스템 동작에 필요한 키-값 설정을 추가·수정·삭제하고, 캐시를 재적용하는 화면입니다.
### 상단 도구
```
🎚️ 시스템 설정 [설정 키 검색 ...] [조회] [↻] | [➕ 설정 추가] [🔄 재적용]
```
| 컨트롤 | 폭 | 설명 |
| ------------------------------ | ------- | ----------------------------------------------------------------------- |
| **설정 키 검색** (`search_keyword`) | 200px | placeholder: "설정 키 검색 ..." |
| **조회** | 빨강 + 🔍 | `search()` — 키워드 필터 적용 |
| **새로고침** | 빨강 + ↻ | `refresh()` |
| **설정 추가** | 빨강 + ➕ | `addConfig()` — 새 설정 추가 폼 열기 |
| **재적용** | 파랑 + 🔄 | `refreshCache()` — 서버 재시작 없이 설정 캐시 재적용 (툴팁: "서버 재시작 없이 설정 캐시를 재적용합니다.") |
### 설정 목록 테이블
| 컬럼 | 폭 | 설명 |
| -------- | ----- | ------------------------------------ |
| **설정 키** | 300px | 시스템이 인식하는 키 (예: `engine.timeout.ms`) |
| **설정 값** | 600px | 키의 현재 값 |
| **설명** | 자동 | 키 용도 메모 |
| **수정일** | 150px | 마지막 수정 시각 |
| **액션** | 80px | 수정·삭제 버튼 |
페이지 하단에 안내 박스가 표시됩니다.
> ℹ️ **시스템 설정 안내** 시스템 동작에 필요한 키-값 설정을 관리합니다. 설정 변경 후 일부 항목은 서버 재시작이 필요할 수 있습니다.
### 설정 추가/수정 양식
상단 **설정 추가** 또는 목록의 액션으로 설정 양식 화면(`/config/form`)으로 이동합니다.
| 입력 | 설명 |
| -------- | ------------------------------------------ |
| **설정 키** | 영문/숫자/`.`/`_` 만 사용. 예: `engine.timeout.ms` |
| **설정 값** | 텍스트 (숫자·boolean·JSON 모두 가능, 키 정의에 따라 다름) |
| **설명** | 자유 텍스트 (운영자가 식별 용이하도록 메모) |
저장 후 즉시 반영하려면 목록 화면으로 돌아와 **재적용** 을 누르세요. 일부 설정은 서버 재시작이 필요할 수 있습니다.
***
## 환경정보 화면 (`/env/view`)
플랫폼이 부팅 시 읽어 들이는 프로퍼티 파일들을 그룹별 탭으로 조회하는 **읽기 전용** 화면입니다.
### 상단 안내 박스
> ❓ **시스템 환경 정보** 서버 시스템에 설정된 환경 정보를 프로퍼티 파일별로 표시합니다. 환경 설정 변경은 각 파일을 수정하십시오.
>
> * 설정이 변경되면 서버를 재시작해야 합니다.
### 6 탭 구성
| 탭 | 표시 |
| ---------- | ------------------------------ |
| **엔진** | 엔진 코어 동작 설정 (시간/스레드/큐 한계 등) |
| **애플리케이션** | 웹 애플리케이션 일반 설정 |
| **메시지 큐** | 메시지 채널 연결 설정 (브로커 호스트·인증·토픽 등) |
| **스토리지** | 시계열·이벤트 저장소 연결 설정 |
| **메일** | 이메일 발송 SMTP 설정 |
| **웹소켓** | 실시간 푸시 채널 설정 |
### 각 탭의 표 (공통)
| 컬럼 | 표시 |
| ------- | ---------------------------- |
| **키** | 프로퍼티 키 |
| **설정값** | 현재 값 (마스킹된 비밀번호는 `***` 로 표시) |
> 환경정보 화면에서는 값을 **수정할 수 없습니다**. 변경이 필요하면 시스템 관리자가 서버의 해당 프로퍼티 파일을 직접 수정한 후 서버를 재시작해야 합니다.
***
## 활용 시나리오
| 시나리오 | 화면 | 절차 |
| ---------------------- | ---- | -------------------------------------------------- |
| **PPS가 평소보다 떨어진다** | 모니터링 | PPS 패널 차트 → 인프라 헬스 6분할 → 데이터 파이프라인 다이어그램의 병목 노드 식별 |
| **GC가 길다 / 메모리 누수 의심** | 모니터링 | JVM 힙 패널의 GC 시간 추이 → 시스템 관리자 통보 |
| **서버 시작 직후 정상 가동 확인** | 모니터링 | 상단 시작 시각 + 인프라 헬스 6셀 모두 정상 + 연결 히트맵 녹색 |
| **특정 클래스에서 ERROR 추적** | 로그 | 레벨=ERROR + 메시지 검색에 클래스명 키워드 → 라인 번호 포함 로그 분석 |
| **일시적으로 설정 변경 적용** | 설정 | 설정 추가/수정 → **재적용** (재시작 없음) |
| **비밀번호 정책·세션 시간 변경** | 환경정보 | 애플리케이션 탭에서 현재 값 확인 → 시스템 관리자가 파일 수정 → 서버 재시작 |
| **연결 히트맵에서 빨강 블록 식별** | 모니터링 | 빨강 블록 클릭 → 데이터소스 상세 화면 새 창으로 이동 |
***
## 자주 묻는 질문
**Q. 모니터링 화면이 진단 화면과 무엇이 다른가요?** A. **모니터링** 은 플랫폼 자체의 실시간 운영 메트릭(처리량·메모리·헬스), **진단** 은 모듈별 INFO/WARN/ERROR 이벤트 로그입니다. 둘 다 시스템 관리자가 사용하지만 모니터링은 "지금 어떤가?", 진단은 "무슨 일이 있었나?" 에 답합니다.
**Q. 모니터링의 인프라 헬스가 한 칸이라도 빨간색입니다.** A. 해당 컴포넌트가 응답하지 않거나 헬스 체크 실패 상태입니다. 즉시 [진단](/plantpulse-platform/user/diagnostic.md) 화면에서 SERVER 또는 해당 컴포넌트의 ERROR 로그를 확인하시고, 동시에 시스템 관리자에게 통보하세요.
**Q. 데이터 파이프라인 다이어그램의 노드가 회색입니다.** A. 그 단계가 활성화되지 않았거나 처리 데이터가 없는 상태입니다. 평상시 회색이 정상인 단계도 있고(예: 백업·아카이빙), 인입 시간대인데 회색이면 문제일 수 있습니다.
**Q. 연결 히트맵에서 한 블록이 빨강입니다.** A. 그 데이터소스의 연결이 이상 상태입니다. 블록 클릭으로 상세 화면(`/connect/view`)에 가시거나, [연결 관리 > 상태](/plantpulse-platform/user/connection.md) 화면에서 좌측 24시간 이력을 확인하세요.
**Q. 로그 화면과 진단 화면은 어느 쪽을 봐야 하나요?** A. **이상 신호 추적**은 [진단](/plantpulse-platform/user/diagnostic.md), **코드 레벨 디버깅**은 로그입니다. 진단에서 ERROR 가 잡혔는데 메시지가 부족하면 같은 시각에 로그 화면에서 그 클래스/메소드의 상세 로그를 추가로 보세요.
**Q. 설정 화면의 "재적용" 버튼은 안전한가요?** A. 서버 재시작 없이 메모리 캐시만 새로고침합니다. 대부분의 설정에 안전하지만 일부 설정(스레드 풀 크기·DB 연결 풀 등)은 재시작이 필요합니다. 재적용 후 의도한 동작이 안 되면 시스템 관리자에게 문의하세요.
**Q. 환경정보의 값을 화면에서 바꾸고 싶어요.** A. 환경정보 화면은 읽기 전용입니다. 변경은 서버 측 프로퍼티 파일을 수정 후 서버를 재시작해야 합니다. 화면에서 변경 가능한 키-값은 [설정](#config) 화면에서 관리합니다.
**Q. 로그의 "전체 출력" CSV 가 너무 큽니다.** A. 검색 조건의 기간을 짧게(1시간 이내), 레벨을 ERROR/WARN 으로 좁혀 다시 다운로드하세요. 또는 CSV 다운로드 후 외부 분석 도구로 가져가세요.
**Q. 모니터링 화면이 자동으로 갱신되나요?** A. 모니터링은 실시간 푸시로 자동 갱신됩니다. 메트릭이 멈춰 있다면 헤더의 실시간 연결 상태가 빨강인지 먼저 확인하세요.
***
## 관련 화면
* [대시보드](/plantpulse-platform/user/summary.md) — 운영자용 메인 대시보드 (KPI + 우측 헬스 레일)
* [진단](/plantpulse-platform/user/diagnostic.md) — 모듈별 진단 로그
* [일일 통계](/plantpulse-platform/user/statistics.md) — 일일 운영 통계
* [연결 관리](/plantpulse-platform/user/connection.md) — 데이터소스 연결 상태 모니터링
* [상태 코드 정의](/plantpulse-platform/user/status.md) — 인프라 헬스/연결 상태 코드 매핑
* [보안 관리](/plantpulse-platform/user/security.md) — 사용자·정책·API 토큰