38 lines
2.1 KiB
Markdown
38 lines
2.1 KiB
Markdown
<!-- file: crates/ksp-logging-lib/README.md -->
|
|
<!-- version: 3 -->
|
|
|
|
# ksp-logging-lib
|
|
|
|
`ksp-logging-lib` est la façade commune de logging/tracing runtime de Khadhroony Solana Project.
|
|
|
|
## Responsabilités
|
|
|
|
La crate possède :
|
|
|
|
- les cinq niveaux KSP `error`, `warn`, `info`, `debug` et `trace` ;
|
|
- les macros d'événements et de spans qui préservent le callsite du consommateur ;
|
|
- `LoggingSettings`, la console explicite et les settings fichier indépendants de Config ;
|
|
- les formats publics `Human/Compact/Pretty/Json` et les filtres par output (`level`, targets KSP et domains) ;
|
|
- zéro, un ou plusieurs descriptors fichier identifiés par `output_id` unique ;
|
|
- l'installation unique du subscriber global ;
|
|
- le hot reload via `reinitialize` sans second subscriber global ;
|
|
- le takeover des logs : les targets externes sont silencieux par défaut ;
|
|
- le runtime non bloquant console/fichier existant, avec activation multi-sink/routing enrichie finalisée dans la tranche runtime dédiée ;
|
|
- les `WorkerGuard`, compteurs de lignes abandonnées, rotation fichier et stripping ANSI ;
|
|
- l'instrumentation de scopes synchrones et de `Future` async.
|
|
|
|
L'API async de production reste indépendante de tout executor. Tokio est utilisé uniquement comme `dev-dependency` afin de valider `instrument(...)` sur un executor réel en mode current-thread et multi-thread ; il ne fait pas partie des dépendances runtime de la crate.
|
|
|
|
## Frontières
|
|
|
|
Une crate KSP comportementale qui journalise son activité dépend de `ksp-logging-lib` et n'utilise pas directement `tracing`, `tracing-subscriber` ou `tracing-appender`.
|
|
|
|
Les événements utiles issus d'une dépendance externe ne sont pas renommés : la crate KSP propriétaire de l'opération réémet explicitement l'information utile sous son propre target KSP.
|
|
|
|
`ksp-logging-lib` ne dépend pas de `ksp-config-lib`. Config pourra construire un `LoggingSettings` puis appeler `initialize` ou `reinitialize`.
|
|
|
|
## Documentation
|
|
|
|
- [`USAGE.md`](USAGE.md) — utilisation concrète de la façade et du runtime ;
|
|
- [`TODO.md`](TODO.md) — capacités explicitement différées ou points restant à fermer.
|