ltrace
A high-performance rolling file writer for
tracingandlogcrates with rotation, compression, and dynamic log level 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
logcrate log level at runtime viaLogHandle - 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) |
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;
fmt
.with_ansi
.with_writer
.finish
.try_init?;
With log crate
Chain init() directly on the builder for a clean one-liner:
use LogWriterBuilder;
use ;
let handle = new
.rotation
.max_file_size // optional: rotate within the same day if size exceeded
.max_files
.compression
.level
.init?;
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 (log crate only)
LogHandle is Clone + Send + Sync, so you can move it to other threads:
let handle = new
.level
.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 / Module | Description |
|---|---|
RollingWriter |
Core rolling file writer, implements std::io::Write |
Rotation |
Time-based rotation frequency enum |
Compression |
Compression mode (None / Gzip) |
Timezone |
UTC or Local timezone for timestamps |
log_layer::LogWriterBuilder |
Builder for log crate integration |
log_layer::LogWriter |
Implements log::Log for the global logger |
log_layer::LogHandle |
Cloneable handle for dynamic level changes |
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