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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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)

# 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

# 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

ls -lh logs/
chmod 755 logs/
chmod 644 logs/*.log

Solution 2 : Vérifier que le dossier logs/ existe

mkdir -p logs

Solution 3 : Vérifier le niveau de log dans le code

# 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

# Passer de DEBUG à INFO
logger = setup_logger(__name__, level="INFO")

Problème : Logs en double

Solution : Le logger est configuré plusieurs fois

# 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

# 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

# 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

# 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

# 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

# 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
• Tests : tests/unit/test_logger.py
• Documentation : REFACTORING_REPORT.md

---

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