ltrace
A high-performance rolling file writer and multi-target logger for
tracingandlogcrates with rotation, compression, dynamic log levels, console output, and multi-target support.
Features
- 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
Installation
Add ltrace to your Cargo.toml:
[]
= "0.1"
Features
| 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:
[]
= { = "0.1", = ["log", "console"] }
To disable default features:
[]
= { = "0.1", = false, = ["log"] }
Quick Start
With tracing
Use RollingWriter with tracing_appender::non_blocking() for non-blocking writes:
use ;
let writer = builder
.rotation
.max_file_size // 10 MB
.max_files
.compression
.build?;
let = non_blocking;
let subscriber = fmt
.with_writer
.finish
.try_init?;
With log crate
Simple initialization with defaults (Daily rotation, Info level):
use LogWriter;
let handle = init?;
// Dynamically change level at runtime:
handle.set_level;
Full builder configuration:
use ;
let handle = builder
.rotation
.max_file_size // also rotate within the same day if size exceeded
.max_files
.compression
.level
.init?;
Console output (feature console)
Output colored logs to the terminal:
use ConsoleWriter;
let handle = builder
.level
.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.
Multi-target output (console + file)
Combine multiple writers to log to both console and file simultaneously:
use ;
let multi = new
.writer
.writer
.init?;
Per-writer dynamic level control
Adjust each writer's log level independently at runtime:
use ;
let = new
.writer_with_handle
.writer_with_handle
.build_with_handles?;
// Adjust each writer's level independently:
handles.set_level; // console: only warn+
handles.set_level; // file: debug+
Configuration
Rotation
use Rotation;
// Time-based rotation
builder.rotation.build?;
builder.rotation.build?;
builder.rotation.build?;
// Size-only rotation (no time-based rotation)
builder
.rotation
.max_file_size // 50 MB
.build?;
Compression
use Compression;
builder
.compression
.build?;
Compression is performed on a background thread and does not block log writes.
Timezone
use Timezone;
// UTC (default)
builder.timezone.build?;
// Local timezone
builder.timezone.build?;
Max File Count
builder
.max_files // Keep at most 10 archived log files
.build?;
Dynamic Log Level
LogHandle is Clone + Send + Sync, so you can move it to other threads:
let handle = init?;
// Spawn a thread to listen for signals
let h = handle.clone;
spawn;
// Check current level
println!;
Rotated File Naming
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
API Overview
| 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 |
License
Licensed under either of:
at your option.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Author: James Ren jamesvren@163.com Repository: https://github.com/jamesvren/ltrace