A high-performance rolling file writer and multi-target logger for
tracingandlogcrates with rotation, compression, dynamic log levels, console output, and multi-target support.
- Log rotation by time — MINUTELY, HOURLY, DAILY
- Log rotation by size — configurable max file size (independent of time rotation)
- Time + size combined — size limits can trigger additional rotations within a time window
- Gzip compression — rotated files can be compressed on a background thread (zero blocking)
- Auto prune — automatically remove old log files when max count is exceeded
- Dynamic log level — change the log level at runtime via
LogHandle(Clone + Send + Sync) - Console output — colored terminal logging with ANSI colors (feature
console) - Multi-target logging — combine console + file, or any number of writers together
- Timezone support — UTC (default) or local timezone for rotation timestamps
- Auto-create directories — parent directories created automatically
Add ltrace to your Cargo.toml:
[dependencies]
ltrace = "0.1"| Feature | Default | Description |
|---|---|---|
log |
✅ | Enable log crate support |
compression |
✅ | Enable gzip compression (requires flate2) |
console |
❌ | Enable colored console output (requires colored) |
To enable console support:
[dependencies]
ltrace = { version = "0.1", features = ["log", "console"] }To disable default features:
[dependencies]
ltrace = { version = "0.1", default-features = false, features = ["log"] }Use RollingWriter with tracing_appender::non_blocking() for 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()?;
let (non_blocking, _guard) = tracing_appender::non_blocking(writer);
let subscriber = tracing_subscriber::fmt()
.with_writer(non_blocking)
.finish()
.try_init()?;Simple initialization with defaults (Daily rotation, Info level):
use ltrace::LogWriter;
let handle = LogWriter::init("/var/log/myapp/app.log")?;
// Dynamically change level at runtime:
handle.set_level(log::LevelFilter::Debug);Full builder configuration:
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()?;Output colored logs to the terminal:
use ltrace::ConsoleWriter;
let handle = ConsoleWriter::builder()
.level(log::LevelFilter::Debug)
.init()?;Colors by level:
- ERROR: bold red
- WARN: yellow
- INFO: green
- DEBUG: cyan
- TRACE: dimmed / bright black
Error and warning messages go to stderr; info, debug, and trace go to stdout.
Combine multiple writers to log to both console and file simultaneously:
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()?;Adjust each writer's log level independently at runtime:
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+use ltrace::Rotation;
// Time-based rotation
RollingWriter::builder("app.log").rotation(Rotation::Daily).build()?;
RollingWriter::builder("app.log").rotation(Rotation::Hourly).build()?;
RollingWriter::builder("app.log").rotation(Rotation::Minutely).build()?;
// Size-only rotation (no time-based rotation)
RollingWriter::builder("app.log")
.rotation(Rotation::Never)
.max_file_size(50 * 1024 * 1024) // 50 MB
.build()?;use ltrace::Compression;
RollingWriter::builder("app.log")
.compression(Compression::Gzip)
.build()?;Compression is performed on a background thread and does not block log writes.
use ltrace::Timezone;
// UTC (default)
RollingWriter::builder("app.log").timezone(Timezone::Utc).build()?;
// Local timezone
RollingWriter::builder("app.log").timezone(Timezone::Local).build()?;RollingWriter::builder("app.log")
.max_files(10) // Keep at most 10 archived log files
.build()?;LogHandle is Clone + Send + Sync, so you can move it to other threads:
let handle = LogWriter::init("app.log")?;
// Spawn a thread to listen for signals
let h = handle.clone();
std::thread::spawn(move || {
// e.g., listen for SIGHUP or an HTTP endpoint
h.set_level(log::LevelFilter::Debug);
});
// Check current level
println!("Current level: {:?}", handle.get_level());Rotated filenames use a nanosecond-precision timestamp (nanoseconds since UNIX epoch) to guarantee strict ordering and uniqueness:
| Mode | Filename Pattern |
|---|---|
| Daily | app.log.2024-01-15T1780358400000000000 |
| Hourly | app.log.2024-01-15-14T1780358400000000000 |
| Minutely | app.log.2024-01-15-14-30T1780358400000000000 |
| Size-only | app.log.1780358400000000000 |
With gzip compression: app.log.2024-01-15T1780358400000000000.gz
| Type | Description |
|---|---|
RollingWriter |
Core rolling file writer, implements std::io::Write |
Rotation |
Time-based rotation frequency enum |
Compression |
Compression mode (None / Gzip, requires compression feature) |
Timezone |
UTC or Local timezone for timestamps |
LogWriter |
Implements log::Log for rolling file logging |
LogWriterBuilder |
Builder for LogWriter |
ConsoleWriter |
Colored terminal logger (requires console feature) |
ConsoleWriterBuilder |
Builder for ConsoleWriter |
MultiLog |
Multi-target log dispatcher, combines multiple writers |
LogHandle |
Cloneable handle for dynamic level changes |
MultiHandle |
Handle for multi-log management with per-writer access |
Licensed under either of:
at your option.
Contributions are welcome! Please feel free to submit a Pull Request.
Author: James Ren jamesvren@163.com Repository: https://github.com/jamesvren/ltrace