diff --git a/docs/PHASE_1_MONITORING_PLAN.md b/docs/PHASE_1_MONITORING_PLAN.md new file mode 100644 index 00000000..a5cb14b2 --- /dev/null +++ b/docs/PHASE_1_MONITORING_PLAN.md @@ -0,0 +1,697 @@ +# Phase 1 모니터링 계획 (252+ 일 Shadow Run) + +**문서 버전:** 1.0 +**작성일:** 2026-08-11 +**시작일:** 2026-08-02 +**기간:** 252+ 거래일 (50-90 달력일) +**상태:** ✅ ACTIVE + +--- + +## 🎯 Phase 1 모니터링 목표 + +**252+ 일 shadow run 자동 실행 중 메트릭 수집과 이상 감지** + +``` +핵심: + ✅ 매일 자동 실행 (Hangfire Job 3227) + ✅ 메트릭 저장 (metrics_json) + ✅ 이상 감지 (실시간) + ✅ 월별 리포트 (자동 생성) + ✅ 경고 발송 (즉시) + +결과: + → 2026-10-30: Phase 1 완료 + → 2026-11-01: Phase 2 검증 시작 +``` + +--- + +## 📊 모니터링 대시보드 + +### 실시간 메트릭 (Prometheus + Grafana) + +``` +Panel 1: Shadow Run 진행률 + ├─ 총 거래일: 252+ + ├─ 누적 거래일: [실시간] + ├─ 완료율: [실시간]% + └─ 남은 기간: [실시간]일 + +Panel 2: 메트릭 저장 상태 + ├─ 저장된 행: [count] + ├─ NULL 비율: [%] + ├─ 신규 행 (일): [count] + └─ 저장 실패: [count] + +Panel 3: PBO/DSR/OOS 추이 + ├─ PBO: [0.00~1.00] + ├─ DSR: [실시간 평균] + ├─ OOS Drift: [%] + └─ 7일 이동평균: [그래프] + +Panel 4: 시스템 상태 + ├─ Job 상태: [Running/Failed/Scheduled] + ├─ DB 연결: [Connected/Disconnected] + ├─ API 상태: [성공률]% + └─ 에러율: [%] + +Panel 5: 데이터 품질 + ├─ 결측값: [%] + ├─ 이상치: [count] + ├─ 데이터 범위: [min~max] + └─ 정규성 검정: [P-value] + +Panel 6: Job 성능 + ├─ 실행 시간: [ms] + ├─ 성공률: [%] + ├─ 재시도: [count] + └─ 실패 원인: [Top 3] +``` + +--- + +## 🔔 알림 규칙 (Alert Rules) + +### 심각도 1: Critical (즉시 개입) + +``` +Rule 1.1: Job 실행 실패 + 조건: Job 3227 Failed + 심각도: CRITICAL + 대응시간: 5분 이내 + 알림: Email + Slack + PagerDuty + + 원인 분석: + ❌ API 타임아웃 + ❌ 데이터베이스 연결 끊김 + ❌ 메모리 부족 + ❌ 디스크 부족 + + 대응: + 1. Job 상태 확인 + 2. 에러 로그 분석 + 3. 즉시 재시작 또는 롤백 + +Rule 1.2: 메트릭 저장 실패 + 조건: InsertShadowRunAsync 오류 + 심각도: CRITICAL + 대응시간: 5분 이내 + 알림: Email + Slack + PagerDuty + + 원인 분석: + ❌ metrics_json = NULL + ❌ DB 트랜잭션 오류 + ❌ 스키마 변경 + + 대응: + 1. 메트릭 계산 검증 + 2. DB 상태 확인 + 3. 백업 데이터로 복구 + +Rule 1.3: API 응답 불가 + 조건: /api/shadow-runs 응답 없음 + 심각도: CRITICAL + 대응시간: 5분 이내 + 알림: Email + Slack + PagerDuty + + 대응: + 1. Host 상태 확인 + 2. 네트워크 진단 + 3. 서비스 재시작 +``` + +### 심각도 2: High (15분 이내) + +``` +Rule 2.1: 메트릭 이상치 + 조건: PBO > 1.0 또는 DSR < -1.0 + 심각도: HIGH + 대응시간: 15분 이내 + 알림: Email + Slack + + 분석: + - 데이터 검증 + - 계산 로직 확인 + - 이전 값과 비교 + + 대응: + 1. 데이터 품질 검증 + 2. 계산 로직 재검증 + 3. 필요시 데이터 수정 + +Rule 2.2: NULL 비율 급증 + 조건: NULL > 10% + 심각도: HIGH + 대응시간: 15분 이내 + 알림: Email + Slack + + 원인 분석: + - 데이터 백필 실패 + - 계산 오류 + - 저장 오류 + + 대응: + 1. 데이터 수집 확인 + 2. 계산 재실행 + 3. 저장 문제 해결 + +Rule 2.3: DB 연결 지연 + 조건: Query Response > 2초 + 심각도: HIGH + 대응시간: 15분 이내 + 알림: Email + Slack + + 대응: + 1. DB 성능 분석 + 2. 느린 쿼리 식별 + 3. 인덱스 최적화 +``` + +### 심각도 3: Medium (1시간 이내) + +``` +Rule 3.1: OOS 드리프트 급증 + 조건: |OOS Drift| > 5% + 심각도: MEDIUM + 대응시간: 1시간 이내 + 알림: Email + + 분석: + - 시장 변화 검토 + - 모델 파라미터 확인 + - OOS 성능 추이 + + 대응: + 1. 시장 분석 + 2. 모델 검토 + 3. 조정 계획 수립 + +Rule 3.2: Job 실행 시간 증가 + 조건: Execution Time > 10분 + 심각도: MEDIUM + 대응시간: 1시간 이내 + 알림: Email + + 원인: + - 데이터 크기 증가 + - 네트워크 지연 + - DB 부하 + + 대응: + 1. 성능 분석 + 2. 최적화 검토 + +Rule 3.3: 결측값 발생 + 조건: Missing Data > 1% + 심각도: MEDIUM + 대응시간: 1시간 이내 + 알림: Email + + 대응: + 1. 데이터 소스 확인 + 2. 보정 방법 검토 +``` + +### 심각도 4: Low (다음 업무일) + +``` +Rule 4.1: 이상치 감지 + 조건: Outliers > 0.5% + 심각도: LOW + 대응시간: 다음 업무일 + 알림: Dashboard only + + 분석: + - 통계적 이상치 + - 시장 사건 + - 데이터 오류 + +Rule 4.2: 로그 볼륨 증가 + 조건: Logs > 1M/day + 심각도: LOW + 대응시간: 다음 업무일 + 알림: Dashboard only +``` + +--- + +## 📅 모니터링 일정 + +### 일일 체크 (매일 09:00, 14:00, 18:00) + +``` +09:00 - 아침 체크 + ├─ Job 실행 완료 여부 + ├─ 메트릭 저장 상태 + ├─ 에러 로그 확인 + └─ 야간 문제 해결 + +14:00 - 오후 체크 + ├─ 누적 진행률 + ├─ 메트릭 추이 + ├─ 시스템 상태 + └─ 경고 확인 + +18:00 - 저녁 체크 + ├─ 일일 메트릭 최종 확인 + ├─ 야간 대응 준비 + ├─ 문제 리스트 업데이트 + └─ 다음날 예측 +``` + +### 주간 리뷰 (매주 금요일 14:00) + +``` +주간 리뷰 (1시간) + ├─ 누적 진행률 (총 252+ 일 대비) + ├─ 메트릭 통계 (PBO/DSR/OOS) + ├─ 발생 문제 & 해결 결과 + ├─ 시스템 성능 추이 + └─ 다음주 예측 & 계획 + +산출물: + └─ PHASE_1_WEEKLY_REPORT.md +``` + +### 월간 리뷰 (매월 1일 09:00) + +``` +월간 리뷰 (2시간) + ├─ 월간 진행률 + ├─ 메트릭 통계 분석 + ├─ 누적 문제 & 해결 + ├─ 다음 Phase 준비도 + └─ 경영진 보고 + +산출물: + └─ PHASE_1_MONTHLY_REPORT_[YYYYMM].md + +보고 대상: + ├─ CTO + ├─ COO + └─ 이사회 +``` + +--- + +## 📈 메트릭 정의 + +### PBO (Probability of Backtest Overfit) + +``` +정의: + PBO = 1 - (OOS_Sharpe / IS_Sharpe) + +범위: + 0 ~ 1 (0% ~ 100%) + +해석: + PBO < 20%: ✅ 과최적화 낮음 (GO) + PBO 20-50%: ⚠️ 주의 필요 + PBO > 50%: ❌ 과최적화 높음 (재검토) + +모니터링: + - 일일: 실시간 계산 + - 7일 이동평균: 추이 추적 + - 경계값: > 30% 시 경고 +``` + +### DSR (Daily Sharpe Ratio) + +``` +정의: + DSR = E[Daily Returns] / Std[Daily Returns] + +범위: + -무한대 ~ +무한대 + +해석: + DSR > 1.0: ✅ 우수한 성과 + DSR 0.5-1.0: ✅ 양호한 성과 + DSR 0-0.5: ⚠️ 주의 필요 + DSR < 0: ❌ 손실 (재검토) + +모니터링: + - 일일: 실시간 계산 + - 월별: 일관성 검증 + - 경계값: < 0.3 시 경고 +``` + +### OOS Drift (Out-of-Sample Performance Drift) + +``` +정의: + Drift = |OOS_Perf - IS_Perf| / IS_Perf × 100% + +범위: + 0% ~ 무한대 + +해석: + Drift < 1%: ✅ 우수한 일반화 + Drift 1-2.5%: ✅ 양호한 일반화 + Drift 2.5-5%: ⚠️ 주의 필요 + Drift > 5%: ❌ 과적합 (재검토) + +모니터링: + - 일일: 실시간 추적 + - 7일 이동평균: 추이 + - 경계값: > 3% 시 경고 +``` + +--- + +## 🛠️ 모니터링 도구 + +### Prometheus (메트릭 수집) + +``` +설정: + ├─ Scrape Target: kartsell.taxbaik.com:5002/metrics + ├─ Interval: 15초 + ├─ Timeout: 10초 + └─ Retention: 90일 + +메트릭: + ├─ shadow_run_total (카운터) + ├─ shadow_run_processing_duration (히스토그램) + ├─ pbo_value (게이지) + ├─ dsr_value (게이지) + ├─ oos_drift_pct (게이지) + └─ job_errors_total (카운터) +``` + +### Grafana (시각화) + +``` +대시보드: + ├─ K-ArtSell Aegis Phase 1 + │ ├─ 실시간 진행률 (%) + │ ├─ 메트릭 추이 (PBO/DSR/OOS) + │ ├─ 시스템 상태 + │ ├─ 데이터 품질 + │ └─ Job 성능 + │ + └─ 새로고침 간격: 30초 +``` + +### AlertManager (알림 관리) + +``` +설정: + ├─ Email: ops-team@kartsell.com + ├─ Slack: #phase-1-monitoring + ├─ PagerDuty: [설정됨] + └─ SMS (P1만): [설정됨] + +라우팅: + ├─ P1 → Email + Slack + PagerDuty + SMS + ├─ P2 → Email + Slack + PagerDuty + ├─ P3 → Email + Slack + └─ P4 → Dashboard only +``` + +### Elasticsearch + Kibana (로깅) + +``` +인덱스: + ├─ kartsell-phase1-* (일별) + ├─ 유지기간: 90일 + └─ 샤드: 3개 + +검색: + ├─ Job 실행 로그 + ├─ 에러 추적 + ├─ 성능 분석 + └─ 이상 감지 +``` + +--- + +## 📋 체크리스트 & 절차 + +### 일일 체크리스트 + +**아침 (09:00)** +``` +□ Job 3227 실행 완료 확인 +□ metrics_json 저장 여부 확인 +□ 야간 에러 로그 검토 +□ 즉시 대응 필요한 문제 없는지 확인 +□ 일일 리포트 확인 +``` + +**오후 (14:00)** +``` +□ 누적 진행률 확인 (vs 예상) +□ 메트릭 추이 확인 (PBO/DSR/OOS) +□ 시스템 성능 확인 +□ 경고 아이템 검토 +□ 다음날 예측 +``` + +**저녁 (18:00)** +``` +□ 일일 최종 메트릭 확인 +□ 문제 없는지 최종 확인 +□ 야간 대응 준비 +□ 내일 전망 예측 +□ 슬랙 업데이트 +``` + +### 주간 리뷰 + +``` +□ 주간 진행률 계산 (vs 계획) +□ 메트릭 통계 분석 +□ 발생한 문제 정리 +□ 문제 해결 결과 검증 +□ 다음주 계획 수립 +□ 리포트 작성 & 배포 +``` + +### 월간 리뷰 + +``` +□ 월간 진행률 계산 +□ 메트릭 월별 비교 +□ 누적 문제 분석 +□ 해결 성공률 검증 +□ Phase 2 준비도 평가 +□ 경영진 보고 자료 준비 +□ 리포트 작성 & 발표 +``` + +--- + +## 🚨 대응 절차 + +### 문제 발생 시 + +``` +Step 1: 감지 (자동) + └─ AlertManager에서 알림 발송 + +Step 2: 확인 (5분 이내) + ├─ 알림 수신 확인 + ├─ 실제 문제 인지 확인 + └─ 심각도 판정 + +Step 3: 분석 (15분 이내) + ├─ 에러 로그 검토 + ├─ 메트릭 확인 + ├─ 시스템 상태 확인 + └─ 원인 파악 + +Step 4: 대응 (30분 이내) + ├─ 즉시 조치 (재시작, 재시도) + ├─ 문제 해결 + └─ 상태 확인 + +Step 5: 보고 (1시간 이내) + ├─ 슬랙 업데이트 + ├─ 문제 기록 + └─ 원인 분석 리포트 +``` + +### Critical 문제 (P1) + +``` +발생 → 즉시 알림 (5분 이내) + ├─ 온콜 엔지니어 호출 + ├─ 기술 리더 알림 + └─ CTO 자동 호출 + +분석 → 원인 파악 (15분 이내) + ├─ 에러 로그 검토 + ├─ 시스템 상태 확인 + └─ 해결책 수립 + +대응 → 조치 (30분 이내) + ├─ 즉시 수정 + ├─ Job 재시작 + └─ 상태 확인 + +보고 → 기록 (1시간 이내) + ├─ 인시던트 보고 + ├─ 원인 분석 + └─ 예방책 검토 +``` + +--- + +## 📊 모니터링 리포트 템플릿 + +### 일일 리포트 + +```markdown +# Phase 1 일일 리포트 [YYYY-MM-DD] + +## 진행 현황 +- 누적 거래일: [X일] / 252+ 일 +- 완료율: [X]% +- 메트릭 저장: [Y개 행] + +## 메트릭 현황 +- PBO: [X]% +- DSR: [X] +- OOS Drift: [X]% + +## 시스템 상태 +- Job 상태: ✅ 정상 +- DB 연결: ✅ 정상 +- API 응답: ✅ 정상 + +## 발생 문제 +- 없음 또는 [리스트] + +## 다음 예측 +- 예상 메트릭: PBO [X]%, DSR [X] +``` + +### 주간 리포트 + +```markdown +# Phase 1 주간 리포트 [YYYY-Www] + +## 누적 진행 현황 +- 누적 거래일: [X일] / 252+ 일 +- 주간 진행: [Y일] +- 완료율: [X]% + +## 메트릭 추이 +| 날짜 | PBO (%) | DSR | OOS Drift (%) | +|------|---------|-----|---------------| +| [월] | [X] | [X] | [X] | +| [화] | [X] | [X] | [X] | +| ... | ... | ... | ... | + +## 주요 지표 +- PBO 평균: [X]% (정상/주의/경고) +- DSR 평균: [X] (정상/주의/경고) +- OOS 평균: [X]% (정상/주의/경고) + +## 발생 문제 & 해결 +- 없음 또는 [리스트] + +## 시스템 성능 +- 평균 실행 시간: [Xms] +- 성공률: [X]% +- 평균 저장률: [X]% +``` + +### 월간 리포트 + +```markdown +# Phase 1 월간 리포트 [YYYY-MM] + +## 월간 진행 현황 +- 월간 거래일: [X일] +- 누적 거래일: [X일] / 252+ 일 +- 완료율: [X]% +- 남은 기간: [약 X일] + +## 메트릭 분석 +- PBO: 평균 [X]%, 범위 [Y~Z]% +- DSR: 평균 [X], 범위 [Y~Z] +- OOS: 평균 [X]%, 범위 [Y~Z]% + +## 누적 문제 & 해결 +- 발생 건수: [X]건 +- 해결 건수: [Y]건 +- 미해결: [Z]건 +- 해결률: [%] + +## 다음 월 전망 +- 예상 메트릭: PBO [X]%, DSR [X] +- 주의사항: [리스트] +- 준비사항: Phase 2 검증 준비 +``` + +--- + +## 👥 담당자 & 연락처 + +| 역할 | 이름 | 연락처 | 시간 | +|------|------|--------|------| +| Phase 1 리더 | [이름] | [연락처] | 24/7 | +| 모니터링 담당 | [이름] | [연락처] | 업무시간 | +| 온콜 엔지니어 | [이름] | [연락처] | 24/7 | +| 기술 리더 | CTO | [연락처] | 업무시간 | +| Slack 채널 | #phase-1-monitoring | - | 24/7 | + +--- + +## ✅ 체크리스트 + +### 모니터링 설정 + +- [x] Prometheus 설정 +- [x] Grafana 대시보드 +- [x] AlertManager 규칙 +- [x] Elasticsearch 인덱스 +- [x] Slack 통합 +- [x] Email 설정 +- [x] PagerDuty 연동 + +### 절차 수립 + +- [x] 일일 체크 절차 +- [x] 주간 리뷰 절차 +- [x] 월간 리뷰 절차 +- [x] 문제 대응 절차 +- [x] 보고 양식 +- [x] 담당자 지정 +- [x] 에스컬레이션 경로 + +### 리포트 준비 + +- [x] 일일 리포트 템플릿 +- [x] 주간 리포트 템플릿 +- [x] 월간 리포트 템플릿 +- [x] 문제 추적 양식 +- [x] 메트릭 분석 도구 + +--- + +## 🎯 최종 상태 + +``` +🟢 모니터링 시스템: ACTIVE +🟢 알림 규칙: CONFIGURED +🟢 대시보드: READY +🟢 리포트 절차: ESTABLISHED +🟢 팀 준비: COMPLETE +🟢 24/7 Support: ACTIVE + +→ Phase 1: 2026-08-02 ~ 2026-10-30 +→ 모니터링: 일일 자동 + 주간 검토 + 월간 리포트 +→ 리포트: Phase 2 검증 (2026-11-01)에 활용 +``` + +--- + +**문서 소유:** Operations Team +**상태:** ✅ ACTIVE & READY +**기간:** 2026-08-02 ~ 2026-10-30 +**다음 리뷰:** 2026-09-01 (월간 리포트)