build-eye

# Build-Eye CI 모니터링 시스템 **빌드 아이** - vLLM-Ascend CI 빌드 자동 모니터링 및 근본 원인 분석 시스템 ## 시스템 개요 Build-Eye는 vLLM-Ascend 프로젝트를 위해 설계된 CI 빌드 모니터링 시스템으로, 다음을 수행할 수 있습니다: - vllm-project/vllm-ascend 저장소의 CI 빌드를 **자동 모니터링** - 빌드 실패 근본 원인(코드 문제/인프라 문제/간섭 문제)을 **지능적으로 분류** - 저비용으로 실행 가능한 수정 방안 **제안 생성** - 표준화된 보고서를 build-eye 저장소에 자동 **보관** ## 모니터링 대상 - 주 모니터링 저장소: https://github.com/vllm-project/vllm-ascend - 보관 호스팅 저장소: https://github.com/winson-00178005/build-eye.git ## 실패 근본 원인 분류 ### 1. PR 코드 문제 - 테스트 어서션 실패 - 컴파일 오류(CMake, clang) - Python 임포트 오류 - vLLM API 비호환 - Ascend kernel 컴파일 문제 ### 2. 인프라 문제 - K8s cache-service 실패(cache-service.nginx-pypi-cache) - Runner 사용 불가 - NPU 하드웨어 문제(910B/910C/310P) - CANN toolkit 문제 - HCCL 다중 카드 통신 실패 - Docker 이미지 풀 실패 - Csrc 캐시 실패 - 빌드 타임아웃 ### 3. 다중 PR 동시 간섭 - 단시간 내 여러 PR 머지 - vLLM 버전 매트릭스 차이 - Runner 리소스 경쟁 - CANN 이미지 업데이트 영향 ## 빠른 시작 ### 1. GitHub Token 설정 필수 키 설정은 `docs/token-setup.md`를 참조하세요. ### 2. 의존성 설치 ```bash pip install -r requirements.txt ``` ### 3. 수동 모니터링 트리거 ```bash python scripts/monitor/fetch_runs.py --output data/workflow_runs.json python scripts/monitor/collect_metadata.py --input data/workflow_runs.json --output data/build_metadata.json python scripts/classify/classifier.py --input data/build_metadata.json --output data/classifications.json python scripts/recommend/recommender.py --input data/classifications.json --output data/recommendations.json python scripts/report/generator.py --input data/recommendations.json --output reports/ ``` ### 4. 보고서 보관 ```bash python scripts/archive/archiver.py --input reports/ --repo https://github.com/winson-00178005/build-eye.git ``` ## GitHub Actions 워크플로 시스템은 두 가지 트리거 모드를 지원합니다: ### 정기 폴링 6시간마다 최근 빌드 실패를 자동으로 확인합니다. 워크플로 파일: `.github/workflows/monitor.yml` ### 수동 트리거 GitHub Actions의 `workflow_dispatch`를 통해 수동으로 트리거합니다. 선택 매개변수: - `lookback_hours`: 과거 몇 시간을 확인할지(기본 24) - `dry_run`: 시험 실행 모드(보관하지 않음) - `target_repo`: 대상 저장소 ## 프로젝트 구조 ``` build-eye/ ├── .github/workflows/ │ └── monitor.yml # GitHub Actions 워크플로 ├── scripts/ │ ├── monitor/ # CI 모니터링 모듈 │ │ ├── github_client.py # GitHub API 클라이언트 │ │ ├── fetch_runs.py # workflow runs 가져오기 │ │ ├── collect_metadata.py # 메타데이터 수집 │ │ └── config_loader.py # 설정 로드 │ ├── classify/ # 실패 분류 모듈 │ │ ├── classifier.py # 분류 엔진 │ │ ├── code_detector.py # 코드 문제 감지 │ │ ├── infra_detector.py # 인프라 감지 │ │ └── interference_detector.py # 간섭 감지 │ ├── recommend/ # 수정 제안 모듈 │ │ ├── recommender.py # 제안 생성기 │ │ └── templates.py # 제안 템플릿 │ ├── report/ # 보고서 생성 모듈 │ │ ├── generator.py # 보고서 생성기 │ │ ├── formatter.py # 포맷 도구 │ │ └── summary.py # 요약 생성 │ └── archive/ # 보고서 보관 모듈 │ ├── archiver.py # 보관기 │ └── git_client.py # Git 클라이언트 ├── config/ │ └── config.yaml # 시스템 설정 ├── templates/ │ └ example_reports.py # 보고서 예시 ├── tests/ # 테스트 디렉터리 ├── docs/ │ └ token-setup.md # Token 설정 가이드 ├── reports/ # 보고서 출력 디렉터리 └ requirements.txt # Python 의존성 └ requirements-dev.txt # 개발 의존성 └ README.md # 본 문서 ``` ## 설정 옵션 ### config/config.yaml ```yaml target_repository: owner: vllm-project repo: vllm-ascend url: https://github.com/vllm-project/vllm-ascend branch: main monitored_workflows: - pr_test_full.yaml - pr_test_light.yaml archive_repository: owner: winson-00178005 repo: build-eye url: https://github.com/winson-00178005/build-eye.git monitoring: polling_interval_hours: 6 lookback_hours: 24 ``` ### 환경 변수 - `GITHUB_TOKEN`: GitHub API 접근 token - `ARCHIVE_TOKEN`: 보관 저장소 쓰기 token - `TARGET_REPO_OWNER`: 대상 저장소 owner - `TARGET_REPO_NAME`: 대상 저장소 이름 ## 보고서 형식 각 보고서는 다음을 포함합니다: - YAML frontmatter(메타데이터) - 개요(1-2문장) - 근본 원인 분석(분류, 신뢰도, 추론) - 증거(매칭 패턴, 링크, 로그 발췌) - 수정 제안(우선 제안, 상세 단계) - 관련 PR(간섭 분류에만 해당) 보고서 보관 경로: `reports/YYYY/MM/DD/<분류>-pr-<번호>.md` ## 테스트 실행 ```bash pip install -r requirements-dev.txt pytest tests/ ``` ## nightly 파이프라인 확장 시스템은 nightly 파이프라인 모니터링을 지원하도록 설계되었으며, 설정에 다음을 추가하기만 하면 됩니다: ```yaml target_repository: monitored_workflows: - schedule_nightly_test_a2.yaml - schedule_nightly_test_a3.yaml ``` ## 유지보수 및 확장 ### 새로운 분류 규칙 추가 `scripts/classify/`에 새로운 감지기를 추가합니다: ```python def detect_new_pattern(log_excerpt: str) -> dict: patterns = [...] # 감지 로직 구현 ``` 그런 다음 `classifier.py`에서 호출합니다. ### 새로운 제안 템플릿 추가 `scripts/recommend/templates.py`에 새 템플릿을 추가합니다. ## 라이선스 Apache License 2.0 - 자세한 내용은 LICENSE 파일 참조 ## 연락처 문제 피드백: https://github.com/winson-00178005/build-eye/issues