build-eye

# Sistema de Monitoramento CI Build-Eye **Olho de Águia de Build** - Sistema de monitoramento automatizado de builds CI e análise de causa raiz para vLLM-Ascend ## Visão Geral do Sistema Build-Eye é um sistema de monitoramento de builds CI projetado especificamente para o projeto vLLM-Ascend, capaz de: - **Monitorar automaticamente** os builds CI do repositório vllm-project/vllm-ascend - **Classificar inteligentemente** as causas raiz de falhas de build (problemas de código/problemas de infraestrutura/problemas de interferência) - **Gerar sugestões** de soluções de correção de baixo custo e aplicáveis - **Arquivar relatórios** padronizados automaticamente no repositório build-eye ## Objetivos de Monitoramento - Repositório principal monitorado: https://github.com/vllm-project/vllm-ascend - Repositório de arquivamento: https://github.com/winson-00178005/build-eye.git ## Classificação de Causas Raiz de Falhas ### 1. Problemas de Código do PR - Falha em asserções de teste - Erros de compilação (CMake, clang) - Erros de importação Python - Incompatibilidade com API do vLLM - Problemas de compilação de kernel Ascend ### 2. Problemas de Infraestrutura - Falha do K8s cache-service (cache-service.nginx-pypi-cache) - Runner indisponível - Problemas de hardware NPU (910B/910C/310P) - Problemas com CANN toolkit - Falha de comunicação multi-card HCCL - Falha ao baixar imagem Docker - Falha de cache Csrc - Timeout de build ### 3. Interferência de Múltiplos PRs Concorrentes - Múltiplos PRs mesclados em curto período - Diferenças na matriz de versões do vLLM - Competição por recursos de Runner - Impacto de atualizações de imagem CANN ## Início Rápido ### 1. Configurar GitHub Token Consulte `docs/token-setup.md` para configurar as chaves necessárias. ### 2. Instalar Dependências ```bash pip install -r requirements.txt ``` ### 3. Acionar Monitoramento Manualmente ```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. Arquivar Relatórios ```bash python scripts/archive/archiver.py --input reports/ --repo https://github.com/winson-00178005/build-eye.git ``` ## Workflow do GitHub Actions O sistema suporta dois modos de acionamento: ### Polling Agendado Verifica automaticamente falhas de build recentes a cada 6 horas. Arquivo de workflow: `.github/workflows/monitor.yml` ### Acionamento Manual Acionamento manual através do `workflow_dispatch` do GitHub Actions. Parâmetros opcionais: - `lookback_hours`: quantas horas no passado verificar (padrão 24) - `dry_run`: modo de execução de teste (sem arquivamento) - `target_repo`: repositório alvo ## Estrutura do Projeto ``` build-eye/ ├── .github/workflows/ │ └── monitor.yml # Workflow do GitHub Actions ├── scripts/ │ ├── monitor/ # Módulo de monitoramento CI │ │ ├── github_client.py # Cliente da API do GitHub │ │ ├── fetch_runs.py # Obter workflow runs │ │ ├── collect_metadata.py # Coletar metadados │ │ └── config_loader.py # Carregamento de configuração │ ├── classify/ # Módulo de classificação de falhas │ │ ├── classifier.py # Motor de classificação │ │ ├── code_detector.py # Detecção de problemas de código │ │ ├── infra_detector.py # Detecção de infraestrutura │ │ └── interference_detector.py # Detecção de interferência │ ├── recommend/ # Módulo de sugestões de correção │ │ ├── recommender.py # Gerador de sugestões │ │ └── templates.py # Templates de sugestões │ ├── report/ # Módulo de geração de relatórios │ │ ├── generator.py # Gerador de relatórios │ │ ├── formatter.py # Ferramentas de formatação │ │ └── summary.py # Geração de resumo │ └── archive/ # Módulo de arquivamento de relatórios │ ├── archiver.py # Arquivador │ └── git_client.py # Cliente Git ├── config/ │ └── config.yaml # Configuração do sistema ├── templates/ │ └ example_reports.py # Exemplos de relatórios ├── tests/ # Diretório de testes ├── docs/ │ └ token-setup.md # Guia de configuração de Token ├── reports/ # Diretório de saída de relatórios └ requirements.txt # Dependências Python └ requirements-dev.txt # Dependências de desenvolvimento └ README.md # Este documento ``` ## Opções de Configuração ### 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 ``` ### Variáveis de Ambiente - `GITHUB_TOKEN`: token de acesso à API do GitHub - `ARCHIVE_TOKEN`: token de escrita no repositório de arquivamento - `TARGET_REPO_OWNER`: owner do repositório alvo - `TARGET_REPO_NAME`: nome do repositório alvo ## Formato do Relatório Cada relatório contém: - YAML frontmatter (metadados) - Resumo (1-2 frases) - Análise de causa raiz (classificação, confiança, raciocínio) - Evidências (padrões correspondentes, links, trechos de log) - Sugestões de correção (sugestão prioritária, passos detalhados) - PRs relacionados (apenas para classificação de interferência) Caminho de arquivamento do relatório: `reports/YYYY/MM/DD/<classificação>-pr-<número>.md` ## Executar Testes ```bash pip install -r requirements-dev.txt pytest tests/ ``` ## Estender Pipeline Nightly O sistema já foi projetado para suportar monitoramento de pipeline nightly, bastando adicionar na configuração: ```yaml target_repository: monitored_workflows: - schedule_nightly_test_a2.yaml - schedule_nightly_test_a3.yaml ``` ## Manutenção e Extensão ### Adicionar Novas Regras de Classificação Adicione um novo detector em `scripts/classify/`: ```python def detect_new_pattern(log_excerpt: str) -> dict: patterns = [...] # Implementar lógica de detecção ``` Em seguida, chame-o em `classifier.py`. ### Adicionar Novos Templates de Sugestões Adicione novos templates em `scripts/recommend/templates.py`. ## Licença Apache License 2.0 - Consulte o arquivo LICENSE para detalhes ## Contato Feedback de problemas: https://github.com/winson-00178005/build-eye/issues