163 lines
6.9 KiB
Markdown
163 lines
6.9 KiB
Markdown
<!-- file: deltas/0.1.2/pre.001-fix.001.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.1.2-pre.001-fix.001
|
|
|
|
## Base requise
|
|
|
|
Livraison précédente :
|
|
|
|
```text
|
|
0.1.2-pre.001
|
|
```
|
|
|
|
Ce correctif est documentaire et corrige le plan de `pre.001` sans réécrire son delta historique.
|
|
|
|
## Objectif
|
|
|
|
Corriger le cadrage Logging avant validation du plan afin de fixer :
|
|
|
|
- le takeover complet du logging/tracing KSP par `ksp-logging-lib` ;
|
|
- le target KSP explicite égal au nom Cargo de la crate propriétaire ;
|
|
- le silence par défaut des targets tiers et la réémission explicite des informations utiles par le composant KSP propriétaire ;
|
|
- console et fichier non bloquants avec guards et compteurs de lignes abandonnées ;
|
|
- le stripping ANSI des fichiers ;
|
|
- un `initialize` global unique suivi d'un hot reload via `reinitialize` sans second subscriber global ;
|
|
- une surface de spans KSP synchrones et async avec diagnostic de durée `NEW/CLOSE`, `busy` et `idle` ;
|
|
- la responsabilité des données loggées au caller, sans détection/redaction automatique par Logging.
|
|
|
|
Aucun développement fonctionnel de `ksp-logging-lib` n'est introduit par ce fix.
|
|
|
|
## Décisions prises
|
|
|
|
### Takeover tracing
|
|
|
|
`ksp-logging-lib` devient le seul propriétaire KSP direct de la stack tracing et la seule façade autorisée pour les événements/spans KSP.
|
|
|
|
Le subscriber applique une politique de takeover :
|
|
|
|
```text
|
|
external targets = Off by default
|
|
ksp-* targets = configured KSP default
|
|
specific ksp-* = optional override
|
|
```
|
|
|
|
KSP ne renomme pas un événement tiers. Lorsqu'un détail provenant d'une dépendance externe est utile, la crate KSP propriétaire le réémet sous son propre target.
|
|
|
|
Exemple attendu pour Store : les logs SQLx natifs sont désactivés/silencieux ; les opérations SQL utiles sont journalisées explicitement par `ksp-store-lib`, typiquement au niveau `trace`.
|
|
|
|
### Targets
|
|
|
|
Les macros événements et spans exigent un target explicite correspondant au nom Cargo de la crate propriétaire. `domain`, `component` et autres fields restent des subdivisions structurées, pas des remplacements du target.
|
|
|
|
### Settings runtime
|
|
|
|
`LoggingSettings` reste propriétaire de Logging et indépendant de Config. Il couvre niveau KSP default, overrides de target, sorties console/fichier et politique d'événements de spans.
|
|
|
|
Une future `ksp-config-lib` pourra construire ces settings puis appeler la façade Logging.
|
|
|
|
### Non-blocking
|
|
|
|
Console et fichier utilisent des writers non bloquants avec leurs `WorkerGuard` possédés par `LoggingGuard`.
|
|
|
|
Le mode retenu privilégie l'absence de backpressure sur le hot path : une saturation peut abandonner des lignes. Les `ErrorCounter` sont conservés afin que ces pertes restent observables.
|
|
|
|
### Stripping ANSI
|
|
|
|
Les fichiers passent par un stripping ANSI générique avant persistence. Logging ne dépend pas de Tauri ; cette protection évite seulement de persister des séquences de terminal déjà présentes dans les données écrites.
|
|
|
|
### Initialisation et hot reload
|
|
|
|
`initialize(settings)` installe le subscriber global une seule fois et retourne `LoggingGuard`.
|
|
|
|
Après succès, `reinitialize(&mut guard, settings)` ou une méthode équivalente peut être appelée 0..N fois. Elle ne réinstalle pas le subscriber global ; elle modifie les filters/layers/sinks de l'infrastructure déjà installée.
|
|
|
|
Le reload vise une sémantique transactionnelle : une nouvelle configuration invalide ou impossible à construire laisse l'ancienne configuration active.
|
|
|
|
Le mécanisme interne exact (`tracing_subscriber::reload` ciblé ou routing KSP dynamique) sera choisi par implémentation/tests selon correction et overhead, sans modifier le contrat public.
|
|
|
|
### Spans sync/async et durée
|
|
|
|
`0.1.2` inclut désormais une surface de spans KSP par niveau, sans dépendance directe `tracing` dans les crates consommatrices.
|
|
|
|
Le code sync doit pouvoir exécuter un scope dans un span. Le code async doit instrumenter la `Future` elle-même et ne pas maintenir un enter guard à travers `.await`.
|
|
|
|
Les settings permettent au minimum `Off` et `NewAndClose`; `NEW | CLOSE` fournit des repères de début/fin et, lorsque les timestamps sont actifs, le close fournit `busy`/`idle`. Cette capacité sert au diagnostic rapide de latence/blocage et n'est pas présentée comme un benchmark de précision absolue.
|
|
|
|
### Contenu sensible
|
|
|
|
`ksp-logging-lib` n'essaie pas de détecter ou redacter automatiquement les données sensibles. La crate appelante est responsable du contenu qu'elle choisit de logger.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
- `deltas/0.1.2/pre.001-fix.001.md`
|
|
|
|
## Fichiers modifiés
|
|
|
|
- `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`
|
|
- `docs/rules/RULES_DEPENDENCIES.md`
|
|
- `docs/architecture/003-COMPONENT_CONTRACTS.md`
|
|
- `docs/architecture/005-DEPENDENCY_GRAPH.md`
|
|
|
|
## Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## Version Cargo
|
|
|
|
Aucune modification de `Cargo.toml`.
|
|
|
|
Ce fix est limité à la documentation et respecte `VER-ID-008` : `workspace.package.version` reste donc :
|
|
|
|
```text
|
|
0.1.2-pre.1
|
|
```
|
|
|
|
L'identifiant de livraison est :
|
|
|
|
```text
|
|
0.1.2-pre.001-fix.001
|
|
```
|
|
|
|
## Validations exécutées
|
|
|
|
- vérification du delta `pre.001` fourni et des règles de version/delta/archive de la base `0.1.1` ;
|
|
- vérification de la documentation officielle `tracing` indiquant que le subscriber global ne peut être installé qu'une fois ;
|
|
- vérification de `tracing-subscriber::reload` pour le remplacement runtime d'une Layer/Filter ;
|
|
- vérification de l'avertissement officiel contre `Span::enter()` conservé à travers `.await` ;
|
|
- vérification de l'instrumentation de `Future` fournie par `tracing::Instrument` ;
|
|
- vérification de `FmtSpan::NEW | FmtSpan::CLOSE` et des champs `busy`/`idle` au close lorsque les timestamps sont actifs ;
|
|
- vérification du writer non bloquant, de `WorkerGuard` et `ErrorCounter` dans `tracing-appender 0.2.5` ;
|
|
- contrôle des headers `file:` / `version:` des fichiers livrés ;
|
|
- contrôle de l'absence de modification Cargo dans ce fix documentaire ;
|
|
- contrôle du contenu de l'archive selon `VER-ARCHIVE-004`.
|
|
|
|
## Validations non exécutées
|
|
|
|
Aucune validation Cargo n'est applicable à ce correctif documentaire et aucun code fonctionnel Logging n'existe encore dans la livraison.
|
|
|
|
Les commandes suivantes restent à exécuter dès que les tranches de développement les rendent applicables :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check --workspace
|
|
cargo test --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo tree -p ksp-logging-lib
|
|
cargo tree -p ksp-logging-lib -d
|
|
cargo tree -p ksp-logging-lib -e features
|
|
```
|
|
|
|
## Questions ouvertes
|
|
|
|
Aucune question architecturale bloquante.
|
|
|
|
Restent à trancher par implémentation/tests dans les prereleases suivantes :
|
|
|
|
- mécanisme exact des macros spans/events préservant le callsite sans fuite de types `tracing` ;
|
|
- abstraction KSP exacte pour instrumenter les futures async ;
|
|
- composition reloadable interne la moins coûteuse ;
|
|
- API exacte d'observation des dropped lines.
|
|
|
|
Après validation de ce fix, la prochaine tranche reste `0.1.2-pre.002`.
|