Expand description
§ltrace — Rolling file writer and multi-target logger for tracing and log
This crate provides a high-performance rolling file writer with:
- Log rotation by time: MINUTELY, HOURLY, DAILY
- Log rotation by size: configurable max file size (independent of time rotation)
- Time + size combined rotation: even when using time-based rotation (e.g. Daily), a size limit still triggers additional rotations within that window (e.g., multiple rotations per day if the log exceeds the size threshold)
- Compression: optional gzip compression for rotated files (feature
compression), performed on a background thread so it does not block writes - Max file count: automatically prune old log files
- Dynamic log level: change the log level at runtime via
LogHandle - Timezone configuration: UTC (default) or local timezone for rotation timestamps
- Auto-create directories: parent directories are created automatically if they don’t exist
§Using with tracing
Since RollingWriter implements std::io::Write, you can use it with
tracing_appender::non_blocking() to get non-blocking writes:
use ltrace::{RollingWriter, Rotation, Compression};
let writer = RollingWriter::builder("/var/log/myapp/app.log")
.rotation(Rotation::Daily)
.max_file_size(10 * 1024 * 1024) // 10 MB
.max_files(10)
.compression(Compression::Gzip)
.build()
.unwrap();
let (non_blocking, _guard) = tracing_appender::non_blocking(writer);
let subscriber = tracing_subscriber::fmt()
.with_writer(non_blocking)
.finish()
.init()?;§Output targets
ltrace supports multiple log output targets that can be combined:
- Rolling file logs:
LogWriterfor time/size-based rotating file logs - Console output: [
ConsoleWriter] for colored terminal output (featureconsole) - Multi-target output:
MultiLogto combine multiple writers together
§Rotated file naming
Rotated filenames use a nanosecond-precision timestamp (nanoseconds since UNIX epoch) to guarantee strict ordering and uniqueness, with an optional date prefix:
- Daily rotation:
app.log.2024-01-15T1780358400000000000 - Hourly rotation:
app.log.2024-01-15-14T1780358400000000000 - Minutely rotation:
app.log.2024-01-15-14-30T1780358400000000000 - Size-only (Never):
app.log.1780358400000000000
With gzip compression enabled: app.log.2024-01-15T1780358400000000000.gz
§Quick start
Enable the log feature in your Cargo.toml:
[dependencies]
ltrace = { version = "0.1", features = ["log"] }The recommended way is to call LogWriter::init directly:
use ltrace::LogWriter;
let handle = LogWriter::init("app.log")?;
// Dynamically change level at runtime:
handle.set_level(log::LevelFilter::Debug);§Full builder configuration
Use LogWriter::builder for complete control over rotation, compression, and levels:
use ltrace::{LogWriter, Rotation, Compression};
let handle = LogWriter::builder("/var/log/myapp/app.log")
.rotation(Rotation::Daily)
.max_file_size(10 * 1024 * 1024) // also rotate within the same day if size exceeded
.max_files(5)
.compression(Compression::Gzip)
.level(log::LevelFilter::Info)
.init()?;§Console output (feature console)
Enable the console feature in your Cargo.toml:
[dependencies]
ltrace = { version = "0.1", features = ["console"] }use ltrace::ConsoleWriter;
let handle = ConsoleWriter::builder()
.level(log::LevelFilter::Debug)
.init()?;§Multi-target output (console + file)
use ltrace::{MultiLog, ConsoleWriter, LogWriter, Rotation, Compression};
let multi = MultiLog::new()
.writer(ConsoleWriter::builder()
.level(log::LevelFilter::Info)
.build()?)
.writer(LogWriter::builder("/var/log/myapp/app.log")
.rotation(Rotation::Daily)
.compression(Compression::Gzip)
.level(log::LevelFilter::Debug)
.build()?)
.init()?;§Multi-target with per-writer level control
use ltrace::{MultiLog, ConsoleWriter, LogWriter};
let (multi, handles) = MultiLog::new()
.writer_with_handle(ConsoleWriter::builder().build()?)
.writer_with_handle(LogWriter::builder("app.log").build()?)
.build_with_handles()?;
// Adjust each writer's level independently:
handles[0].set_level(log::LevelFilter::Warn); // console: only warn+
handles[1].set_level(log::LevelFilter::Debug); // file: debug+§Dynamic log level control
LogHandle is Clone + Send + Sync, so you can move it to other threads:
let handle = LogWriter::init("app.log")?;
// Spawn a thread that listens for signals to change the log level.
let handle_clone = handle.clone();
std::thread::spawn(move || {
// e.g., listen for SIGHUP or an HTTP endpoint
handle_clone.set_level(log::LevelFilter::Debug);
});Structs§
- LogHandle
- A handle to dynamically change the log level of a writer.
- LogWriter
- A logger that writes to rolling log files.
- LogWriter
Builder - Builder for creating a
LogWriterand optionally initializing it as the global logger. - Multi
Handle - A handle returned by
MultiLogBuilder::initorMultiLogBuilderWithHandles::init_with_handlesfor managing the multi-log. - Multi
Log - A logger that dispatches records to multiple
log::Logwriters. - Multi
LogBuilder - Builder for creating a
MultiLogwith multiple writers. - Multi
LogBuilder With Handles - Builder for creating a
MultiLogwith per-writer dynamic level handles. - Rolling
Writer - A
std::io::Writeimplementation that writes to a log file with automatic rotation by time and/or size.
Enums§
- Compression
- Compression mode for rotated log files.
- Rotation
- How often to rotate log files based on time.
- Timezone
- Timezone used for rotation timestamps and filenames.