📝docs(docs): add documentation for README.md
add documentation in README.md, usage.md, architecture.md, update python version based on the version used in development
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
# 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) |
|
||||
+142
@@ -0,0 +1,142 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## Entrées
|
||||
|
||||
### Analyser un fichier de logs
|
||||
|
||||
```bash
|
||||
logwatcher --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 :
|
||||
|
||||
```bash
|
||||
logwatcher --input-files fichier1.txt --input-files fichier2.txt
|
||||
```
|
||||
|
||||
### Analyser tous les logs d'un répertoire
|
||||
|
||||
```bash
|
||||
logwatcher --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. 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` :
|
||||
|
||||
```bash
|
||||
logwatcher --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 :
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--output-dir` : Répertoire de sortie des rapports. Par défaut : `output/`.
|
||||
```bash
|
||||
logwatcher --input-dir logs/ --output-dir rapports/2026-09-01/
|
||||
```
|
||||
|
||||
- `--version` : Affiche la version du package et quitte.
|
||||
```bash
|
||||
logwatcher --version
|
||||
# logwatcher version: 0.0.1
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
## Exemple complet
|
||||
|
||||
Analyser tous les logs d'un répertoire et écrire les rapports dans un
|
||||
dossier dédié :
|
||||
```bash
|
||||
logwatcher --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/` :
|
||||
```text
|
||||
all.log # toutes les erreurs
|
||||
n2.log # erreurs pertinentes pour le N2
|
||||
other.log # erreurs hors périmètre N2
|
||||
```
|
||||
|
||||
Le rapport `n2.log` peut ensuite être transmis aux techniciens N2, et
|
||||
`other.log` aux équipes concernées par les autres erreurs.
|
||||
Reference in New Issue
Block a user