khadhroony-solana-project/crates/ksp-logging-lib/README.md

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 runtime Human/Compact/Pretty/Json ;
• zéro, un ou plusieurs outputs fichier actifs simultanément, identifiés par output_id unique ;
• le routing par output sur niveau et target KSP ;
• le contrat de filtre domain, dont l'activation runtime structurée est volontairement séparée dans la tranche suivante ;
• 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 ;
• les writers non bloquants console/fichier et leurs WorkerGuard ;
• les compteurs agrégés de lignes abandonnées et le compteur cumulatif par output_id fichier ;
• la rotation fichier, le stripping ANSI persistant et l'ANSI configurable pour la console ;
• 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.

Routing domain

OutputFilter représente déjà :

level
targets[]
domains[]

0.1.3-pre.005 active réellement level et targets[]. Un output actif dont domains[] est différent de [*] est refusé explicitement par initialize/reinitialize jusqu'à la tranche dédiée au routing structuré par champ domain.

Ce refus évite d'assimiler artificiellement domain au target ou d'ignorer silencieusement la dimension demandée.

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 — utilisation concrète de la façade et du runtime ;
• TODO.md — capacités explicitement différées ou points restant à fermer.