From 3ef1b7b77343d29c50c72e6931b3018bb5b725c3 Mon Sep 17 00:00:00 2001 From: Cloud User Date: Tue, 17 Mar 2026 14:36:11 +0900 Subject: [PATCH] docs: update record.md (#32-39) and README with latest changes Co-Authored-By: Claude Opus 4.6 --- README.md | 25 ++++++++++++++++++++++--- record.md | 16 ++++++++++++++++ 2 files changed, 38 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 219be0a..541155c 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ Kubernetes 클러스터 인프라 모니터링 주간 리포트 시스템. Prome - **주의 구간 자동 감지** (임계값 기반 + Z-score peak 감지) - **기간 선택** (시작일/종료일 직접 설정 + 프리셋 버튼) - **차트 인터랙션** (hover 시 전체 데이터 tooltip, 클릭 시 solo 모드) +- **Alert 클릭 → 차트 확대** (주의 구간 항목 클릭 시 해당 시간대로 zoom) +- **Alert 유형 구분** (PEAK 보라색 / WARNING 주황색 / CRITICAL 빨간색 태그) - **PDF 내보내기** ## 기술 스택 @@ -88,12 +90,25 @@ charts/infra-report/ # Helm Chart ### Z-score Peak 감지 -CPU, Memory, Ingress, Istio에 적용됩니다. +모든 메트릭에 적용됩니다. 상승 방향(평균 초과)만 감지합니다. - **알고리즘**: 전체 데이터의 평균(mean)과 모표준편차(stddev)를 계산하고, 각 데이터 포인트의 Z-score `(값 - mean) / stddev`를 산출 -- **Threshold**: `|Z-score| > 5` (평균에서 표준편차 5배 이상 벗어난 경우) +- **Threshold**: 메트릭별로 다름 + +| 메트릭 | Z-score Threshold | +|--------|-------------------| +| CPU | 5 | +| Memory | 5 | +| Disk | 2 | +| NAS | 2 | +| Ingress | 5 | +| Istio | 5 | + +- **최소 표준편차 가드**: `stddev < 0.5`이면 데이터 변동이 무의미하므로 peak 감지 스킵 (Disk 등 안정적 메트릭에서 미세 변동이 peak으로 잡히는 문제 방지) +- **감지 방향**: 상승(양수)만 감지 (`zScore > threshold`). 평균 이하 급감은 peak으로 잡지 않음 - **구간 병합**: 연속된 peak 포인트를 하나의 구간으로 묶어 시작/종료 시간, 최대값, 평균값 기록 -- **차트 표시**: peak 구간은 차트에 빨간색 반투명 영역으로 표시 +- **차트 표시**: peak 구간은 차트에 빨간색 반투명 영역(markArea)으로 표시 +- **클릭 확대**: AlertPanel에서 peak 항목 클릭 시 해당 시간대로 차트 확대 (최소 앞뒤 15분 padding) ## 환경 변수 (ConfigMap) @@ -220,6 +235,10 @@ PROMETHEUS_URL=http://localhost:9090 npm run dev - 프론트엔드에서 `Asia/Seoul` 타임존으로 변환하여 표시합니다 - `TZ` 환경 변수는 Prometheus 쿼리에 영향을 주지 않습니다 +## 노드 배치 + +기본적으로 `nodegroup: nd` 라벨이 있는 노드에만 배포됩니다. `values.yaml`의 `nodeSelector`에서 변경 가능합니다. + ## Kubernetes RBAC ServiceAccount `infra-report-sa`에 ClusterRole이 부여되어 노드 정보를 조회합니다: diff --git a/record.md b/record.md index bc91a70..29d1fdc 100644 --- a/record.md +++ b/record.md @@ -67,3 +67,19 @@ 30. **Memory 주의 기준 변경**: warning 85%/critical 95% → warning 80%~90%/critical 90% 초과로 변경. 31. **CI paths-ignore 추가**: `*.md`, `docs/**` 파일만 변경된 push에서는 CI 스킵. 불필요한 Docker 빌드 및 파드 재배포 방지. + +32. **NetworkChart markArea 추가**: Ingress/Istio 차트에도 Z-score peak 구간을 빨간색 반투명 영역으로 표시. 기존에는 TimeSeriesChart만 markArea가 있었음. + +33. **Alert 유형 구분 태그 추가**: AlertPanel에서 PEAK(보라색), WARNING(주황색), CRITICAL(빨간색) 태그로 Z-score peak과 임계값 경고를 시각적으로 구분. + +34. **Alert 클릭 → 차트 확대 기능**: AlertPanel의 peak 항목 클릭 시 해당 시간대로 차트가 dataZoom. `forwardRef` + `useImperativeHandle`로 차트 인스턴스의 `zoomToRange` 메서드 외부 노출. + +35. **Z-score 상승 방향만 감지**: `Math.abs(zScore) > threshold` → `zScore > threshold`로 변경. 평균 이하 급감은 peak로 잡지 않음 (NAS에서 평균 아래 구간이 잘못 표시되던 문제 해결). + +36. **Zoom 최소 padding 15분**: peak 구간이 30분 미만이어도 앞뒤로 최소 15분씩 여유를 두고 확대되도록 `MIN_PADDING = 15 * 60 * 1000` 추가. + +37. **Z-score threshold 메트릭별 분리**: 전체 threshold 5 → Disk/NAS는 2, CPU/Memory/Ingress/Istio는 5로 분리. `processResults`에 `peakThreshold` 파라미터 추가. 개별 메트릭 API(`/api/metrics/[type]`)에도 `PEAK_THRESHOLD` 맵으로 적용. + +38. **최소 표준편차(MIN_STDDEV) 가드 추가**: `stddev < 0.5`이면 데이터 변동이 무의미하므로 peak 감지 스킵. Disk 데이터가 거의 일정할 때(50.00~50.05) stddev가 극소값이 되어 미세 변동이 peak로 잡히던 문제 해결. + +39. **nodeSelector 추가**: Deployment에 `nodeSelector: nodegroup: nd` 추가. values.yaml에 `nodeSelector` 항목 추가, deployment.yaml 템플릿에 조건부 렌더링.