KArtSell.Aegis/docs/PHASE_1_MONITORING_PLAN.md

# 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 (월간 리포트)