logwatcher/docs/architecture.md

Architecture

Vue d'ensemble

Logwatcher est un outil en ligne de commande Python qui analyse des fichiers de logs LAME MDC, identifie les erreurs pertinentes pour le support N2, et génère des rapports texte.

Le traitement suit un pipeline linéaire :

fichiers de logs
      │
      ▼
  parser.py       lit et parse les fichiers en LogEntry
      │
      ▼
  classifier.py   classe chaque entrée : N2 ou hors N2
      │
      ▼
  reporter.py     génère les trois rapports (all, n2, other)
      │
      ▼
  rapports .log

Structure du package

src/logwatcher/
├── __init__.py          # expose __version__
├── __main__.py          # point d'entrée : python -m logwatcher
├── cli.py               # interface en ligne de commande (Typer)
├── config.py            # constantes : chemins, formats
├── logging_config.py    # configuration du logging
├── models.py            # LogEntry : structure de données
├── parser.py            # lecture et parsing des fichiers
├── classifier.py        # classification N2 / hors N2
└── reporter.py          # génération des rapports texte

Modules

cli.py — point d'entrée

• Définit app = typer.Typer() et la commande principale.
• Valide les arguments (--input-files / --input-dir mutuellement exclusifs).
• Orchestre le pipeline : parsing → classification → rapports.
• Gère les erreurs utilisateur (BadParameter, code de sortie 2) et
• les erreurs d'exécution (code de sortie 1).
• Expose --version (eager, affiche et quitte).

models.py — LogEntry

Dataclass immuable (par convention) représentant une ligne de log parsée.

Champs principaux :

• server_ip, mdc_server_name : origine du log
• store_name : magasin concerné
• start_time, error_time : horodatages
• error_message : message d'erreur complet
• error_name : nom du pattern N2 correspondant (rempli par le classifier)
• raw_line : ligne brute d'origine
• ligne : numéro de ligne dans le fichier source

LogEntry est créée uniquement par le parser. Le classifier l'enrichit (remplit error_name). Le modèle lui-même ne contient pas de logique métier. parser.py — lecture et parsing

• LOG_PATTERN : expression régulière du format d'une ligne LAME MDC.
• parse_log_file() : lit un fichier, retourne list[LogEntry].
• Les lignes non conformes (système, en-têtes, corrompues) sont ignorées silencieusement.

classifier.py — classification

• N2_PATTERNS : dictionnaire des motifs d'erreurs pertinents pour le N2, fournis par les techniciens.
• classify_log_entries() : sépare les entrées en deux listes (relevant, irrelevant) et remplit entry.error_name pour les entrées pertinentes.

reporter.py — rapports

• Templates texte (string.Template) : BASE_TEMPLATE, N2_SUPPORT_TEMPLATE, OTHER_TEMPLATE, ERROR_TEMPLATE.
• build_reports() : construit les trois rapports (dict n2, other, all).
• write_log_report() : écrit les rapports sur disque en Windows-1252.
• _get_period() : calcule les bornes min/max des error_time.

logging_config.py — logging

• setup_logging() : configure le logger racine.
• Handler console (INFO, ou DEBUG si verbose) + handler fichier.
• Le fichier de log logwatcher.log est horodaté et écrit dans le dossier de sortie.

config.py — constantes

• Chemins (OUTPUT_PATH, FIXTURE_PATH ...).
• Formats de date (DATETIME_FORMAT).

Dépendances

Package	Rôle
typer	Interface en ligne de commande
pytest	Tests (dev)
pytest-cov	Couverture (dev)
ruff	Linting/formatage (dev)
mypy	Typage statique (dev)