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)

# 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 인코딩 확인

file .gitea/workflows/*.yml
# 모두 UTF-8 (또는 ASCII) 여야 함
# 한글/emoji는 포함되면 안 됨

문제: Stage 2 DB validation 실패

해결: Production password 확인

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 느려짐

해결: 캐시 무효화 여부 확인

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 - 프로젝트 기준 및 정책