📘 xcraft-core-log

Aperçu

Le module xcraft-core-log est le système de journalisation central du framework Xcraft. Il fournit une interface unifiée pour la gestion des logs avec support de différents niveaux de verbosité, filtrage par modules, coloration syntaxique, et intégration avec les systèmes de bus et de journalisation persistante de Xcraft.

Sommaire

- Structure du module
- Fonctionnement global
- Exemples d'utilisation
- Interactions avec d'autres modules
- Configuration avancée
- Détails des sources

Structure du module

Le module est organisé autour de plusieurs composants principaux :

- Logger principal (lib/index.js) : Classe Log qui gère l'affichage et la distribution des messages
- Interface bus (buslog.js) : Commandes exposées sur le bus Xcraft pour contrôler le logging à distance
- Configuration (config.js) : Options configurables via xcraft-core-etc

Le système supporte 5 niveaux de log : verb (0), info (1), warn (2), err (3), et dbg (4).

Fonctionnement global

Le logger fonctionne selon un modèle d'événements où chaque instance de Log :

1. Filtre les messages selon le niveau de verbosité et les modules autorisés
2. Formate les messages avec coloration, horodatage et identification du module
3. Distribue les logs vers différentes sorties :
- Console standard (stdout/stderr)
- Bus Xcraft ([xcraft-core-buslog]) pour la supervision
- Journal persistant ([xcraft-core-journal]) pour l'archivage

Le système détecte automatiquement le module appelant en analysant la pile d'appels et peut filtrer les logs par nom de module. La détection se base sur le pattern xcraft-[type]-[nom] dans le chemin du fichier.

Exemples d'utilisation

$3

``javascript
const xLog = require('xcraft-core-log')('mon-module');

// Différents niveaux de log
xLog.verb('Message de débogage détaillé');
xLog.info('Information générale');
xLog.warn('Avertissement important');
xLog.err('Erreur critique');
xLog.dbg('Debug technique');

// Vérification du niveau avant log coûteux
if (xLog.isVerb()) {
xLog.verb('Calcul complexe: %j', calculComplexe());
}
`

$3

`javascript
const data = [
{nom: 'Alice', age: 30, ville: 'Paris'},
{nom: 'Bob', age: 25, ville: 'Lyon'},
];

xLog.info.table(data);
// Affiche un tableau formaté avec bordures ASCII
`

$3

`javascript
const xLog = require('xcraft-core-log')('mon-module');

// Verbosité locale (ne s'applique qu'à cette instance)
xLog.setVerbosity(2, true); // Seuls warn et err seront affichés

// Désactiver la décoration pour cette instance
xLog.setDecorate(false, true);
`

$3

`javascript
const errorWithContext = {
_xcraftOverwatch: true,
err: 'Erreur dans le traitement',
goblin: {
id: 'user-123',
goblin: 'user',
quest: 'updateProfile',
callerGoblin: 'desktop',
callerQuest: 'handleUserAction',
},
};

