wevia-brain/cognitive/debug/debugging-methodology.md

WEVIA OPUS — Debugging Methodology

Comment Opus 4.6 diagnostique et résout les problèmes techniques

Principe: Le debug est un PROCESSUS SCIENTIFIQUE, pas du tâtonnement

MÉTHODE EN 7 ÉTAPES

1. REPRODUIRE

Avant TOUTE action, confirmer le problème:

# Le symptôme exact (pas l'interprétation)
curl -v http://89.167.40.150:5821/api/brain-configs.php
# → Quel code HTTP? Quel body? Quel header?

# Le contexte
uptime            # Depuis quand le serveur tourne?
free -h           # RAM disponible?
df -h             # Disque plein?
systemctl status apache2  # Service en marche?

2. ISOLER

Réduire le périmètre:

# C'est le réseau?
ping 89.167.40.150
curl -I http://localhost:5821  # Depuis le serveur lui-même

# C'est Apache?
tail -20 /var/log/apache2/error.log

# C'est PHP?
php -l /opt/wevads/public/api/brain-configs.php  # Syntaxe
php -r "phpinfo();"  # Config PHP

# C'est la DB?
psql -U admin -d adx_system -c "SELECT 1"  # Connexion
psql -U admin -d adx_system -c "SELECT count(*) FROM admin.brain_configs"

3. HYPOTHÈSE (toujours au moins 3)

H1 (plus simple): Apache est tombé → systemctl restart apache2
H2 (probable): La requête SQL timeout → vérifier les locks/performances
H3 (edge case): Le fichier PHP a été corrompu → vérifier md5sum vs backup

4. TESTER L'HYPOTHÈSE LA PLUS SIMPLE D'ABORD

Suivre le principe d'Occam: la cause la plus simple est souvent la bonne.

5. CORRIGER

• TOUJOURS backup AVANT modification
• UN SEUL changement à la fois
• Documenter chaque changement

6. VÉRIFIER

# Le problème original est résolu?
curl -v http://89.167.40.150:5821/api/brain-configs.php  # Même test qu'étape 1

# Pas de régression?
# Tester les fonctions adjacentes
curl http://89.167.40.150:5821/health
curl http://89.167.40.150:5890/api/sentinel-brain.php?action=status

7. DOCUMENTER

Date: YYYY-MM-DD HH:MM
Symptôme: [ce qui ne marchait pas]
Cause: [root cause identifiée]
Correction: [ce qui a été fait]
Vérification: [comment on a confirmé]
Prévention: [ce qui empêchera la récurrence]

ARBRE DE DIAGNOSTIC PAR SYMPTÔME

"Le site ne répond pas"

1. ping → timeout? → Serveur down / réseau
          → OK? → Continue
2. curl localhost → timeout? → Service web down
                  → Connection refused? → Port non écouté
                  → 403? → .htaccess bloque
                  → 500? → Erreur PHP/app
                  → 200? → Problème DNS ou réseau externe
3. Si 500: tail /var/log/apache2/error.log
   → PHP Fatal Error? → Corriger le code
   → Permission denied? → chmod/chown
   → Out of memory? → Augmenter memory_limit ou tuer process

"L'email n'arrive pas"

1. PowerMTA queue: pmta show queue
   → Email en queue? → PMTA n'arrive pas à livrer
   → Queue vide? → L'email n'a jamais été soumis
2. Si en queue: pmta show counters
   → Beaucoup de bounces? → IP bloquée ou mauvaise adresse
   → Throttled? → ISP rate-limit, attendre
3. Vérifier les headers: envoyer un test à un Gmail personnel
   → SPF pass? → dig TXT domain.com
   → DKIM pass? → vérifier la clé DNS
   → DMARC pass? → vérifier la policy
4. Vérifier la réputation: senderscore.org, barracudacentral.org

"La requête SQL est lente"

1. EXPLAIN ANALYZE la requête
2. Seq Scan sur grande table? → Index manquant
3. Nested Loop avec beaucoup de rows? → Mauvais plan → ANALYZE la table
4. Sort/Hash très coûteux? → work_mem trop bas ou ORDER BY sur colonne non indexée
5. Locks? → SELECT * FROM pg_stat_activity WHERE state = 'active'

"Ollama ne répond pas"

1. curl http://88.198.4.195:11434/api/tags
   → Connection refused? → Service down → systemctl restart ollama
   → Timeout? → UFW/réseau bloque
   → 200 mais lent? → Modèle en cours de swap
2. GPU check: nvidia-smi
   → VRAM pleine? → Un modèle trop gros est chargé
   → GPU utilisation 0%? → Modèle pas chargé
3. Logs: journalctl -u ollama -n 50
   → OOM? → Modèle trop gros pour la VRAM
   → Layer mismatch? → Modèle corrompu → ollama rm + pull

OUTILS DE DIAGNOSTIC ESSENTIELS

# Système
top / htop              # CPU et mémoire en temps réel
free -h                 # RAM
df -h                   # Disque
iostat                  # I/O disque
vmstat 1                # Vue d'ensemble système

# Réseau
ss -tlnp                # Ports en écoute
netstat -tuln           # Alternative
iptables -L -n          # Règles firewall
tcpdump -i eth0 port 80 # Capture réseau
curl -v URL             # Debug HTTP complet
dig domain.com          # DNS
traceroute IP           # Chemin réseau

# Processus
ps aux | grep processus # Trouver un processus
lsof -i :port          # Qui utilise un port
strace -p PID          # Tracer les appels système
pgrep -la pattern      # Chercher processus par nom

# Logs
journalctl -xe         # Dernières erreurs système
tail -f /var/log/syslog # Log système temps réel
tail -f /var/log/apache2/error.log  # Apache errors
grep -r "ERROR" /var/log/ --include="*.log" -l  # Trouver les fichiers avec erreurs

# Base de données
pg_isready             # PostgreSQL répond?
psql -c "SELECT pg_database_size('adx_system')"  # Taille DB
psql -c "SELECT * FROM pg_stat_activity WHERE state != 'idle'"  # Requêtes actives