logwatcher/docs/usage.md

Guide d'utilisation

Introduction

Logwatcher analyse les comptes-rendus de suivi d'imports NOSYMAG (fichiers CR_*.txt et autres logs LAME MDC) pour identifier les erreurs pertinentes pour le support N2. Il génère trois rapports : un pour les erreurs N2, un pour les erreurs hors périmètre N2, et un rapport complet.

Deux modes d'entrée sont disponibles : l'analyse de fichiers locaux, et l'analyse des compte-rendus reçus par correspondance dans une boîte Exchange.

---

Entrées

Analyser les compte-rendus reçus par mail

logwatcher from-mails --output-dir chemin/vers/sortie 

Les mails sont lus dans le dossier Logs de la boîte (les compte-rendus y sont déplacés par une règle automatique). Les logs sont extraits du corps du message, ou de la pièce jointe CR_* lorsque le corps indique que le compte-rendu dépasse 100 lignes.

Après traitement, les mails sont déplacés dans le sous-dossier Logs/Analyzed et ne seront pas relus. Le dossier Analyzed est créé automatiquement au premier passage s'il n'existe pas. Les trois rapports sont écrits sur disque. Le rapport n2.log est envoyé automatiquement aux destinataires définis dans N2_REPORT_RECIPIENTS (variable du fichier .env). Une copie du mail envoyé est conservée dans le dossier Logs/Sent.

Analyser un fichier de logs

logwatcher from-files --input-files chemin/vers/CR_fichier.txt

Analyser plusieurs fichiers de logs

L'option --input-files accepte plusieurs fichiers. Répéter l'option pour chaque fichier :

logwatcher from-files --input-files fichier1.txt --input-files fichier2.txt

Analyser tous les logs d'un répertoire

logwatcher from-files --input-dir chemin/vers/dossier

L'option --input-dir analyse tous les fichiers .log, .txt ou sans extension contenus dans le répertoire. Les autres fichiers sont ignorés.

Règle d'exclusivité

--input-files et --input-dir sont mutuellement exclusifs et ne concernent que la commande from-files. Il n'y a pas de règle équivalente pour from-mails. Fournir les deux options lève une erreur et le traitement est interrompu. Ne fournir aucune des deux lève également une erreur.

Sorties

Emplacement des rapports

Par défaut, les rapports sont écrits dans le répertoire output/ du dossier courant. Un autre emplacement peut être fourni avec --output-dir :

logwatcher from-files --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie

Les rapports générés

Chaque analyse produit trois rapports différents : all.log, n2.log et other.log.

• all.log : Toutes les erreurs analysées, N2 et hors N2.
• n2.log : Uniquement les erreurs pertinentes pour le support N2.
• other.log : Uniquement les erreurs hors périmètre N2

Contenu d'un rapport

Chaque rapport contient un en-tête avec la période analysée, le nombre de fichiers lus et le nombre total d'erreurs, suivi du détail des erreurs. Un rapport se présente ainsi :

RAPPORT D'ANALYSE DE LOGS
=========================
Période	 : 01/09/2026 11:07:53 -> 01/09/2026 15:04:18
Fichier(s) lu(s)	 : 1
Nombre total d'erreur(s)	: 3

=================================
ERREURS SUPPORT N2
=================================
Nombre d'erreurs	 : 2

[1] BL_AUTO_BESTSELLER_REJECTED
    Magasin: DUMAS-DELAGE
    MDC: MDC_340
    Serveur: 192.168.13.23
    Heure: 28/07/2026 08:05:27
    Raison: Erreur : 1099_2622609667_DESADV : / 00098/000 ... ne correspond

Pour la commande from-mails, la ligne "Fichier(s) lu(s)" devient "Mail(s) lu(s)". Le reste de l'en-tête est identique. Ce libellé est déterminé par le type de source (fichiers ou mails).

Options

Options communes à toutes les commandes

• --verbose, -v affiche les logs DEBUG sur la sortie standard. Sans cette option, seuls les avertissements et erreurs sont affichés. Le fichier de log contient toujours le niveau DEBUG.

• --version affiche la version du package et quitte.

logwatcher version: 1.0.1

Options de from-files et from-mails

