sourcefinder/export_logger/README.md

📋 Système de Logging SEO Generator

Système de logging centralisé avec support multi-output (Console + File + WebSocket) et visualisation en temps réel.

🏗️ Architecture

Composants principaux

1. ErrorReporting.js - Système de logging centralisé avec logSh()
2. trace.js - Système de traçage hiérarchique avec AsyncLocalStorage
3. trace-wrap.js - Utilitaires de wrapping pour le tracing
4. logviewer.cjs - Outil CLI pour consulter les logs
5. logs-viewer.html - Interface web temps réel
6. log-server.cjs - Serveur WebSocket pour logs temps réel

🚀 Installation

1. Copier les fichiers

# Dans votre projet Node.js
cp ErrorReporting.js lib/
cp trace.js lib/
cp trace-wrap.js lib/
cp logviewer.cjs tools/
cp logs-viewer.html tools/
cp log-server.cjs tools/

2. Installer les dépendances

npm install ws edge-runtime

3. Configuration package.json

{
  "scripts": {
    "logs": "node tools/logviewer.cjs",
    "logs:server": "node tools/log-server.cjs",
    "logs:pretty": "node tools/logviewer.cjs --pretty"
  }
}

📝 Utilisation

1. Dans votre code

// Import principal
const { logSh, setupTracer } = require('./lib/ErrorReporting');

// Configuration du traceur (optionnel)
const tracer = setupTracer('MonModule');

// Utilisation basique
logSh('Message info', 'INFO');
logSh('Erreur détectée', 'ERROR');
logSh('Debug info', 'DEBUG');

// Avec traçage hiérarchique
await tracer.run('maFonction', async () => {
  logSh('Début opération', 'TRACE');
  // ... votre code
  logSh('Fin opération', 'TRACE');
}, { param1: 'value1' });

2. Consultation des logs

Via CLI

# Logs récents avec formatage
npm run logs:pretty

# Recherche par mot-clé
node tools/logviewer.cjs --search --includes "ERROR" --pretty

# Filtrer par niveau
node tools/logviewer.cjs --level ERROR --pretty

# Plage temporelle
node tools/logviewer.cjs --since 2025-01-01T00:00:00Z --until 2025-01-01T23:59:59Z

Via interface web

# Lancer le serveur WebSocket
npm run logs:server

# Ouvrir logs-viewer.html dans un navigateur
# L'interface se connecte automatiquement sur ws://localhost:8081

🎯 Fonctionnalités

Niveaux de logs

• TRACE (10) : Exécution hiérarchique avec symboles ▶ ✔ ✖
• DEBUG (20) : Information détaillée de débogage
• INFO (30) : Messages informatifs standard
• WARN (40) : Conditions d'avertissement
• ERROR (50) : Conditions d'erreur avec stack traces

Outputs multiples

• Console : Formatage coloré avec timestamps
• Fichier : JSON structuré dans logs/app-YYYY-MM-DD_HH-MM-SS.log
• WebSocket : Diffusion temps réel pour interface web

Traçage hiérarchique

const tracer = setupTracer('MonModule');

await tracer.run('operationPrincipale', async () => {
  logSh('▶ Début opération principale', 'TRACE');

  await tracer.run('sousOperation', async () => {
    logSh('▶ Début sous-opération', 'TRACE');
    // ... code
    logSh('✔ Sous-opération terminée', 'TRACE');
  }, { subParam: 'value' });

  logSh('✔ Opération principale terminée', 'TRACE');
}, { mainParam: 'value' });

🔧 Configuration

Variables d'environnement

# Niveau de log minimum (défaut: INFO)
LOG_LEVEL=DEBUG

# Port WebSocket (défaut: 8081)
WEBSOCKET_PORT=8081

# Répertoire des logs (défaut: logs/)
LOG_DIRECTORY=logs

Personnalisation ErrorReporting.js

// Modifier les couleurs console
const COLORS = {
  TRACE: '\x1b[90m',  // Gris
  DEBUG: '\x1b[34m',  // Bleu
  INFO: '\x1b[32m',   // Vert
  WARN: '\x1b[33m',   // Jaune
  ERROR: '\x1b[31m'   // Rouge
};

// Modifier le format de fichier
const logEntry = {
  level: numericLevel,
  time: new Date().toISOString(),
  msg: message,
  // Ajouter des champs personnalisés
  module: 'MonModule',
  userId: getCurrentUserId()
};

📊 Interface Web (logs-viewer.html)

Fonctionnalités

