📘 Documentation du module xcraft-core-journal

Aperçu

Le module xcraft-core-journal est un système de journalisation avancé pour le framework Xcraft qui gère l'écriture persistante des logs dans des fichiers rotatifs. Il capture automatiquement tous les messages de log émis par le système de logging Xcraft et les sauvegarde dans des fichiers compressés avec rotation automatique.

Sommaire

• Structure du module
• Fonctionnement global
• Exemples d'utilisation
• Interactions avec d'autres modules
• Variables d'environnement
• Détails des sources

Structure du module

Le module est composé d'une classe principale Journal qui :

• S'abonne aux événements de logging du système Xcraft
• Gère la création et la rotation des fichiers de log
• Utilise rotating-file-stream pour la gestion avancée des fichiers
• Maintient un registre global des streams de fichiers par processus

Fonctionnement global

Le journal fonctionne selon le principe suivant :

1. Initialisation : À la création, le journal s'abonne à tous les niveaux de log disponibles dans le système Xcraft
2. Capture : Chaque message de log émis déclenche automatiquement l'écriture dans le fichier correspondant
3. Rotation : Les fichiers sont automatiquement rotés selon la taille (1MB) et l'intervalle (1 jour)
4. Compression : Les anciens fichiers sont compressés en gzip pour économiser l'espace
5. Rétention : Un maximum de 50 fichiers est conservé avant suppression automatique

Le système utilise un pattern singleton par processus pour éviter les conflits d'écriture sur les mêmes fichiers. L'identification des processus se base sur le nom du fichier principal (require.main?.filename) avec un fallback sur 'host' pour les environnements Electron > 27 où ESM est utilisé par défaut.

Exemples d'utilisation

Initialisation du journal

const xLog = require('xcraft-core-log')('myModule');
const xJournal = require('xcraft-core-journal')(xLog);

// Le journal capture automatiquement tous les logs
xLog.info("Message d'information");
xLog.warn("Message d'avertissement");
xLog.err("Message d'erreur");

Structure des fichiers générés

var/log/xcraft/
├── xcraft.host.log                       # Fichier actuel
├── 20250613-0936-01-xcraft.host.log.gz   # Rotation précédente
├── 20250613-0936-02-xcraft.host.log.gz   # Plus ancienne
├── 20250613-0824-01-xcraft.host.log.gz   # Plus ancienne
└── ...

Format des messages dans les fichiers

2024-01-15T10:30:45.123Z [myModule] info: Application démarrée
2024-01-15T10:30:46.456Z [database] warn: Connexion lente détectée
2024-01-15T10:30:47.789Z [auth] err: Échec d'authentification pour user123

Interactions avec d'autres modules

Le module interagit étroitement avec :

• xcraft-core-etc : Pour la configuration et la localisation du répertoire de logs
• xcraft-core-log : Pour l'écoute des événements de logging
• rotating-file-stream : Pour la gestion avancée des fichiers rotatifs

Variables d'environnement

| Variable | Description | Exemple | Valeur par défaut | | ------------ | ---------------------------------------------- | ------------- | -------------------------- | | xcraftRoot | Répertoire racine Xcraft (via xcraft-core-etc) | /opt/xcraft | Dépend de la configuration |

Détails des sources

lib/index.js

Ce fichier contient la classe principale Journal qui implémente le système de journalisation persistante.

Fonctionnalités principales

• Gestion des streams globaux : Utilise un objet streams global pour éviter la duplication des flux de fichiers par processus
• Auto-abonnement : S'abonne automatiquement à tous les niveaux de log disponibles
• Identification des processus : Utilise le nom du fichier principal pour identifier chaque processus avec fallback pour Electron
• Gestion d'erreurs robuste : Évite les boucles infinies (effet Larsen) en utilisant console.error pour les erreurs internes

Configuration de la rotation

• Taille maximale : 1MB par fichier
• Intervalle : Rotation quotidienne
• Rétention : 50 fichiers maximum
• Compression : gzip pour les fichiers archivés
• Répertoire : {xcraftRoot}/var/log/xcraft/

Méthodes publiques

• log(mode, msg) — Écrit un message de log dans le fichier rotatif avec le format standardisé incluant timestamp, module source, niveau et message.

Gestion des erreurs

Le module implémente une gestion d'erreurs défensive :

• Les erreurs de création de stream suppriment l'entrée du registre global
• Les erreurs d'écriture sont loggées via console.error pour éviter les boucles
• Les exceptions sont capturées pour maintenir la stabilité du système
• Protection contre l'effet Larsen en évitant d'utiliser xLog pour les erreurs internes

Particularités techniques

Le module gère spécifiquement le cas d'Electron version 27+ où ESM est utilisé par défaut, ce qui peut affecter la disponibilité de require.main.filename. Dans ce cas, un fallback sur 'host' est utilisé pour l'identification du processus.

Ce document a été mis à jour pour refléter l'état actuel du code source.