docs(docs): 📝 update documentation files
update ruff and pyproject.toml. Sync or reinstall the package
This commit is contained in:
+100
-16
@@ -7,14 +7,34 @@ Logwatcher analyse les comptes-rendus de suivi d'imports NOSYMAG (fichiers
|
||||
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
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
logwatcher --input-files chemin/vers/CR_fichier.txt
|
||||
logwatcher from-files --input-files chemin/vers/CR_fichier.txt
|
||||
```
|
||||
|
||||
### Analyser plusieurs fichiers de logs
|
||||
@@ -22,21 +42,22 @@ 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
|
||||
logwatcher from-files --input-files fichier1.txt --input-files fichier2.txt
|
||||
```
|
||||
|
||||
### Analyser tous les logs d'un répertoire
|
||||
|
||||
```bash
|
||||
logwatcher --input-dir chemin/vers/dossier
|
||||
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. Fournir
|
||||
les deux options lève une erreur et le traitement est interrompu. Ne fournir
|
||||
> `--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
|
||||
@@ -47,7 +68,7 @@ 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
|
||||
logwatcher from-files --input-dir chemin/vers/dossier --output-dir chemin/vers/sortie
|
||||
```
|
||||
|
||||
### Les rapports générés
|
||||
@@ -85,19 +106,56 @@ Nombre d'erreurs : 2
|
||||
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
|
||||
|
||||
- `--output-dir` : Répertoire de sortie des rapports. Par défaut : `output/`.
|
||||
### 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.
|
||||
|
||||
```bash
|
||||
logwatcher --input-dir logs/ --output-dir rapports/2026-09-01/
|
||||
logwatcher version: 1.0.1
|
||||
```
|
||||
|
||||
- `--version` : Affiche la version du package et quitte.
|
||||
### Options de `from-files` et `from-mails`
|
||||
- `--output-dir` répertoire de sortie des rapports. Par défaut : `output/`.
|
||||
|
||||
Exemple :
|
||||
```bash
|
||||
logwatcher --version
|
||||
# logwatcher version: 0.0.1
|
||||
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
|
||||
@@ -118,17 +176,34 @@ 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
|
||||
### 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
|
||||
- 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/
|
||||
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/` :
|
||||
@@ -138,5 +213,14 @@ 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.
|
||||
La commande n'envoie rien ; le rapport `n2.log` est transmis manuellement.
|
||||
|
||||
|
||||
- Depuis la boîte mail :
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user