litellm/litellm-rust/crates/tracing

Native diagnostic tracing

litellm-tracing connects standard tracing events to a host-provided Sink. It has no Python dependency and does not install a global subscriber

Use the exported debug!, info!, warn!, and error! macros in native code. A host creates a Logger with its sink, uses scope for synchronous operations, and wraps futures with instrument. Instrument spawned futures explicitly because thread-local subscribers do not automatically follow spawned work

Bindings implement litellm_tracing::Sink to connect events to their host runtime:

pub trait Sink: Send + Sync + 'static {
    fn enabled(&self, metadata: &Metadata<'_>) -> bool;
    fn emit(&self, record: &Record);
}

Pass the implementation to litellm_tracing::Logger::new(sink), then call logger.scope(|| litellm_tracing::info!(attempt = 1, "request started")). The sink owns host access, level mapping, correlation capture, and delivery failures. enabled runs before event fields are evaluated or formatted. emit borrows a record; an adapter that queues delivery must copy the data it needs into an owned value

Records retain event metadata, the message, and typed event fields. Sink filtering runs for each event so runtime level changes take effect. Logging from inside a sink is suppressed to prevent recursion

The Python bridge scopes native execution to a sink that uses LiteLLM's existing Python logger. It preserves request correlation, redacts before delivering to handlers, maps Rust trace events to Python debug, and reports handler failures through sys.unraisablehook. It accepts LiteLLM targets only, keeping dependency wire diagnostics out of the application logger

Python consumers continue using litellm._logging and its existing loggers, filters, formatters, and context setters. Catalog dispatch selects the processing backend for both Python and native diagnostics. The pure Processor takes explicit settings and never emits events

A future Node bridge can implement the same sink with runtime-specific delivery and expose the same processor through N-API. Node callback scheduling, queue limits, and shutdown belong in that bridge; this crate has no interpreter handles or output queue

This is diagnostic logging. Request lifecycle hooks and CustomLogger dispatch remain separate