• ✅ Logs temps réel via WebSocket
• ✅ Filtrage par niveau (TRACE, DEBUG, INFO, WARN, ERROR)
• ✅ Recherche textuelle dans les messages
• ✅ Auto-scroll avec possibilité de pause
• ✅ Formatage coloré selon niveau
• ✅ Timestamps lisibles

Utilisation

1. Lancer le serveur WebSocket : npm run logs:server
2. Ouvrir logs-viewer.html dans un navigateur
3. L'interface se connecte automatiquement et affiche les logs

🛠️ Outils CLI

logviewer.cjs

# Options disponibles
--pretty           # Formatage coloré et lisible
--last N           # N dernières lignes (défaut: 200)
--level LEVEL      # Filtrer par niveau (TRACE, DEBUG, INFO, WARN, ERROR)
--includes TEXT    # Rechercher TEXT dans les messages
--regex PATTERN    # Recherche par expression régulière
--since DATE       # Logs depuis cette date (ISO ou YYYY-MM-DD)
--until DATE       # Logs jusqu'à cette date
--module MODULE    # Filtrer par module
--search           # Mode recherche interactif

# Exemples
node tools/logviewer.cjs --last 100 --level ERROR --pretty
node tools/logviewer.cjs --search --includes "Claude" --pretty
node tools/logviewer.cjs --since 2025-01-15 --pretty

🎨 Exemples d'usage

Logging simple

const { logSh } = require('./lib/ErrorReporting');

// Messages informatifs
logSh('Application démarrée', 'INFO');
logSh('Utilisateur connecté: john@example.com', 'DEBUG');

// Gestion d'erreurs
try {
  // ... code risqué
} catch (error) {
  logSh(`Erreur lors du traitement: ${error.message}`, 'ERROR');
}

Traçage de fonction complexe

const { logSh, setupTracer } = require('./lib/ErrorReporting');
const tracer = setupTracer('UserService');

async function processUser(userId) {
  return await tracer.run('processUser', async () => {
    logSh(`▶ Traitement utilisateur ${userId}`, 'TRACE');

    const user = await tracer.run('fetchUser', async () => {
      logSh('▶ Récupération données utilisateur', 'TRACE');
      const userData = await database.getUser(userId);
      logSh('✔ Données utilisateur récupérées', 'TRACE');
      return userData;
    }, { userId });

    await tracer.run('validateUser', async () => {
      logSh('▶ Validation données utilisateur', 'TRACE');
      validateUserData(user);
      logSh('✔ Données utilisateur validées', 'TRACE');
    }, { userId, userEmail: user.email });

    logSh('✔ Traitement utilisateur terminé', 'TRACE');
    return user;
  }, { userId });
}

🚨 Bonnes pratiques

1. Niveaux appropriés

• TRACE : Flux d'exécution détaillé (entrée/sortie fonctions)
• DEBUG : Information de débogage (variables, états)
• INFO : Événements importants (démarrage, connexions)
• WARN : Situations inhabituelles mais gérables
• ERROR : Erreurs nécessitant attention

2. Messages structurés

// ✅ Bon
logSh(`Utilisateur ${userId} connecté depuis ${ip}`, 'INFO');

// ❌ Éviter
logSh('Un utilisateur s\'est connecté', 'INFO');

3. Gestion des erreurs

// ✅ Avec contexte
try {
  await processPayment(orderId);
} catch (error) {
  logSh(`Erreur traitement paiement commande ${orderId}: ${error.message}`, 'ERROR');
  logSh(`Stack trace: ${error.stack}`, 'DEBUG');
}

4. Performance

// ✅ Éviter logs trop fréquents en production
if (process.env.NODE_ENV === 'development') {
  logSh(`Variable debug: ${JSON.stringify(complexObject)}`, 'DEBUG');
}

📦 Structure des fichiers de logs

logs/
├── app-2025-01-15_10-30-45.log    # Logs JSON structurés
├── app-2025-01-15_14-22-12.log
└── ...

Format JSON par ligne :

{"level":20,"time":"2025-01-15T10:30:45.123Z","msg":"Message de log"}
{"level":30,"time":"2025-01-15T10:30:46.456Z","msg":"Autre message","module":"UserService","traceId":"abc123"}

🔄 Intégration dans projet existant

1. Remplacer console.log par logSh()
2. Ajouter traçage aux fonctions critiques
3. Configurer niveaux selon environnement
4. Mettre en place monitoring avec interface web
5. Automatiser consultation des logs via CLI

Ce système de logging vous donnera une visibilité complète sur le comportement de votre application ! 🎯