ihm_client/docs/LOGGING_GUIDELINES.md

Guide des bonnes pratiques de logging

Vue d'ensemble

Ce document décrit les bonnes pratiques pour l'utilisation des logs dans l'application 4NK. Nous utilisons un système de logging centralisé avec secureLogger pour assurer la cohérence et la sécurité.

Système de logging

SecureLogger

Le secureLogger est le système de logging principal de l'application. Il fournit :

• Sanitisation automatique des données sensibles
• Niveaux de log structurés (DEBUG, INFO, WARN, ERROR)
• Contexte enrichi avec composant et métadonnées
• Formatage cohérent des messages

Import

import { secureLogger } from '../services/secure-logger';

Niveaux de log

DEBUG

Utilisé pour les informations de débogage détaillées, généralement utiles uniquement lors du développement.

secureLogger.debug('Memory usage after cleanup: 45.2%', { component: 'Service' });
secureLogger.debug('Checking credentials availability', { component: 'HomePage' });

Quand utiliser :

• Informations de débogage
• État interne des variables
• Progression des opérations complexes
• Messages avec emoji 🔍

INFO

Utilisé pour les informations générales sur le fonctionnement de l'application.

secureLogger.info('Home/Pairing page loaded', { component: 'HomePage' });
secureLogger.info('Services initialized successfully', { component: 'Service' });

Quand utiliser :

• Initialisation de composants
• Succès d'opérations
• Messages avec emoji ✅, 🔄, 🚀
• Événements importants du flux utilisateur

WARN

Utilisé pour les avertissements qui n'empêchent pas le fonctionnement mais méritent attention.

secureLogger.warn('High memory detected, performing cleanup', { component: 'Service' });
secureLogger.warn('Home page already initializing, skipping...', { component: 'HomePage' });

Quand utiliser :

• Conditions non critiques mais inhabituelles
• Messages avec emoji ⚠️
• Opérations de récupération
• Dégradations de performance

ERROR

Utilisé pour les erreurs qui empêchent le fonctionnement normal.

secureLogger.error('Failed to initialize services', error, { component: 'Service' });
secureLogger.error('Authentication failed', error, { component: 'HomePage' });

Quand utiliser :

• Erreurs critiques
• Messages avec emoji ❌
• Échecs d'opérations importantes
• Exceptions non gérées

Contexte et métadonnées

Composant

Toujours spécifier le composant dans le contexte :

secureLogger.info('Operation completed', { component: 'HomePage' });
secureLogger.error('Database connection failed', error, { component: 'Service' });

Métadonnées supplémentaires

Ajouter des métadonnées utiles pour le débogage :

secureLogger.debug('Wallet details', {
  component: 'HomePage',
  hasSpendKey: !!wallet.sp_wallet?.spend_key,
  hasScanKey: !!wallet.sp_wallet?.scan_key,
  birthday: wallet.sp_wallet?.birthday
});

Bonnes pratiques

1. Utiliser secureLogger au lieu de console.*

❌ Mauvais :

console.log('User authenticated');
console.error('Database error:', error);

✅ Bon :

secureLogger.info('User authenticated', { component: 'AuthService' });
secureLogger.error('Database error', error, { component: 'DatabaseService' });

2. Messages clairs et concis

❌ Mauvais :

secureLogger.info('x', { component: 'Service' });
secureLogger.info('Processing user request with id 12345 and data {name: "John", email: "john@example.com"}', { component: 'UserService' });

✅ Bon :

secureLogger.info('Processing user request', {
  component: 'UserService',
  userId: 12345,
  userName: 'John'
});

3. Niveaux appropriés

❌ Mauvais :

secureLogger.error('User clicked button'); // Pas une erreur
secureLogger.info('Critical system failure'); // Pas une info

✅ Bon :

secureLogger.debug('User clicked button', { component: 'UI' });
secureLogger.error('Critical system failure', error, { component: 'System' });

4. Contexte enrichi

❌ Mauvais :

secureLogger.info('Operation failed');

✅ Bon :

secureLogger.error('Operation failed', error, {
  component: 'PaymentService',
  operation: 'processPayment',
  userId: user.id,
  amount: payment.amount
});

5. Gestion des erreurs

try {
  await riskyOperation();
  secureLogger.info('Operation completed successfully', { component: 'Service' });
} catch (error) {
  secureLogger.error('Operation failed', error, {
    component: 'Service',
    operation: 'riskyOperation'
  });
  throw error;
}

Patterns d'emojis

DEBUG (🔍)

• 🔍 Checking...
• 🔍 Debug info:
• 🔍 Memory usage:

INFO (✅, 🔄, 🚀)

• ✅ Operation completed
• 🔄 Processing...
• 🚀 Starting...
• 🔧 Initializing...

WARN (⚠️)

• ⚠️ Warning:
• ⚠️ Skipping...
• ⚠️ High memory detected

ERROR (❌)

• ❌ Error:
• ❌ Failed to:
• ❌ Critical error:

Exemples par composant

Service

secureLogger.info('Service initialized', { component: 'Service' });
secureLogger.debug('Memory usage: 45.2%', { component: 'Service' });
secureLogger.warn('High memory detected', { component: 'Service' });
secureLogger.error('Service initialization failed', error, { component: 'Service' });

HomePage

secureLogger.info('Home page loaded', { component: 'HomePage' });
secureLogger.info('Prerequisites verified', { component: 'HomePage' });
secureLogger.warn('Already initializing, skipping', { component: 'HomePage' });
secureLogger.error('Page initialization failed', error, { component: 'HomePage' });

PairingPage

secureLogger.info('Pairing page loaded', { component: 'PairingPage' });
secureLogger.info('Pairing process started', { component: 'PairingPage' });
secureLogger.warn('Pairing already in progress', { component: 'PairingPage' });
secureLogger.error('Pairing failed', error, { component: 'PairingPage' });

Outils de correction

Un script automatique est disponible pour corriger les logs existants :

node fix-logs.cjs

Ce script :

• Remplace console.* par secureLogger.*
• Ajoute les imports nécessaires
• Détermine automatiquement les niveaux appropriés
• Ajoute le contexte de composant

Vérification

Pour vérifier que tous les logs utilisent le système centralisé :

grep -r "console\.\(log\|info\|warn\|error\|debug\)" src/

Cette commande ne devrait retourner aucun résultat si tous les logs sont correctement migrés.