Code/docs/GUIDE_LOGS.md

# 📋 Guide d'utilisation des Logs - FabNum

**Date** : 2026-02-07
**Module** : utils/logger.py

---

## 📂 Emplacement des logs

Tous les logs sont centralisés dans le dossier :
```
logs/
├── utils_graph_utils.log           # Logs des fonctions de graphe
├── utils_widgets.log                # Logs des widgets HTML
├── batch_ia_utils_sections.log      # Logs génération sections IA
├── app_fiches_utils_tickets_display.log  # Logs affichage tickets
└── app_plan_d_action_utils_data_data_utils.log  # Logs plan d'action
```

Chaque module a **son propre fichier de log**, ce qui facilite le débogage ciblé.

---

## 🔍 Comment consulter les logs

### 1. **Voir les logs en temps réel**

```bash
# Suivre tous les logs
tail -f logs/*.log

# Suivre un module spécifique
tail -f logs/utils_graph_utils.log

# Suivre plusieurs modules
tail -f logs/utils_graph_utils.log logs/batch_ia_utils_sections.log
```

### 2. **Voir les derniers logs**

```bash
# 20 dernières lignes de tous les logs
tail -20 logs/*.log

# 50 dernières lignes d'un module spécifique
tail -50 logs/utils_graph_utils.log
```

### 3. **Rechercher dans les logs**

```bash
# Chercher toutes les erreurs
grep -r "ERROR" logs/

# Chercher tous les warnings
grep -r "WARNING" logs/

# Chercher un terme spécifique
grep -r "hafnium" logs/

# Chercher avec contexte (3 lignes avant/après)
grep -C 3 "ERROR" logs/*.log
```

### 4. **Filtrer par niveau de log**

```bash
# Voir uniquement les erreurs et warnings
grep -E "ERROR|WARNING" logs/*.log

# Voir uniquement les erreurs critiques
grep "ERROR" logs/*.log

# Exclure les tests
grep -v "test_" logs/*.log | grep ERROR
```

### 5. **Analyser par période**

```bash
# Logs d'aujourd'hui
grep "$(date +%Y-%m-%d)" logs/*.log

# Logs d'une heure spécifique
grep "2026-02-07 17:" logs/*.log
```

---

## 📊 Exemples de logs actuels

### ✅ Logs normaux (WARNING)

```
2026-02-07 17:24:25 - utils.graph_utils - WARNING - Nœuds manquants pour MineraiInexistant : MineraiInexistant, Extraction_MineraiInexistant, Reserves_MineraiInexistant — Ignoré.
```

**Interprétation** : Le système cherche un minerai qui n'existe pas dans le graphe. C'est normal lors des tests, le système l'ignore gracieusement.

---

### ✅ Logs cas edge (WARNING)

```
2026-02-07 17:28:21 - batch_ia.utils.sections - WARNING - Impossible de traiter le produit 'Procédé EUV' (cas edge hafnium/EUV): 'NoneType' object has no attribute 'split'
```

**Interprétation** : Le cas edge de l'hafnium lié au procédé EUV est détecté. Le système continue le traitement des autres produits. C'est le comportement attendu.

---

## 🎨 Format des logs

Chaque ligne de log suit ce format :
```
[TIMESTAMP] - [MODULE] - [NIVEAU] - [MESSAGE]
```

**Exemple** :
```
2026-02-07 17:24:25 - utils.graph_utils - WARNING - Nœuds manquants pour MineraiInexistant
│                    │                    │         │
│                    │                    │         └─ Message détaillé
│                    │                    └─────────── Niveau (DEBUG, INFO, WARNING, ERROR, CRITICAL)
│                    └──────────────────────────────── Nom du module Python
└───────────────────────────────────────────────────── Timestamp (YYYY-MM-DD HH:MM:SS)
```

---

## 🎯 Niveaux de log

| Niveau | Usage | Action recommandée |
|--------|-------|-------------------|
| **DEBUG** | Informations détaillées pour le débogage | Ignorer en production |
| **INFO** | Informations générales (chargement, succès) | Surveillance normale |
| **WARNING** | Situations anormales mais gérées | Surveiller, pas d'action immédiate |
| **ERROR** | Erreurs qui empêchent une fonctionnalité | **Action requise** |
| **CRITICAL** | Erreurs système graves | **Action immédiate** |

---

## 🔧 Commandes utiles

### Nettoyer les logs de tests

```bash
# Supprimer tous les logs de tests (test_*.log)
rm logs/test_*.log

# Supprimer tous les logs vides
find logs/ -name "*.log" -type f -empty -delete
```

### Archiver les anciens logs

```bash
# Créer un dossier d'archives
mkdir -p logs/archives

# Archiver les logs de la semaine dernière
tar -czf logs/archives/logs_$(date +%Y%m%d).tar.gz logs/*.log

# Vider les logs actuels (garder les fichiers)
truncate -s 0 logs/*.log
```

### Surveiller les erreurs en temps réel

