diagnosis.md — Contexte mode diagnostic

Type : Contexte — propriétaire : debug, monitoring Rédigé : 2026-03-14 Résout : "debug multi-infra sans ordre de lecture des logs = hypothèses au hasard, diagnostic circulaire"

Problème résolu

En environnement multi-services (VPS + containers + Node.js + MySQL + Apache + pm2), un bug peut venir de n'importe quelle couche. Sans ordre de lecture formalisé, le debug suit l'intuition — ce qui amène à relire les mêmes logs en boucle sans jamais identifier la cause racine.

Ce contexte impose un ordre d'investigation et un protocole d'hypothèses.

Ordre de lecture des logs — multi-infra

Couche 1 — Infrastructure (première)

systemctl status <service>         # est-il up ?
journalctl -u <service> -n 50      # dernières erreurs système
dmesg | tail -20                   # erreurs kernel (OOM, disk)
df -h && free -h                   # ressources (disk full = cause fréquente silencieuse)

Couche 2 — Réseau / Proxy

# Apache / Nginx
tail -n 100 /var/log/apache2/error.log
tail -n 100 /var/log/nginx/error.log

# SSL
openssl s_client -connect <host>:443 -brief

# Ports
ss -tlnp | grep <port>

Couche 3 — Application

# pm2
pm2 logs <app> --lines 100
pm2 show <app>                     # état mémoire, restarts

# Docker
docker logs <container> --tail 100
docker stats <container>           # mémoire / CPU

Couche 4 — Base de données

# MySQL — dernières erreurs
tail -n 50 /var/log/mysql/error.log

# Connexions actives
SHOW PROCESSLIST;
SHOW STATUS LIKE 'Threads_connected';

Couche 5 — Application code

# Uniquement après avoir éliminé les couches 1-4
# Logs applicatifs, stack traces, erreurs TypeScript runtime

Protocole d'hypothèses

Règle : une hypothèse à la fois, vérifiée avant la suivante.

1. Formuler l'hypothèse : "Je pense que X est causé par Y parce que Z"
2. Identifier le log ou la commande qui confirme ou infirme Y
3. Exécuter — lire le résultat
4. Confirmer ou infirmer explicitement
5. Si infirmé → hypothèse suivante (pas de "peut-être les deux")

Anti-pattern à éviter :

Proposer 3 causes simultanées sans les tester → confus, lent
Modifier le code avant d'identifier la cause → cache le vrai problème
"Ça vient sûrement de X" sans log qui confirme

Questions de cadrage au démarrage d'un diagnostic

1. Quel service est affecté ? (nom précis)
2. Depuis quand ? (heure, event déclencheur)
3. C'est reproductible ? (always / intermittent / once)
4. Qu'est-ce qui a changé juste avant ? (deploy, config, restart)
5. Quel est le symptôme exact ? (message d'erreur complet ou comportement observé)

Ces 5 questions évitent 80% des diagnostics circulaires.

Cross-services — quel serveur, quelle stack

En multi-infra (prod@desktop + VPS + containers) :

Symptôme	Première couche à vérifier
502 Bad Gateway	Apache → pm2/container (dans cet ordre)
Connexion refusée	Port ouvert ? → Service up ? → Firewall ?
Lenteur API	pm2 logs → MySQL PROCESSLIST → Node heap
Auth échoue	JWT valide ? → Redis (sessions) → MySQL (user)
Mail non livré	SPF/DKIM → Stalwart logs → DNS
Deploy échoue	CI/CD logs → Docker build → VPS disk

Trigger de chargement

Propriétaire : debug, monitoring
Trigger      : session de type "debug" détectée, ou symptôme multi-services
Section      : Sources conditionnelles (debug — si infra détectée dans le scope)

Maintenance

Propriétaire : debug (mise à jour si nouveau pattern de diagnostic validé)
Mise à jour  : en fin de session debug si une nouvelle séquence d'investigation a été utile
Jamais modifié par : agents non-debug

Cycle de vie

État	Condition	Action
Actif	Sessions debug fréquentes	Enrichi après chaque pattern validé
Stable	Stack stable, peu de bugs infra	Consulté, rarement modifié
Archivé	N/A	Non applicable

Changelog

Date	Changement
2026-03-14	Création — ordre lecture 5 couches, protocole hypothèses, cross-services table, questions cadrage

4.3 KiB Raw Blame History