build-eye

# Система мониторинга CI Build-Eye **Build-Eye** — система автоматизированного мониторинга CI-сборок и анализа первопричин для vLLM-Ascend ## Обзор системы Build-Eye — это система мониторинга CI-сборок, разработанная специально для проекта vLLM-Ascend, которая умеет: - **Автоматически отслеживать** CI-сборки репозитория vllm-project/vllm-ascend - **Интеллектуально классифицировать** первопричины сбоев сборки (проблемы кода / проблемы инфраструктуры / проблемы помех) - **Формировать рекомендации** — низкозатратные и практически реализуемые решения по исправлению - **Архивировать отчёты** — стандартизированные отчёты автоматически архивируются в репозиторий build-eye ## Цели мониторинга - Основной отслеживаемый репозиторий: https://github.com/vllm-project/vllm-ascend - Репозиторий архивации: https://github.com/winson-00178005/build-eye.git ## Классификация первопричин сбоев ### 1. Проблемы кода PR - Сбой тестовых утверждений - Ошибки компиляции (CMake, clang) - Ошибки импорта Python - Несовместимость API vLLM - Проблемы компиляции 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` ### Ручной запуск Запуск вручную через `workflow_dispatch` в GitHub Actions. Необязательные параметры: - `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 - `ARCHIVE_TOKEN`: токен записи в репозиторий архивации - `TARGET_REPO_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