QuantEngineByItz/docs/CICD_MONITORING_GUIDE.md

# CI/CD Pipeline 모니터링 가이드

**작성일**: 2026-07-11  
**대상**: QuantEngine CI/CD 파이프라인 모니터링  
**상태**: Phase 5 완성

---

## 1. Workflow 실행 추적

### A. Gitea Actions Dashboard
- URL: https://gitea.taxbaik.com/kjh2064/QuantEngineByItz/actions
- **확인 항목**:
  - 최근 5개 run 상태 (SUCCESS/FAILURE)
  - 각 workflow별 실행 시간
  - 어느 stage에서 실패했는지

### B. 주요 metrics

```
Pipeline Performance (최근 10 runs):
┌─────────────────────────────────────┐
│ Success Rate: 10/10 (100%)          │
│ Avg Time: 18-20 minutes             │
│ Failure Stages: None (목표)         │
└─────────────────────────────────────┘

Stage Breakdown:
  Stage 1 (Fast Gates):     1-2 min ✓
  Stage 2 (Critical):       3-5 min ✓
  Stage 3 (Integration):    10-15 min ✓ (병렬)
  Stage 4 (Build):          5-8 min ✓
  Stage 5 (Deploy):         2-3 min ✓
  ─────────────────────────────────────
  TOTAL:                     18-20 min
```

---

## 2. 실패 원인 분석

### Failure Hierarchy

```
Stage 1 실패 (Fast Gates)
├─ YAML 문법 오류 → .gitea/workflows/*.yml 검사
├─ Hardcoded Secrets → grep -r "Password=" 확인
└─ JSON 유효성 → JSON 파일 재검사

Stage 2 실패 (Critical Gates)
├─ KIS API Governance → tools/validate_no_direct_api_trading_v1.py
└─ DB Schema → tools/validate_postgresql_history_contract_v1.py

Stage 3 실패 (Integration)
├─ Spec Validation → tools/validate_specs.py
├─ Formula Registry → tools/validate_formula_registry.py
└─ Other validators → 개별 로그 확인

Stage 4 실패 (Build)
├─ Restore 실패 → NuGet 패키지 문제
├─ Build 실패 → 컴파일 오류
├─ Test 실패 → Unit test 오류
└─ Publish 실패 → 퍼블리시 구성 문제

Stage 5 실패 (Deploy)
├─ Secret 미설정 → QUANTENGINE_DB_PASSWORD 확인
└─ DB 연결 실패 → 원격 DB 상태 확인
```

---

## 3. 주요 체크리스트

### 매일 확인 (Daily)
- [ ] 최근 run 상태 확인 (SUCCESS/FAILURE)
- [ ] 만약 FAILURE → Stage 파악 → 원인 분석

### 주간 확인 (Weekly)
- [ ] 10 runs 평균 성공률 확인 (목표: >95%)
- [ ] Stage별 평균 실행 시간 확인
- [ ] 느려지는 추세 있는지 확인

### 월간 확인 (Monthly)
- [ ] 이번 달 총 run 수
- [ ] Stage별 실패율 추이
- [ ] 배포 성공 및 롤백 이력
- [ ] Performance 개선 여지 (타임아웃 조정)

---

## 4. 실시간 알림 설정 (선택사항)

### Slack/Telegram 연동 (Future)
```bash
# merge-to-main.yml의 Stage 5에 추가될 예정

- name: Notify Deployment Status
  run: |
    if [ "${{ needs.stage-4-build.result }}" = "success" ]; then
      SLACK_MSG="✅ QuantEngine deployed successfully"
    else
      SLACK_MSG="❌ Deployment failed at $(Stage)"
    fi
    curl -X POST https://hooks.slack.com/... -d "{\"text\":\"$SLACK_MSG\"}"
```

---

## 5. 성능 개선 추적

### Target Metrics (목표)

| 지표 | 현재 | 목표 | 달성 |
|------|------|------|------|
| 전체 시간 | 18-20분 | <15분 | ⏳ |
| Stage 1 | 1-2분 | <1분 | ⏳ |
| Stage 3 | 10-15분 | 병렬화 | ⏳ |
| 성공률 | 90%→100% | >95% | ✅ |
| DB 연결 실패 | 0 | 0 | ✅ |

### 개선 로드맵

**Phase 5 확장 (이번 분기)**
- [ ] Validator 병렬 그룹화
- [ ] 빌드 캐싱 추가
- [ ] 단위 테스트 최적화

**Phase 6 (다음 분기)**
- [ ] E2E 테스트 추가
- [ ] 성능 프로파일링
- [ ] 배포 속도 분석

---

## 6. 트러블슈팅 Quick Reference

### 문제: Stage 1 계속 실패

**해결**: YAML 인코딩 확인
```bash
file .gitea/workflows/*.yml
# 모두 UTF-8 (또는 ASCII) 여야 함
# 한글/emoji는 포함되면 안 됨
```

### 문제: Stage 2 DB validation 실패

**해결**: Production password 확인
```bash
ssh kjh2064@178.104.200.7
PGPASSWORD="pvuIp8fWNj+oWfZtciw43GzJ4yU0vwKf" \
  psql -h 127.0.0.1 -U quantengine_app -d quantenginedb -c "SELECT 1"
```

### 문제: Stage 4 Build 느려짐

**해결**: 캐시 무효화 여부 확인
```bash
dotnet clean src/dotnet/QuantEngine.Web/QuantEngine.Web.csproj
# 그 후 다시 build
```

---

## 7. Dashboard 요약 (매주 업데이트)

### 2026-07-11 ~ 2026-07-18

| Run # | Date | Status | Time | Note |
|-------|------|--------|------|------|
| 530   | 7-11 | FAIL   | 3m   | Tier 1 encoding 이슈 |
| 533   | 7-11 | FAIL   | 5m   | Tier 2 DB secret |
| 535   | 7-11 | PASS   | 18m  | Phase 5 첫 성공 |

**Trend**: ✅ Improving (실패율 감소)

---

## 참고 자료

- `.gitea/workflows/` - 모든 CI/CD workflow 정의
- `docs/CICD_ANALYSIS_AND_ROADMAP.md` - 아키텍처 및 로드맵
- `docs/CI_CD_IMPLEMENTATION_SUMMARY.md` - 이전 구현 요약
- `CLAUDE.md` - 프로젝트 기준 및 정책