Logging System
Relevant Rust source files
crates/common/src/logging/mod.rscrates/common/src/logging/config.rscrates/common/src/logging/logger.rscrates/common/src/logging/writer.rscrates/common/src/logging/bridge.rscrates/common/src/logging/macros.rscrates/common/benches/logging.rs
The Rust logger isolates formatting and I/O from performance-sensitive engine paths. Producers emit structured log events through a channel; a dedicated logger consumes them and writes to configured stdout, stderr, and file targets. LogGuard keeps that worker alive for the owning system lifetime and coordinates shutdown.
Initialization
init_logging accepts the instance identity, trader identity, machine identifier, component name, LoggerConfig, and optional file-writer config. Initialization is process-global and must occur before concurrent components begin emitting. ensure_logging_initialized provides a conservative fallback based on NAUTILUS_LOG, but production binaries should initialize deliberately so level, color, buffering, and file behavior are explicit.
logging_is_initialized reports the state. logging_shutdown begins termination, and logging_sync_to_disk requests a durable flush. Applications should retain the returned LogGuard until all producers have stopped; dropping it early can discard late lifecycle diagnostics.
Configuration
LoggerConfig controls the default level, per-component level overrides, color, and output behavior. Its builder validates the configuration before it reaches the worker. parse_level_filter_str and parse_component_levels convert textual configuration at the boundary rather than scattering parsing through components.
Writers are separate from routing:
StdoutWriterhandles the normal stream with optional buffering and color.StderrWriterhandles error output.FileWriterowns file output and rotation throughFileWriterConfigandFileRotateConfig.
Time model
Logging follows the active execution clock. logging_clock_set_realtime_mode selects wall-clock time for live operation. Static mode plus logging_clock_set_static_time makes backtest log timestamps follow deterministic simulation time. This is essential when logs are used to explain replay order.
Filtering and backpressure
Level and component filtering should occur before expensive formatting. The logger is asynchronous, but its queue is still a bounded operational resource: debug volume can increase memory use and delay flush. High-frequency market-data values belong in metrics, traces, or sampled diagnostics rather than unconditional line logs.
Tracing bridge
When the relevant feature is enabled, init_tracing bridges tracing events into the Nautilus logging pipeline. tracing_is_initialized prevents duplicate subscriber installation. The bridge does not make a tracing span durable; durability still depends on the configured writers and successful flush.
Failure-driven shutdown
arm_shutdown_on_error, take_shutdown_on_error_trigger, and try_drain_shutdown_on_error_trigger support a bounded handoff from fatal logging conditions to the outer runtime. That path should request orderly node shutdown instead of terminating inside a logging callback.
Operational checklist
Initialize once, retain LogGuard, use component-specific levels, keep hot-path logging sampled, flush before process exit, and verify file rotation under the deployment filesystem. Benchmarks in crates/common/benches/logging.rs measure the logger itself; they do not substitute for end-to-end latency measurements with the chosen writers and deployment storage.