maurane
bfa5fa600b
add documentation in README.md, usage.md, architecture.md, update python version based on the version used in development
106 lines
3.7 KiB
Markdown
106 lines
3.7 KiB
Markdown
# 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 :
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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) |
|