xLog.err(errorWithContext);
// Affiche l'erreur avec la pile d'appels Goblin complète
`

$3

`javascript
// Depuis un autre module via le bus
await this.quest.cmd('buslog.enable', {modes: ['event', 'overwatch']});
await this.quest.cmd('buslog.verbosity', {level: 1});
await this.quest.cmd('buslog.modulenames', {modulenames: ['user', 'desktop']});
`

Interactions avec d'autres modules

$3

Le module s'intègre automatiquement avec [xcraft-core-buslog] pour :

- Transmettre les logs via le bus Xcraft
- Supporter les modes de supervision (event, overwatch)
- Permettre le contrôle à distance du logging
- Afficher des barres de progression

$3

Intégration optionnelle pour la persistance des logs :

- Sauvegarde automatique des logs en fichier
- Configuration via journalize: true
- Chargement différé du module journal

$3

Utilise le système de configuration pour :

- Charger les paramètres de logging au démarrage
- Appliquer les modes et filtres configurés
- Gérer la configuration interactive

$3

Récupère automatiquement :

- L'identifiant d'application (appId)
- Le nom de la tribu pour les commandes spécialisées
- Gestion gracieuse si le module n'est pas disponible

Configuration avancée

| Option | Description | Type | Valeur par défaut |
| ------------ | ---------------------------------------- | --------- | ----------------- |
| journalize | Active la sauvegarde des logs en fichier | boolean | false |
| modes | Modes buslog à activer au démarrage | array | [] |

Détails des sources

$3

Le fichier principal expose une factory qui crée des instances de logger pour chaque module. La classe Log hérite d'EventEmitter et fournit un système de logging complet avec détection automatique du module appelant.

#### État et modèle de données

Chaque instance de Log maintient :

- _moduleName : Nom du module propriétaire
- _currentLevel : Niveau de verbosité local (-1 = utilise le niveau global)
- _currentDecorate : Activation locale de la décoration (null = utilise le paramètre global)
- _busLog : Instance du logger bus (chargement différé)
- _journal : Instance du journal persistant (chargement différé)
- _resp : Objet de réponse pour les commandes bus

Variables globales :

- currentModulesNames : Liste des modules autorisés pour le filtrage
- currentLevel : Niveau de verbosité global (0-3)
- currentUseColor : Activation de la coloration syntaxique
- currentUseDatetime : Activation de l'horodatage
- currentDecorate : Activation de la décoration des messages

#### Méthodes publiques

- verb(format, ...args) — Log de niveau verbose (0), pour les détails de débogage. Supporte également verb.table(data) pour l'affichage tabulaire.
- info(format, ...args) — Log informatif (1), pour les messages généraux. Supporte également info.table(data) pour l'affichage tabulaire.
- warn(format, ...args) — Log d'avertissement (2), pour les situations suspectes. Supporte également warn.table(data) pour l'affichage tabulaire.
- err(format, ...args) — Log d'erreur (3), pour les erreurs critiques. Supporte également err.table(data) pour l'affichage tabulaire.
- dbg(format, ...args) — Log de debug (4), pour le débogage technique. Supporte également dbg.table(data) pour l'affichage tabulaire.
- isVerb(), isInfo(), isWarn(), isErr() — Teste si le niveau correspondant est actif
- progress(topic, position, length) — Affiche une barre de progression via buslog
- setVerbosity(level, onlyLocal) — Définit le niveau de verbosité (0-3)
- setDecorate(decorate, onlyLocal) — Active/désactive la décoration des messages
- setResponse(resp) — Définit l'objet de réponse pour les commandes bus
- color(useColor) — Active/désactive la coloration syntaxique globalement
- datetime(useDatetime) — Active/désactive l'horodatage globalement
- getModule() — Retourne le nom complet du module avec détection automatique du fichier appelant
- getLevels() — Retourne la liste des niveaux disponibles en minuscules
- getModuleName() — Retourne le nom du module configuré

#### Méthodes statiques du module

- setEnable(enable, modes) — Active/désactive le buslog avec modes optionnels
- setModuleNames(moduleNames) — Configure le filtrage global par noms de modules
- setGlobalVerbosity(level) — Définit le niveau de verbosité global

$3

Interface de commandes exposées sur le bus Xcraft pour contrôler le logging à distance. Le module génère automatiquement des commandes génériques et spécialisées par application.

#### Méthodes publiques

- enable(modes) — Active le buslog avec les modes spécifiés (optionnel)
- disable(modes) — Désactive le buslog pour les modes spécifiés (optionnel)
- modulenames(modulenames) — Configure le filtrage par noms de modules
- verbosity(level) — Définit le niveau de verbosité global (requis)

Chaque commande existe en version générique (buslog.enable) et spécialisée par application (${appId}${tribe}.enable`). Toutes les commandes supportent l'exécution en parallèle et envoient un événement de fin d'exécution.

---

_Ce document a été mis à jour pour refléter la structure actuelle du module._

[xcraft-core-buslog]: https://github.com/Xcraft-Inc/xcraft-core-buslog
[xcraft-core-journal]: https://github.com/Xcraft-Inc/xcraft-core-journal
[xcraft-core-etc]: https://github.com/Xcraft-Inc/xcraft-core-etc