> 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/diagnostic.md).

# 진단

## 목차

* [개요](#overview)
* [화면 구성](#layout)
* [상단 검색 영역](#search-toolbar)
* [타임라인](#timeline)
* [좌측 — 진단 로그 테이블](#log-table)
* [우측 통계 패널 (3개)](#stats-panels)
* [전체 출력 (CSV)](#csv)
* [장애 발생 시 표준 진단 절차](#playbook)
* [자주 보는 진단 메시지 패턴](#patterns)
* [자주 묻는 질문](#faq)
* [관련 화면](#related)

***

## 개요 <a href="#overview" id="overview"></a>

진단 화면은 플랫폼 내부에서 발생한 모든 진단 이벤트(정보·경고·심각)를 시간순 타임라인 + 표 + 통계 차트 3가지 시점으로 함께 보여 줍니다. 시스템 관리자나 운영자가 장애 원인을 파악할 때 가장 먼저 들어오는 화면입니다.

이 화면은 다음 동작을 하나로 묶고 있습니다.

* **타임라인** — 시간 흐름에서 어디에 무슨 일이 있었는지 한눈에
* **로그 표** — 정확한 시각·애플리케이션·레벨·메시지 내용
* **통계 패널** — 레벨 비율·시간대 분포·애플리케이션 분포

**경로**: 왼쪽 메뉴 > **System > 진단** (내부 URL `/diagnostic/index`)

***

## 화면 구성 <a href="#layout" id="layout"></a>

```
┌───────────────────────────────────────────────────────────────────────────────┐
│ 🩺 진단                                                                          │
│   [기간]  [애플리케이션]  [레벨]  [건수]  [조회] [전체 출력] [↻]                  │ ← ① 검색 영역
├───────────────────────────────────────────────────────────────────────────────┤
│                          타임라인 + 빠른 시간 범위                                │ ← ② 타임라인
├──────────────────────────────────────────────────────────┬────────────────────┤
│                                                          │ 🥧 통계             │
│                  진단 로그 테이블                          │  검색된 진단 N건    │
│      애플리케이션 │ 레벨 │ 시간      │ 메세지              │  정보·경고·심각 뱃지│ ← ③
│      ...                                                 │  레벨 비율 차트     │
│                                                          ├────────────────────┤
│                                                          │ 📊 시간별 발생 추이 │
│                                                          ├────────────────────┤
│                                                          │ 🖥 애플리케이션별  │
│                                                          │   분포              │
└──────────────────────────────────────────────────────────┴────────────────────┘
```

| 영역      | 위치       | 표시                                |
| ------- | -------- | --------------------------------- |
| ① 검색 영역 | 우상단 form | 기간·애플리케이션·레벨·표시건수 + 조회/전체 출력/새로고침 |
| ② 타임라인  | 전체 폭     | 시간 흐름 위에 진단 마커 + 빠른 시간 범위 6 버튼    |
| ③ 좌측    | col-lg-8 | 진단 로그 테이블(고정 4컬럼)                 |
| ③ 우측    | col-lg-4 | 통계 3개 패널(레벨 비율·시간 추이·애플리케이션 분포)   |

***

## 상단 검색 영역 <a href="#search-toolbar" id="search-toolbar"></a>

페이지 우상단의 검색 폼은 한 줄로 배치되어 있고, 좌→우 순서로 다음 컨트롤이 있습니다.

### 입력 필드와 버튼

| 컨트롤                        | 폭          | 형태                    | 기본값·옵션                                                 | 설명                                                                                               |
| -------------------------- | ---------- | --------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| **기간** (`search_time`)     | 280px      | 텍스트 입력(가운데 정렬, 굵은 글씨) | 비어 있음                                                  | 클릭하면 날짜·시간 범위 선택기가 열려 시작/종료 시각을 설정. 폼 내부에는 hidden 필드 `search_date_from` / `search_date_to` 로 전달됨 |
| **애플리케이션** (`app_name`)    | 120px      | 드롭다운                  | 서버 (SERVER), 에이전트 (AGENT), 배치 (BATCH), 엣지 게이트웨이 (EDGE) | 진단을 발행한 모듈                                                                                       |
| **레벨** (`level`)           | 100px      | 드롭다운                  | 전체 레벨, 정보 (INFO), 경고 (WARN), 심각 (ERROR)                | 진단 레벨 필터. 빈 값이면 전체                                                                               |
| **메세지 검색** (`message`)     | 250px (숨김) | 텍스트 입력                | 비어 있음                                                  | 메시지 본문 키워드 검색. 기본은 숨김 상태이며 운영 환경에 따라 노출                                                          |
| **건수** (`limit`)           | 130px      | 드롭다운                  | 100, 200, 300, 500, 1,000                              | 표시할 최근 진단 건수                                                                                     |
| **조회**                     | (자동)       | 빨강 버튼 + 🔍            | —                                                      | 위 조건으로 진단 데이터를 조회                                                                                |
| **전체 출력**                  | (자동)       | 빨강 버튼 + 📄            | —                                                      | 현재 조건의 진단 결과를 CSV 파일로 일괄 내려받기                                                                    |
| **새로고침** (`realtime_icon`) | (자동)       | 빨강 버튼 + ↻             | —                                                      | 직전 조건 그대로 다시 조회 — 대시보드 형태로 활용할 수 있음                                                              |

### 애플리케이션 드롭다운 의미

| 값        | 라벨       | 설명                     |
| -------- | -------- | ---------------------- |
| `SERVER` | 서버       | 웹 서버·관리 콘솔·도메인 서비스     |
| `AGENT`  | 에이전트     | 데이터 수집 에이전트(파이프라인)     |
| `BATCH`  | 배치       | 배치 처리·집계·보고서 생성        |
| `EDGE`   | 엣지 게이트웨이 | 엣지 디바이스(현장에 설치된 게이트웨이) |

### 레벨 드롭다운 의미

| 값          | 라벨    | 색상 | 의미                  | 권장 조치                |
| ---------- | ----- | -- | ------------------- | -------------------- |
| \`\` (빈 값) | 전체 레벨 | —  | 모든 레벨               |                      |
| `INFO`     | 정보    | 파랑 | 정상 동작 정보·시작/종료 알림 등 | 별도 조치 불필요            |
| `WARN`     | 경고    | 주황 | 잠재적 문제·소프트 임계 초과    | 추이 확인, 동시간대 다른 모듈 점검 |
| `ERROR`    | 심각    | 빨강 | 오류·기능 장애·예외         | 즉시 원인 파악 + 시스템 관리자   |

***

## 타임라인 <a href="#timeline" id="timeline"></a>

검색 영역 아래 패널에 진단 타임라인이 그려집니다.

| 항목          | 설명                                          |
| ----------- | ------------------------------------------- |
| **헤더**      | 🕐 "타임라인" + 우측 작은 글씨 검색 결과 요약(`result_txt`) |
| **타임라인 본문** | `alarm_timeline` — 가로축 시간, 진단 항목이 색상 마커로 표시 |
| **마커 색상**   | 정보=파랑, 경고=주황, 심각=빨강                         |
| **호버**      | 마커에 마우스를 올리면 시각 + 메시지 미리보기 툴팁               |
| **클릭**      | 해당 진단의 행이 좌측 표에서 자동 강조                      |

### 빠른 시간 범위 (Timeline range)

타임라인 헤더 우측의 6개 버튼으로 즉시 줌 가능합니다.

| 버튼        | data-range | 동작               |
| --------- | ---------- | ---------------- |
| **10분전**  | `10M`      | 직전 10분 구간으로 줌    |
| **30분전**  | `30M`      | 직전 30분 구간으로 줌    |
| **1시간전**  | `1H`       | 직전 1시간 구간으로 줌    |
| **6시간전**  | `6H`       | 직전 6시간 구간으로 줌    |
| **12시간전** | `12H`      | 직전 12시간 구간으로 줌   |
| **전체기간**  | `ALL`      | 검색 전체 구간 (기본 활성) |

> 빠른 범위 버튼은 화면에 이미 조회된 결과 위에서 줌만 적용합니다. 더 긴 기간을 보려면 검색 영역의 **기간** 입력으로 새로 조회해야 합니다.

***

## 좌측 — 진단 로그 테이블 <a href="#log-table" id="log-table"></a>

```
| 애플리케이션 | 레벨 | 시간              | 메세지                                |
|-------------|------|------------------|--------------------------------------|
| server      | ERROR| 2026-05-08 12:00 | Connection timeout to upstream...     |
| messaging   | WARN | 2026-05-08 11:55 | Buffer overflow threshold reached...  |
```

| 컬럼         | 폭       | 정렬  | 표시                                                                              |
| ---------- | ------- | --- | ------------------------------------------------------------------------------- |
| **애플리케이션** | 140px   | 가운데 | 진단을 발행한 모듈명 (예: `server`, `agent`, `batch`, `edge`)                             |
| **레벨**     | 80px    | 가운데 | 색상 뱃지 — INFO(파랑) / WARN(주황) / ERROR(빨강)                                         |
| **시간**     | 160px   | 가운데 | 진단 발생 시각 (yyyy-MM-dd HH:mm:ss)                                                  |
| **메세지**    | 자동(나머지) | 좌측  | 진단 본문 (테이블이 `table-layout: fixed` 라 셀 폭에 맞춰 잘림 — 줄바꿈으로 보고 싶다면 행 더블클릭 또는 마우스 호버) |

### 행 인터랙션

* **호버**: 행 배경 강조
* **클릭**: 타임라인의 해당 마커가 동기 강조 (좌·우 동기화)
* **더블클릭/팝업**: 본문 전체와 stack trace 등 추가 정보가 모달로 표시됨

### 표 하단 페이지네이션

조회 건수가 많을 때 페이지 단위로 분할됩니다. 페이지당 행 수는 검색 영역의 **건수** 드롭다운(100/200/300/500/1,000)에 따라 결정됩니다.

***

## 우측 통계 패널 (3개) <a href="#stats-panels" id="stats-panels"></a>

검색 결과의 통계 시각화. 모두 좌측 표와 같은 데이터를 다른 시점에서 보여 줍니다.

### 1. 통계 — 레벨 비율 (`diag_level_chart`)

```
┌────────────────────────────────┐
│  검색된 진단 : N 건             │  ← 큰 글씨 헤드라인
│  [정보 N] [경고 N] [심각 N]     │  ← 3색 뱃지
│                                │
│        도넛/막대 차트           │  ← diag_level_chart (150px 높이)
└────────────────────────────────┘
```

| 항목           | ID                 | 표시                       |
| ------------ | ------------------ | ------------------------ |
| **헤드라인**     | —                  | "검색된 진단 : N 건" 큰 글씨      |
| **검색된 총 건수** | `diag_total_count` | 정수                       |
| **정보 뱃지**    | `diag_info_count`  | 정보 레벨 건수 — 파랑 배경         |
| **경고 뱃지**    | `diag_warn_count`  | 경고 레벨 건수 — 주황 배경         |
| **심각 뱃지**    | `diag_error_count` | 심각 레벨 건수 — 빨강 배경         |
| **레벨 비율 차트** | `diag_level_chart` | 정보·경고·심각 비율 차트           |
| **빈 상태 안내**  | `diag_stats_empty` | 데이터 없을 때 "데이터가 없습니다." 표시 |

### 2. 시간별 발생 추이 (`diag_hourly_chart`)

| 항목        | 설명                                            |
| --------- | --------------------------------------------- |
| **헤더**    | 📊 "시간별 발생 추이"                                |
| **차트**    | 시간대(시간 단위) 막대 차트 (170px 높이) — X축 시간, Y축 진단 건수 |
| **막대 분할** | 정보/경고/심각이 색상으로 누적되어 표시                        |

**해석**: 갑자기 한 시간대에 막대가 솟구치면 그 시각에 대규모 이상이 있었던 것. 시각을 메모하고 좌측 표에서 해당 시각의 행을 더블클릭해 상세 조회.

### 3. 애플리케이션별 분포 (`diag_app_chart`)

| 항목     | 설명                                  |
| ------ | ----------------------------------- |
| **헤더** | 🖥 "애플리케이션별 분포"                     |
| **차트** | 도넛/막대 차트 (140px 높이) — 애플리케이션별 진단 건수 |

**해석**: 한 애플리케이션이 전체의 70% 이상 차지하면 그 모듈에 집중된 장애 가능성. 검색 영역의 **애플리케이션** 드롭다운으로 좁혀 조회한 뒤 좌측 표를 보세요.

***

## 전체 출력 (CSV) <a href="#csv" id="csv"></a>

검색 영역의 **전체 출력** 버튼을 클릭하면 현재 검색 조건의 모든 진단을 CSV 파일로 내려받을 수 있습니다.

### CSV 컬럼

| 컬럼         | 형식                        |
| ---------- | ------------------------- |
| **애플리케이션** | 텍스트                       |
| **레벨**     | 텍스트 (INFO/WARN/ERROR)     |
| **시간**     | 텍스트 (yyyy-MM-dd HH:mm:ss) |
| **메세지**    | 텍스트 (큰따옴표 이스케이프)          |

> CSV 는 화면에 보이는 행만이 아니라 **검색 조건에 맞는 전체 결과**를 내보냅니다. **건수** 드롭다운(최근 N건)의 영향을 받지 않으므로 장기 분석에 적합합니다.

### CSV 활용 팁

* 시스템 관리자에게 전달할 때 압축(.zip)으로 첨부
* 외부 분석 도구(스프레드시트·BI 도구)로 가져와 모듈·시간대·키워드 별 추가 분석
* 같은 패턴이 매일 반복되는지 1주일 분량을 합쳐 비교

***

## 장애 발생 시 표준 진단 절차 <a href="#playbook" id="playbook"></a>

장애가 발생했을 때 다음 순서대로 진행하시면 효율적으로 원인을 파악할 수 있습니다.

### 1단계 — 시간 범위 좁히기

* **기간** 입력에 장애 발생 시점 ±10분 \~ ±30분 지정
* **건수** 는 1,000건으로 (놓치는 항목이 없도록)

### 2단계 — 심각 우선 조회

1. **레벨** 드롭다운을 **심각(ERROR)** 으로 설정 → **조회**
2. 좌측 표의 첫 줄(가장 최근 ERROR)부터 메시지 확인
3. 우측 **애플리케이션별 분포** 차트로 어느 모듈이 ERROR 를 많이 발생시켰는지 확인

### 3단계 — 동시간대 경고 확인

1. **레벨** 을 **경고(WARN)** 로 바꾸고 같은 기간 조회
2. ERROR 직전 1\~5분 사이에 발생한 WARN 메시지 확인 — 보통 ERROR 의 단서가 됩니다

### 4단계 — 모듈별 좁히기

1. ERROR/WARN 이 가장 많은 애플리케이션을 **애플리케이션** 드롭다운으로 선택
2. **레벨** 을 **전체 레벨** 로 다시 풀어 모듈 내 모든 흐름 확인 — INFO 가 끊기는 시점이 단서

### 5단계 — 메시지 패턴

좌측 표의 메시지 본문을 검토. 같은 메시지가 반복되는지(룰 폭주), 한 번만 떨어진 단발성인지(외부 상태 변동) 구분.

### 6단계 — 시스템 관리자 인계

장애 원인을 운영자가 직접 조치할 수 없으면 **전체 출력** 버튼으로 CSV 파일을 받아 시스템 관리자에게 전달. 보고 시 다음을 함께 첨부하시면 좋습니다.

* 장애 발생 시각(첫 ERROR 시각)
* 영향 범위(어느 사이트/모듈)
* ERROR 메시지 1\~3개 텍스트
* CSV 파일

***

## 자주 보는 진단 메시지 패턴 <a href="#patterns" id="patterns"></a>

| 메시지 키워드                 | 의미              | 일반 조치                                                                           |
| ----------------------- | --------------- | ------------------------------------------------------------------------------- |
| `Connection timeout`    | 외부 서비스 연결 시간 초과 | 네트워크 상태·대상 서비스 가동 여부                                                            |
| `Out of memory` / `OOM` | 메모리 부족          | 시스템 리소스 점검·재시작 검토 (시스템 관리자)                                                     |
| `Disk space low`        | 디스크 가용량 부족      | 오래된 데이터 정리 또는 디스크 증설                                                            |
| `Authentication failed` | 인증 실패           | 토큰·계정 정보 만료/오류 확인                                                               |
| `Buffer overflow`       | 처리 큐 가득참        | 트리거 사전 필터·외부 IO 스로틀로 부하 평탄화                                                     |
| `Job already running`   | 잡 중복 실행         | 이전 잡 미완료 — 시스템 관리자 점검                                                           |
| `Failed to parse`       | 메시지 파싱 실패       | 외부 시스템 페이로드 형식 검토                                                               |
| `Schema mismatch`       | DB/메시지 스키마 불일치  | 시스템 관리자 점검 (배포 직후일 수 있음)                                                        |
| `Pipeline exception`    | 데이터 파이프라인 예외    | [일일 통계의 선택일 상세 차트](/plantpulse-platform/user/statistics.md#detail-charts) 함께 확인 |
| `Edge disconnect`       | 엣지 디바이스 단절      | [연결 관리](/plantpulse-platform/user/connection.md) 에서 디바이스별 상태 확인                 |

***

## 자주 묻는 질문 <a href="#faq" id="faq"></a>

**Q. 메시지 검색(키워드) 입력란이 안 보입니다.** A. 운영 환경 설정에 따라 메시지 본문 검색이 비활성화되어 있을 수 있습니다(`display:none`). 활성화 필요 시 시스템 관리자에게 문의하세요.

**Q. 진단 데이터의 보존 기간은?** A. 기본 7일입니다. 장기 보관이 필요하면 **전체 출력** 으로 CSV 를 외부 시스템에 적재하거나, [플로우](/plantpulse-platform/user/flow.md) 의 진단 트리거(`flow_on_diagnostic`)로 외부 로그 시스템에 자동 적재하실 수 있습니다.

**Q. ERROR 가 매우 많이 누적되었는데 모두 같은 메시지입니다. 무시해도 되나요?** A. 같은 ERROR 가 짧은 시간에 반복된다면 한 가지 원인이 폭주한 것이며 카운트만 큰 의미는 작습니다. 첫 발생 시각과 메시지 자체를 먼저 보시면 됩니다.

**Q. 새로고침 버튼은 자동 새로고침으로 바꿀 수 있나요?** A. 화면은 명시적 새로고침만 동작합니다. 운영 모니터링 용도로 자동 갱신이 필요하면 짧은 주기로 새로고침을 클릭하시거나 [플로우](/plantpulse-platform/user/flow.md) 의 알림 자동화로 ERROR 발생 시 푸시를 받도록 설정하세요.

**Q. 타임라인의 마커 색상이 너무 빽빽합니다.** A. **건수** 드롭다운을 작은 값(100\~200건)으로 낮추거나, **레벨** 을 ERROR/WARN 으로 좁히면 가독성이 좋아집니다.

**Q. 같은 시점에 모든 모듈이 ERROR 를 발행했습니다.** A. 공통 인프라(메시지 채널·스토리지) 장애 가능성이 큽니다. [대시보드 헬스 레일](/plantpulse-platform/user/summary.md#health-rail) 의 인프라/엔진 상태를 같이 확인하세요.

**Q. CSV 다운로드가 시간이 오래 걸립니다.** A. 검색 조건이 너무 광범위할 가능성이 큽니다. 기간을 24시간 이하로 줄이거나 모듈을 한정하시기 바랍니다.

***

## 관련 화면 <a href="#related" id="related"></a>

* [대시보드](/plantpulse-platform/user/summary.md) — 우측 헬스 레일에서 최근 진단 미리보기
* [일일 통계](/plantpulse-platform/user/statistics.md) — 시스템 진단 트렌드와 예외 유형/코드 분포
* [알람](/plantpulse-platform/user/alarm.md) — 도메인 알람 이력
* [연결 관리](/plantpulse-platform/user/connection.md) — 엣지/OPC 디바이스 상태
* [플로우](/plantpulse-platform/user/flow.md) — `flow_on_diagnostic` 트리거로 진단 자동 라우팅