build-eye

# Système de surveillance CI Build-Eye **Œil de build** - Système automatisé de surveillance et d'analyse des causes racines des builds CI de vLLM-Ascend ## Présentation du système Build-Eye est un système de surveillance des builds CI conçu spécifiquement pour le projet vLLM-Ascend, capable de : - **Surveiller automatiquement** les builds CI du dépôt vllm-project/vllm-ascend - **Classer intelligemment** les causes racines des échecs de build (problème de code / problème d'infrastructure / problème d'interférence) - **Générer des suggestions** de correction à faible coût et applicables - **Archiver les rapports** : les rapports standardisés sont automatiquement archivés dans le dépôt build-eye ## Cibles de surveillance - Dépôt principal surveillé : https://github.com/vllm-project/vllm-ascend - Dépôt d'archivage : https://github.com/winson-00178005/build-eye.git ## Classification des causes racines d'échec ### 1. Problème de code de la PR - Échec d'assertion de test - Erreur de compilation (CMake, clang) - Erreur d'import Python - Incompatibilité d'API vLLM - Problème de compilation du kernel Ascend ### 2. Problème d'infrastructure - Échec du cache-service K8s (cache-service.nginx-pypi-cache) - Runner indisponible - Problème matériel NPU (910B/910C/310P) - Problème de toolkit CANN - Échec de communication multi-cartes HCCL - Échec de téléchargement de l'image Docker - Échec du cache Csrc - Délai d'attente de build dépassé ### 3. Interférence de concurrence entre plusieurs PR - Plusieurs PR fusionnées en peu de temps - Différences de matrice de versions vLLM - Concurrence des ressources des runners - Impact des mises à jour d'images CANN ## Démarrage rapide ### 1. Configurer le token GitHub Voir `docs/token-setup.md` pour configurer les clés requises. ### 2. Installer les dépendances ```bash pip install -r requirements.txt ``` ### 3. Déclencher manuellement la surveillance ```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. Archiver les rapports ```bash python scripts/archive/archiver.py --input reports/ --repo https://github.com/winson-00178005/build-eye.git ``` ## Workflow GitHub Actions Le système prend en charge deux modes de déclenchement : ### Interrogation planifiée Vérifie automatiquement les échecs de build récents toutes les 6 heures. Fichier de workflow : `.github/workflows/monitor.yml` ### Déclenchement manuel Déclenchement manuel via `workflow_dispatch` de GitHub Actions. Paramètres optionnels : - `lookback_hours` : nombre d'heures à examiner (par défaut 24) - `dry_run` : mode essai (sans archivage) - `target_repo` : dépôt cible ## Structure du projet ``` build-eye/ ├── .github/workflows/ │ └── monitor.yml # Workflow GitHub Actions ├── scripts/ │ ├── monitor/ # Module de surveillance CI │ │ ├── github_client.py # Client API GitHub │ │ ├── fetch_runs.py # Récupérer les workflow runs │ │ ├── collect_metadata.py # Collecter les métadonnées │ │ └── config_loader.py # Chargement de configuration │ ├── classify/ # Module de classification des échecs │ │ ├── classifier.py # Moteur de classification │ │ ├── code_detector.py # Détection des problèmes de code │ │ ├── infra_detector.py # Détection d'infrastructure │ │ └── interference_detector.py # Détection d'interférence │ ├── recommend/ # Module de suggestions de correction │ │ ├── recommender.py # Générateur de suggestions │ │ └── templates.py # Modèles de suggestions │ ├── report/ # Module de génération de rapports │ │ ├── generator.py # Générateur de rapports │ │ ├── formatter.py # Outils de formatage │ │ └── summary.py # Génération de résumé │ └── archive/ # Module d'archivage des rapports │ ├── archiver.py # Archiveur │ └── git_client.py # Client Git ├── config/ │ └── config.yaml # Configuration du système ├── templates/ │ └ example_reports.py # Exemples de rapports ├── tests/ # Répertoire de tests ├── docs/ │ └ token-setup.md # Guide de configuration du token ├── reports/ # Répertoire de sortie des rapports └ requirements.txt # Dépendances Python └ requirements-dev.txt # Dépendances de développement └ README.md # Ce document ``` ## Options de configuration ### 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 ``` ### Variables d'environnement - `GITHUB_TOKEN` : token d'accès à l'API GitHub - `ARCHIVE_TOKEN` : token d'écriture du dépôt d'archivage - `TARGET_REPO_OWNER` : propriétaire du dépôt cible - `TARGET_REPO_NAME` : nom du dépôt cible ## Format des rapports Chaque rapport contient : - YAML frontmatter (métadonnées) - Résumé (1-2 phrases) - Analyse des causes racines (classification, confiance, raisonnement) - Preuves (modèles correspondants, liens, extraits de journaux) - Suggestions de correction (suggestion prioritaire, étapes détaillées) - PR associées (uniquement pour la classification d'interférence) Chemin d'archivage des rapports : `reports/YYYY/MM/DD/<classification>-pr-<numéro>.md` ## Exécuter les tests ```bash pip install -r requirements-dev.txt pytest tests/ ``` ## Extension au pipeline nightly Le système est déjà conçu pour prendre en charge la surveillance du pipeline nightly ; il suffit d'ajouter dans la configuration : ```yaml target_repository: monitored_workflows: - schedule_nightly_test_a2.yaml - schedule_nightly_test_a3.yaml ``` ## Maintenance et extension ### Ajouter de nouvelles règles de classification Ajouter un nouveau détecteur dans `scripts/classify/` : ```python def detect_new_pattern(log_excerpt: str) -> dict: patterns = [...] # Implémenter la logique de détection ``` Puis l'appeler dans `classifier.py`. ### Ajouter de nouveaux modèles de suggestions Ajouter de nouveaux modèles dans `scripts/recommend/templates.py`. ## Licence Apache License 2.0 - voir le fichier LICENSE pour plus de détails ## Contact Retour de problèmes : https://github.com/winson-00178005/build-eye/issues