271 lines
9.0 KiB
Markdown
271 lines
9.0 KiB
Markdown
<!-- file: deltas/0.1.2/pre.002.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Delta 0.1.2-pre.002
|
|
|
|
## Base requise
|
|
|
|
Livraison précédente validée :
|
|
|
|
```text
|
|
0.1.2-pre.001-fix.001
|
|
```
|
|
|
|
Cette tranche applique le plan corrigé de `pre.001` et ouvre le développement fonctionnel de `ksp-logging-lib` sans encore installer le subscriber runtime.
|
|
|
|
## Objectif
|
|
|
|
Créer la première surface fonctionnelle de Logging :
|
|
|
|
- créer `crates/ksp-logging-lib` et l'ajouter au workspace ;
|
|
- dépendre de `ksp-core-lib` pour le contrat commun d'erreur ;
|
|
- ajouter uniquement `tracing` parmi les dépendances de la stack de logging ;
|
|
- définir les settings runtime propres à Logging, indépendants de Config ;
|
|
- exposer les cinq niveaux d'événements par macros KSP avec `target:` explicite ;
|
|
- exposer les cinq niveaux de spans KSP ;
|
|
- fournir une abstraction `Span` KSP pour les scopes synchrones ;
|
|
- fournir `instrument(span, future)` pour l'instrumentation async sans demander au consumer d'utiliser `tracing::Instrument` ;
|
|
- vérifier par tests la préservation du callsite événement/span et le cycle enter/exit d'une future instrumentée.
|
|
|
|
Le subscriber global, le takeover effectif, le filtering runtime, les sorties console/fichier non bloquantes, les guards et le hot reload restent réservés aux prereleases suivantes conformément au plan.
|
|
|
|
## Version Cargo
|
|
|
|
`workspace.package.version` passe de :
|
|
|
|
```text
|
|
0.1.2-pre.1
|
|
```
|
|
|
|
à :
|
|
|
|
```text
|
|
0.1.2-pre.2
|
|
```
|
|
|
|
L'identifiant de livraison reste :
|
|
|
|
```text
|
|
0.1.2-pre.002
|
|
```
|
|
|
|
Le header du `Cargo.toml` racine passe de version 26 à 27.
|
|
|
|
## Dépendances
|
|
|
|
`tracing` est ajouté à la racine sous `[workspace.dependencies]` :
|
|
|
|
```toml
|
|
tracing = { version = "^0.1", default-features = false, features = ["std"] }
|
|
```
|
|
|
|
`ksp-logging-lib` le consomme avec :
|
|
|
|
```toml
|
|
tracing.workspace = true
|
|
```
|
|
|
|
L'audit de la publication actuelle retient `tracing 0.1.44`. Les default features ne sont pas activées : `attributes` n'est pas nécessaire à cette tranche, car KSP n'utilise pas `#[instrument]`. La feature `std` suffit à la façade retenue et aux tests de subscriber local.
|
|
|
|
`tracing-subscriber` et `tracing-appender` ne sont pas ajoutés dans `pre.002` : ils ne sont pas encore consommés par du code runtime.
|
|
|
|
## Settings runtime
|
|
|
|
La surface publique introduit :
|
|
|
|
```text
|
|
LogFilterLevel
|
|
TargetFilter
|
|
SpanEvents
|
|
ConsoleOutput
|
|
ConsoleSettings
|
|
FileRotation
|
|
FileSettings
|
|
LoggingSettings
|
|
```
|
|
|
|
Ces types :
|
|
|
|
- appartiennent à `ksp-logging-lib` ;
|
|
- ne lisent aucun document Config ;
|
|
- ne consultent aucune variable d'environnement ;
|
|
- ne dépendent pas de `ksp-config-lib` ;
|
|
- utilisent des champs privés et une construction/getters explicites.
|
|
|
|
Une configuration sans console ni fichier est valide et représente un logging KSP désactivé. Les validations actuelles rejettent uniquement les ambiguïtés propres au contrat déjà fixé, notamment les préfixes de target vides/externes et un préfixe de fichier vide.
|
|
|
|
## Façade événements
|
|
|
|
Les macros crate-root suivantes sont introduites :
|
|
|
|
```text
|
|
ksp_logging_lib::error!
|
|
ksp_logging_lib::warn!
|
|
ksp_logging_lib::info!
|
|
ksp_logging_lib::debug!
|
|
ksp_logging_lib::trace!
|
|
```
|
|
|
|
Leur syntaxe KSP exige `target:` explicitement. Elles délèguent directement aux macros `tracing` au point d'expansion afin que les métadonnées `file`, `module_path` et `line` correspondent au callsite consumer et non à une fonction wrapper dans Logging.
|
|
|
|
Un bridge `tracing` public mais caché de la documentation est nécessaire à l'expansion des macros depuis les crates consommatrices. Il est réservé à l'implémentation des macros ; `DEP-LOG-009` interdit son usage direct comme API consumer.
|
|
|
|
## Spans synchrones et async
|
|
|
|
Les macros suivantes sont introduites :
|
|
|
|
```text
|
|
ksp_logging_lib::error_span!
|
|
ksp_logging_lib::warn_span!
|
|
ksp_logging_lib::info_span!
|
|
ksp_logging_lib::debug_span!
|
|
ksp_logging_lib::trace_span!
|
|
```
|
|
|
|
Elles exigent également `target:` explicitement et retournent `ksp_logging_lib::Span`.
|
|
|
|
Pour le synchrone :
|
|
|
|
```text
|
|
Span::in_scope(operation)
|
|
```
|
|
|
|
entre dans le span pendant le scope puis en sort à la fin du scope.
|
|
|
|
Pour l'async :
|
|
|
|
```text
|
|
ksp_logging_lib::instrument(span, future)
|
|
```
|
|
|
|
retourne une `Future` opaque instrumentée. Le span est entré pendant chaque poll de la future et quitté lorsque ce poll rend la main ; aucun enter guard KSP n'est destiné à être conservé à travers `.await`.
|
|
|
|
Cette surface prépare les diagnostics de durée `NEW/CLOSE`, `busy` et `idle` qui seront activés par le formatter/subscriber dans les tranches runtime suivantes.
|
|
|
|
## Erreurs
|
|
|
|
`ksp-logging-lib` utilise :
|
|
|
|
```text
|
|
ksp_core_lib::Result<T>
|
|
ksp_core_lib::Error
|
|
ksp_core_lib::ErrorCode
|
|
```
|
|
|
|
Le premier code propre à Logging est :
|
|
|
|
```text
|
|
logging.invalid_settings
|
|
```
|
|
|
|
Core ne reçoit aucune connaissance de Logging et aucune dépendance inverse n'est introduite.
|
|
|
|
## Tests ajoutés
|
|
|
|
### Unitaires
|
|
|
|
- distinction des niveaux ;
|
|
- construction/getters des target filters ;
|
|
- console stdout/stderr ;
|
|
- settings fichier/rotation ;
|
|
- conservation des settings explicites ;
|
|
- logging désactivé sans sink ;
|
|
- rejet des target prefixes vides ou externes ;
|
|
- rejet du préfixe fichier vide ;
|
|
- scope synchrone d'un span ;
|
|
- propagation du résultat d'une future instrumentée.
|
|
|
|
### Intégration
|
|
|
|
- surface publique des settings sans Config ;
|
|
- disponibilité des cinq macros événements ;
|
|
- disponibilité des cinq macros spans ;
|
|
- usage sync et async sans import consumer de `tracing::Span` ou `tracing::Instrument` ;
|
|
- préservation de `target`, `file`, `module_path` et `line` au callsite événement ;
|
|
- préservation de `target`, `file`, `module_path` et `line` au callsite span ;
|
|
- entrée puis sortie du span lors du poll d'une future instrumentée.
|
|
|
|
## Règles ajustées
|
|
|
|
`DEP-LOG-009` documente explicitement que le bridge `tracing` caché nécessaire aux macros est un détail d'implémentation de `ksp-logging-lib`, jamais une surface utilisable par une crate consommatrice.
|
|
|
|
Le plan `004-V0_1_2_LOGGING_FOUNDATION_PLAN.md` est synchronisé avec l'API effectivement retenue dans `pre.002` et avec la validité d'un logging entièrement désactivé.
|
|
|
|
## Fichiers ajoutés
|
|
|
|
- `crates/ksp-logging-lib/Cargo.toml`
|
|
- `crates/ksp-logging-lib/src/error.rs`
|
|
- `crates/ksp-logging-lib/src/lib.rs`
|
|
- `crates/ksp-logging-lib/src/macros.rs`
|
|
- `crates/ksp-logging-lib/src/settings.rs`
|
|
- `crates/ksp-logging-lib/src/span.rs`
|
|
- `crates/ksp-logging-lib/unit_tests/settings.rs`
|
|
- `crates/ksp-logging-lib/unit_tests/span.rs`
|
|
- `crates/ksp-logging-lib/tests/callsite.rs`
|
|
- `crates/ksp-logging-lib/tests/public_api.rs`
|
|
- `deltas/0.1.2/pre.002.md`
|
|
|
|
## Fichiers modifiés
|
|
|
|
- `Cargo.toml`
|
|
- `docs/plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`
|
|
- `docs/rules/RULES_DEPENDENCIES.md`
|
|
|
|
## Fichiers supprimés
|
|
|
|
Aucun.
|
|
|
|
## Validations exécutées
|
|
|
|
Validations statiques exécutées dans l'environnement de préparation :
|
|
|
|
- parsing TOML des manifests ;
|
|
- contrôle des headers `file:` / `version:` des fichiers livrés ;
|
|
- contrôle de l'absence de `Cargo.lock` dans le delta ;
|
|
- contrôle de l'absence de `tracing-subscriber` et `tracing-appender` dans les manifests ;
|
|
- contrôle de la centralisation de `tracing` sous `[workspace.dependencies]` ;
|
|
- contrôle que les usages directs de `tracing` restent bornés à `ksp-logging-lib` ;
|
|
- contrôle des patterns Rust interdits par les règles workspace dans le code production ajouté ;
|
|
- contrôle des liens Markdown locaux du plan modifié ;
|
|
- contrôle du contenu de l'archive selon `VER-ARCHIVE-004`.
|
|
|
|
## Validations non exécutées
|
|
|
|
L'environnement de préparation ne fournit pas `cargo`, `rustc` ou `rustfmt`. Les validations suivantes ne sont donc **pas** déclarées réussies :
|
|
|
|
```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
|
|
```
|
|
|
|
Elles doivent être exécutées sur le workspace de développement avant validation de la tranche. Toute erreur sera corrigée par le delta suivant conformément au workflow KSP.
|
|
|
|
## Décisions prises
|
|
|
|
- `tracing` est la seule dépendance de la stack ajoutée en `pre.002` ;
|
|
- les macros KSP exigent `target:` ;
|
|
- le callsite est préservé par expansion de macro et testé ;
|
|
- l'abstraction publique de span est `ksp_logging_lib::Span` ;
|
|
- le synchrone utilise `Span::in_scope(...)` ;
|
|
- l'async utilise `instrument(span, future)` ;
|
|
- une configuration sans sink est valide et représente Logging désactivé ;
|
|
- aucune initialisation/subscriber global n'est introduit prématurément dans cette tranche.
|
|
|
|
## Questions ouvertes
|
|
|
|
Aucune question bloquante pour `pre.002`.
|
|
|
|
Restent à choisir/tester dans les tranches runtime suivantes :
|
|
|
|
- la composition interne reloadable la moins coûteuse ;
|
|
- l'API exacte d'observation des lignes abandonnées ;
|
|
- les détails finaux du formatter console/fichier ;
|
|
- la stratégie de swap des sinks garantissant le maintien de l'ancienne configuration si une reconfiguration échoue.
|
|
|
|
Après validation de cette tranche, la prochaine étape est `0.1.2-pre.003` : subscriber, takeover, filtering, console initiale et fondation du hot reload.
|