152 lines
4.3 KiB
Markdown
152 lines
4.3 KiB
Markdown
# 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 |
|