diff --git a/docs/CICD_MONITORING_GUIDE.md b/docs/CICD_MONITORING_GUIDE.md new file mode 100644 index 00000000..d8423daa --- /dev/null +++ b/docs/CICD_MONITORING_GUIDE.md @@ -0,0 +1,185 @@ +# 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` - 프로젝트 기준 및 정책 +