```bash
# Afficher uniquement les nouvelles erreurs
tail -f logs/*.log | grep --line-buffered "ERROR"

# Avec notification sonore
tail -f logs/*.log | grep --line-buffered "ERROR" && echo -e '\a'
```

---

## 📈 Monitoring en production

### 1. **Surveillance quotidienne**

```bash
# Script de surveillance (à lancer quotidiennement)
#!/bin/bash
echo "=== Rapport de logs FabNum - $(date) ==="
echo ""
echo "Nombre d'erreurs aujourd'hui:"
grep "$(date +%Y-%m-%d)" logs/*.log | grep -c "ERROR"
echo ""
echo "Nombre de warnings aujourd'hui:"
grep "$(date +%Y-%m-%d)" logs/*.log | grep -c "WARNING"
echo ""
echo "Dernières erreurs:"
grep "$(date +%Y-%m-%d)" logs/*.log | grep "ERROR" | tail -5
```

### 2. **Alertes par email** (optionnel)

```bash
# Si plus de 10 erreurs aujourd'hui, envoyer un email
ERROR_COUNT=$(grep "$(date +%Y-%m-%d)" logs/*.log | grep -c "ERROR")
if [ $ERROR_COUNT -gt 10 ]; then
    echo "⚠️ $ERROR_COUNT erreurs détectées" | mail -s "Alerte FabNum" admin@example.com
fi
```

### 3. **Dashboard simple**

```bash
# Afficher un résumé coloré
echo -e "\n📊 Résumé des logs FabNum\n"
echo "🔵 INFO:    $(grep -c 'INFO' logs/*.log 2>/dev/null || echo 0)"
echo "🟡 WARNING: $(grep -c 'WARNING' logs/*.log 2>/dev/null || echo 0)"
echo "🔴 ERROR:   $(grep -c 'ERROR' logs/*.log 2>/dev/null || echo 0)"
```

---

## 🛠️ Dépannage

### Problème : Les logs ne s'affichent pas

**Solution 1** : Vérifier les permissions
```bash
ls -lh logs/
chmod 755 logs/
chmod 644 logs/*.log
```

**Solution 2** : Vérifier que le dossier logs/ existe
```bash
mkdir -p logs
```

**Solution 3** : Vérifier le niveau de log dans le code
```python
# Dans votre module
from utils.logger import setup_logger
logger = setup_logger(__name__, level="DEBUG")  # Forcer DEBUG
```

### Problème : Trop de logs

**Solution** : Augmenter le niveau de log
```python
# Passer de DEBUG à INFO
logger = setup_logger(__name__, level="INFO")
```

### Problème : Logs en double

**Solution** : Le logger est configuré plusieurs fois
```python
# S'assurer d'appeler setup_logger une seule fois par module
# Au début du fichier, en global
logger = setup_logger(__name__)
```

---

## 📝 Bonnes pratiques

### ✅ À FAIRE

```python
# Utiliser le bon niveau
logger.info("Chargement du graphe réussi")
logger.warning("Nœud manquant, utilisation valeur par défaut")
logger.error("Impossible de se connecter à Gitea", exc_info=True)

# Ajouter du contexte
logger.error(f"Erreur lors du traitement de {produit_id}", exc_info=True)

# Logger les exceptions avec stacktrace
try:
    # code
except Exception as e:
    logger.error(f"Erreur inattendue: {e}", exc_info=True)
```

### ❌ À ÉVITER

```python
# Ne pas utiliser print()
print("Erreur")  # ❌

# Ne pas logger des informations sensibles
logger.info(f"Token: {GITEA_TOKEN}")  # ❌

# Ne pas logger en boucle sans limite
for i in range(10000):
    logger.debug(f"Iteration {i}")  # ❌ Surcharge
```

---

## 🎓 Exemples d'usage

### Exemple 1 : Déboguer un problème de chargement

```bash
# 1. Voir les derniers logs de graph_utils
tail -50 logs/utils_graph_utils.log

# 2. Chercher les erreurs
grep "ERROR" logs/utils_graph_utils.log

# 3. Voir le contexte autour d'une erreur
grep -C 5 "ERROR" logs/utils_graph_utils.log
```

### Exemple 2 : Surveiller la génération IA

```bash
# Suivre en temps réel
tail -f logs/batch_ia_utils_sections.log

# Filtrer les warnings
tail -f logs/batch_ia_utils_sections.log | grep "WARNING"
```

### Exemple 3 : Analyser les performances

```bash
# Compter combien de fois un minerai est manquant
grep "Nœuds manquants" logs/utils_graph_utils.log | wc -l

# Lister les minerais manquants uniques
grep "Nœuds manquants pour" logs/utils_graph_utils.log | \
  sed 's/.*pour \(.*\) :.*/\1/' | sort | uniq
```

---

## 📚 Ressources

- **Module source** : [utils/logger.py](utils/logger.py)
- **Tests** : [tests/unit/test_logger.py](tests/unit/test_logger.py)
- **Documentation** : [REFACTORING_REPORT.md](REFACTORING_REPORT.md)

---

**Dernière mise à jour** : 2026-02-07