174 lines
5.5 KiB
Markdown
174 lines
5.5 KiB
Markdown
<!-- file: deltas/0.1.2/pre.005.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.1.2-pre.005
|
|
|
|
## Identité
|
|
|
|
```text
|
|
0.1.2-pre.005 — intégration, concurrence, saturation et audits Logging
|
|
```
|
|
|
|
Version Cargo portée par ce delta :
|
|
|
|
```text
|
|
0.1.2-pre.5
|
|
```
|
|
|
|
## Base
|
|
|
|
Base directe : `0.1.2-pre.004-fix.004`, version Cargo `0.1.2-pre.4.fix.4`.
|
|
|
|
La validation utilisateur de cette base a exécuté avec succès :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test --workspace
|
|
```
|
|
|
|
Le test runtime global passe alors avec takeover des targets externes, console/fichier non bloquants, stripping ANSI, lifecycle des `WorkerGuard` et hot reload.
|
|
|
|
## Mission du delta
|
|
|
|
Cette tranche ne modifie pas la surface fonctionnelle publique de Logging. Elle durcit la fondation existante avant la validation finale :
|
|
|
|
- saturation déterministe des queues lossy ;
|
|
- émissions concurrentes pendant hot reload ;
|
|
- vérification des temps de lifecycle de spans ;
|
|
- audit automatique du takeover de dépendances ;
|
|
- documentation consommateur de la crate ;
|
|
- probe diagnostic de l'overhead du mécanisme reload.
|
|
|
|
## Changements Rust
|
|
|
|
### Construction non bloquante testable sans setting supplémentaire
|
|
|
|
`runtime.rs` centralise la construction du `NonBlockingBuilder` dans un helper privé utilisé par la production.
|
|
|
|
La politique reste :
|
|
|
|
```text
|
|
lossy = true
|
|
```
|
|
|
|
La taille de queue n'entre pas dans `LoggingSettings`. Le test unitaire peut cependant dériver le même builder avec `buffered_lines_limit(1)` afin de provoquer une saturation contrôlée.
|
|
|
|
### Saturation déterministe
|
|
|
|
Le test unitaire runtime introduit un writer qui bloque volontairement son worker sur la première écriture.
|
|
|
|
Une fois le worker bloqué :
|
|
|
|
1. la queue est limitée à une ligne ;
|
|
2. un producteur émet 1024 lignes supplémentaires ;
|
|
3. le producteur doit terminer sous timeout alors que le writer reste bloqué ;
|
|
4. le compteur `ErrorCounter::dropped_lines()` doit être strictement positif ;
|
|
5. le writer est ensuite libéré et le `WorkerGuard` peut terminer proprement.
|
|
|
|
Ce test distingue directement la politique lossy retenue d'une régression vers une queue exerçant de la backpressure.
|
|
|
|
### Concurrence pendant hot reload
|
|
|
|
Le test runtime global lance quatre threads qui émettent continuellement via `ksp_logging_lib::trace!` pendant que le thread possédant `LoggingGuard` effectue 32 `reinitialize()` successifs.
|
|
|
|
Les settings alternent entre :
|
|
|
|
- runtime sans sink ;
|
|
- console non bloquante présente avec niveau KSP `Off`.
|
|
|
|
Le test exerce donc le reload, la création/retrait de worker guards et la lecture concurrente du subscriber sans inonder stdout/stderr.
|
|
|
|
### Lifecycle des spans
|
|
|
|
Un nouveau test avec subscriber local vérifie que `FmtSpan::NEW | FmtSpan::CLOSE` produit pour un span KSP :
|
|
|
|
- l'identité du span ;
|
|
- l'événement `new` ;
|
|
- l'événement `close` ;
|
|
- `time.busy` ;
|
|
- `time.idle`.
|
|
|
|
### Audit de takeover
|
|
|
|
`tests/ownership.rs` parcourt les crates du workspace autres que `ksp-logging-lib` et rejette :
|
|
|
|
- une dépendance Cargo directe `tracing` ;
|
|
- une dépendance directe `tracing-subscriber` ;
|
|
- une dépendance directe `tracing-appender` ;
|
|
- les usages Rust directs `tracing::`, `tracing_subscriber::` ou `tracing_appender::`.
|
|
|
|
La crate Logging elle-même est explicitement exclue de cet audit car elle possède légitimement la stack.
|
|
|
|
## Documentation de crate
|
|
|
|
Ajouts :
|
|
|
|
```text
|
|
crates/ksp-logging-lib/README.md
|
|
crates/ksp-logging-lib/USAGE.md
|
|
crates/ksp-logging-lib/TODO.md
|
|
```
|
|
|
|
Ils documentent notamment :
|
|
|
|
- target = nom Cargo de la crate propriétaire ;
|
|
- champs structurés additionnels ;
|
|
- `initialize` puis `reinitialize` ;
|
|
- hot reload transactionnel ;
|
|
- spans sync/async ;
|
|
- dropped lines ;
|
|
- capacités explicitement différées.
|
|
|
|
## Probe d'overhead
|
|
|
|
`tests/overhead.rs` est ignoré par défaut car il s'agit d'un probe temporel diagnostic, pas d'un benchmark de précision.
|
|
|
|
Commande explicite :
|
|
|
|
```bash
|
|
cargo test -p ksp-logging-lib --test overhead -- --ignored --nocapture
|
|
```
|
|
|
|
Le probe compare un filtre local fixe au même filtre derrière `tracing_subscriber::reload::Layer` sur 200000 événements et n'échoue que si le coût reload dépasse un garde-fou volontairement très large. Le résultat sert à repérer une régression grossière ; il ne constitue pas une mesure HFT ni un engagement de performance absolue.
|
|
|
|
## Audit des dépendances
|
|
|
|
Aucune dépendance n'est ajoutée par `pre.005`.
|
|
|
|
Lors de `pre.004`, les commandes utilisateur ont observé :
|
|
|
|
```text
|
|
tracing 0.1.44
|
|
tracing-subscriber 0.3.23
|
|
tracing-appender 0.2.5
|
|
```
|
|
|
|
`cargo tree -p ksp-logging-lib -d` ne signalait aucun doublon. Le graphe de features n'activait pas via KSP `tracing-attributes`, `tracing-log`, `env-filter`, JSON/Serde ou le formatter ANSI. Ces commandes doivent être réexécutées sur `pre.005` avant validation finale de la tranche car une validation d'une base précédente ne vaut pas validation du delta courant.
|
|
|
|
## Validations à exécuter
|
|
|
|
Non exécutées dans l'environnement de génération :
|
|
|
|
```bash
|
|
cargo fmt --all
|
|
cargo check --workspace
|
|
cargo test --workspace
|
|
cargo clippy --workspace --all-targets
|
|
cargo test -p ksp-logging-lib --test overhead -- --ignored --nocapture
|
|
cargo tree -p ksp-logging-lib
|
|
cargo tree -p ksp-logging-lib -d
|
|
cargo tree -p ksp-logging-lib -e features
|
|
```
|
|
|
|
La base stable ne contient pas de répertoire `scripts/`; aucun script inexistant n'est déclaré réussi.
|
|
|
|
## Suite
|
|
|
|
Après validation de `pre.005`, la tranche prévue est :
|
|
|
|
```text
|
|
0.1.2-pre.006 — validation finale, documentation, cleanup et prompt 0.1.3
|
|
```
|