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

Utilisation de ksp-logging-lib

Target d'une crate consommatrice

Chaque crate KSP comportementale fournit explicitement son target, égal au nom Cargo de la crate :

const LOGGING_TARGET: &str = "ksp-store-lib";

ksp_logging_lib::trace!(
    target: LOGGING_TARGET,
    domain = "store",
    component = "postgres",
    operation = "load_transactions",
    "executing store operation"
);

Les champs domain, component, operation et autres champs structurés sont ajoutés par le caller lorsqu'ils sont utiles ; ils ne remplacent pas le target propriétaire.

Contrat des outputs

LoggingSettings possède :

• le default_filter global de takeover KSP ;
• les TargetFilter globaux ;
• la politique SpanEvents ;
• une console déclarée optionnellement ;
• zéro, un ou plusieurs FileSettings.

Chaque output possède un OutputFilter indépendant. Son niveau, ses targets et ses domains s'appliquent en plus de la politique globale. * signifie « tous » dans la dimension concernée.

Les formats publics sont :

Human
Compact
Pretty
Json

Une sortie fichier possède un output_id stable et unique dans LoggingSettings. Cet identifiant appartient au runtime Logging et ne doit pas être confondu avec les file_id utilisés par ksp-config-lib pour identifier ses documents.

Les fichiers persistants interdisent ansi = true.

Runtime multi-output de pre.005

0.1.3-pre.005 active réellement :

• plusieurs fichiers simultanés ;
• les formats Human, Compact, Pretty et Json ;
• l'ANSI console ;
• le routing par niveau et target pour chaque output ;
• le comptage cumulatif des lignes abandonnées par output_id fichier ;
• le hot reload de ces sorties sans réinstaller le subscriber global.

Le routing domain est volontairement séparé. OutputFilter continue de représenter domains[], mais un output actif dont cette dimension est différente de ["*"] est refusé par initialize/reinitialize jusqu'à la tranche suivante. La configuration n'est donc jamais acceptée puis partiellement ignorée.

Les helpers ConsoleSettings::stdout() et ConsoleSettings::stderr() restent des raccourcis Human, sans ANSI et sans restriction supplémentaire par output.

Initialisation

let file = ksp_logging_lib::FileSettings::new(
    "file.worker",
    true,
    "logs",
    "worker.log",
    ksp_logging_lib::FileRotation::Daily,
    ksp_logging_lib::LogFormat::Human,
    ksp_logging_lib::OutputFilter::unrestricted(),
);

let settings = ksp_logging_lib::LoggingSettings::new(
    ksp_logging_lib::LogFilterLevel::Info,
    ksp_logging_lib::SpanEvents::NewAndClose,
    std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
    std::vec![file],
);

let initialize_result = ksp_logging_lib::initialize(&settings);
let mut logging_guard = match initialize_result {
    std::result::Result::Ok(guard) => guard,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

Une configuration sans output actif est valide et installe une infrastructure initialement silencieuse qui pourra être activée plus tard par hot reload.

Construction d'un runtime multi-output

Le runtime peut maintenant activer plusieurs sorties ayant des formats et filtres metadata distincts :

let console = ksp_logging_lib::ConsoleSettings::new(
    true,
    ksp_logging_lib::ConsoleOutput::Stderr,
    true,
    ksp_logging_lib::LogFormat::Compact,
    ksp_logging_lib::OutputFilter::new(
        ksp_logging_lib::LogFilterLevel::Debug,
        std::vec!["*".to_string()],
        std::vec!["*".to_string()],
    ),
);

let error_file = ksp_logging_lib::FileSettings::new(
    "file.config.error",
    true,
    "logs/config",
    "error.jsonl",
    ksp_logging_lib::FileRotation::Daily,
    ksp_logging_lib::LogFormat::Json,
    ksp_logging_lib::OutputFilter::new(
        ksp_logging_lib::LogFilterLevel::Error,
        std::vec!["ksp-config-lib".to_string()],
        std::vec!["*".to_string()],
    ),
);

let settings = ksp_logging_lib::LoggingSettings::new(
    ksp_logging_lib::LogFilterLevel::Warn,
    ksp_logging_lib::SpanEvents::NewAndClose,
    std::option::Option::Some(console),
    std::vec![error_file],
);

let validation = settings.validate();

validate() vérifie le contrat structurel. initialize/reinitialize appliquent le niveau et les targets par output ; les domains spécifiques restent refusés jusqu'à la tranche de routing structuré.

Hot reload

Une configuration peut être appliquée sans redémarrer le processus ou le worker :

let debug_settings = ksp_logging_lib::LoggingSettings::new(
    ksp_logging_lib::LogFilterLevel::Info,
    ksp_logging_lib::SpanEvents::NewAndClose,
    std::option::Option::Some(ksp_logging_lib::ConsoleSettings::stderr()),
    std::vec::Vec::new(),
)
.with_target_filter(ksp_logging_lib::TargetFilter::new(
    "ksp-store-lib",
    ksp_logging_lib::LogFilterLevel::Debug,
));

let reload_result = ksp_logging_lib::reinitialize(&mut logging_guard, &debug_settings);
if let std::result::Result::Err(error) = reload_result {
    return std::result::Result::Err(error);
}

La nouvelle configuration est préparée avant la bascule. Si sa validation ou la création d'un nouveau sink échoue, l'ancienne configuration reste active.

Spans synchrones

let span = ksp_logging_lib::trace_span!(
    target: LOGGING_TARGET,
    "materialize_transaction",
    domain = "store"
);

let output = span.in_scope(|| {
    return materialize_transaction();
});

Avec SpanEvents::NewAndClose, le formatter produit les événements de création/fermeture et les temps busy / idle à la fermeture.

Spans async

Une Future doit être instrumentée avec ksp_logging_lib::instrument ; un guard d'entrée de span ne doit pas être conservé à travers .await :

let span = ksp_logging_lib::trace_span!(
    target: LOGGING_TARGET,
    "fetch_account",
    domain = "transport"
);

let output = ksp_logging_lib::instrument(span, fetch_account()).await;

La future instrumentée entre/sort du span pendant ses polls et lors de son Drop, conformément au contrat de la primitive tracing sous-jacente.

Lignes abandonnées

Les sorties utilisent des queues lossy afin de ne pas appliquer de backpressure au hot path. La vue agrégée console/fichier reste disponible :

let dropped = logging_guard.dropped_lines();
ksp_logging_lib::warn!(
    target: LOGGING_TARGET,
    console = dropped.console(),
    file = dropped.file(),
    total = dropped.total(),
    "logging queues dropped lines"
);

Pour un fichier précis :

let dropped_for_output = logging_guard.dropped_file_lines("file.worker");

Le compteur par output_id reste cumulatif à travers les hot reloads tant que le même LoggingGuard est conservé.

Instrumentation async et executor

instrument(span, future) accepte une Future standard et ne dépend d'aucun executor particulier. Tokio n'est présent qu'en dev-dependency pour valider la surface sur un executor réel, y compris après plusieurs suspensions et sur un runtime multi-thread.