• --output-dir répertoire de sortie des rapports. Par défaut : output/.

Exemple :

logwatcher from-files --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie

Options de from-files uniquement

• --input-files fichiers de logs à analyser.
• --input-dir répertoire contenant les fichiers de logs

---

Automatisation sous Windows

Le flux mail est destiné à être déclenché automatiquement par le Planificateur de tâches Windows, après réception des compte-rendus du créneau.

• Réglages de la tâche Déclencheur : tous les jours à 07h20, répété toutes les 4 heures pendant 1 jour

• Action : ....venv\Scripts\logwatcher.exe

• Arguments : from-mails --output-dir ...\results

• Commencer dans : répertoire du projet

• Sécurité : "N'exécuter que si un utilisateur a ouvert une session"

Le mode "uniquement si un utilisateur a ouvert une session" est nécessaire lorsque le compte d'exécution ne dispose pas du droit "Ouvrir une session en tant que tâche" (SeBatchLogonRight).

Sur une machine de production, ce droit doit être accordé à un compte de service, afin que la tâche puisse s'exécuter sans session ouverte. Conséquence de ce mode : la tâche ne se déclenche pas si aucune session n'est ouverte. Les créneaux de 07h20 à 19h20 tombent dans la journée de travail ; le créneau de 03h20 ne se déclenchera pas.

Cas particuliers

Fichier vide

Un fichier vide est lu sans erreur. Les trois rapports sont générés avec Nombre total d'erreur(s) : 0.

Répertoire vide

Un répertoire vide est traité sans erreur. Les trois rapports sont générés avec Fichier(s) lu(s) : 0 et Nombre total d'erreur(s) : 0.

Logs non reconnus

Les lignes qui ne correspondent pas au format LAME MDC (lignes système, en-têtes de répertoire, lignes corrompues) sont ignorées silencieusement et ne produisent pas d'entrée dans les rapports.

Mail en retard

Si un compte-rendu arrive après le passage du Planificateur, il reste dans le dossier Logs et sera traité au créneau suivant. Le rapport indique alors le nombre de mails effectivement lus, sans signaler l'absence.

Mails déjà traités

Les mails traités sont déplacés dans Logs/Analyzed et ne sont pas relus. Le dossier Analyzed est créé automatiquement au premier passage s'il n'existe pas.

Mail sans logs exploitables

Un mail qui ne contient ni logs dans le corps ni pièce jointe CR_* est ignoré, avec un avertissement dans le log applicatif. Il en va de même si le corps annonce une pièce jointe mais qu'aucune n'est trouvée. Les autres mails du dossier sont traités normalement.

Échec de l'envoi du rapport

L'envoi du mail a lieu avant le déplacement des mails vers Analyzed. Si l'envoi échoue, les mails restent dans Logs : le rapport sera régénéré et renvoyé au prochain passage. Un rapport peut donc être envoyé deux fois en cas d'échec après envoi, mais jamais perdu.

Encodage des fichiers

Les fichiers d'entrée sont lus en Windows-1252 (encodage natif des logs LAME MDC). Les rapports générés sont également écrits en Windows-1252. Le corps des mails et le contenu des pièces jointes CR_* sont également lus en windows-1252.

Exemple complet

• Analyser tous les logs d'un répertoire et écrire les rapports dans un dossier dédié :

logwatcher from-files --input-dir logs/2026-09-01/ --output-dir rapports/2026-09-01/

Après exécution, les fichiers suivants sont créés dans rapports/2026-09-01/ :

all.log      # toutes les erreurs
n2.log       # erreurs pertinentes pour le N2
other.log    # erreurs hors périmètre N2

La commande n'envoie rien ; le rapport n2.log est transmis manuellement.

• Depuis la boîte mail :

logwatcher from-mails --output-dir rapports/2026-09-01/

Les trois rapports sont créés dans rapports/2026-09-01/. Le rapport n2.log est envoyé aux destinataires définis dans N2_REPORT_RECIPIENTS, et une copie du mail est conservée dans Logs/Sent. Les mails traités sont déplacés dans Logs/Analyzed.

le rapport n2.log est transmis automatiquement aux techniciens N2.