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

```bash
# 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

```bash
npm install ws edge-runtime
```

### 3. Configuration package.json

```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

```javascript
// 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
```bash
# 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
```bash
# 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
```javascript
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

```bash
# 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

```javascript
// 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

```bash
# 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
```javascript
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
```javascript
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
```javascript
// ✅ Bon
logSh(`Utilisateur ${userId} connecté depuis ${ip}`, 'INFO');

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

### 3. Gestion des erreurs
```javascript
// ✅ 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
```javascript
// ✅ É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 :
```json
{"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 ! 🎯