Rust-Loguru

A flexible and efficient logging library for Rust inspired by Python's Loguru. Designed to provide an intuitive, powerful logging experience while maintaining Rust's performance characteristics.

Features

• Multiple log levels: TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
• Thread-safe global logger: Safe to use in multi-threaded applications
• Extensible handler system: Console, file, and custom handlers
• Configurable log formatting: Customize how log messages are displayed
• Support for metadata in log records: Add structured data to log messages
• Convenient logging macros: Easy to use macros for all log levels
• File rotation: Automatic file rotation based on size with retention policies
• Colorized output: Colorful console output for better readability
• Source location capture: Automatically capture file, line, and module information
• Ergonomic error handling and context helpers: Extension traits, error chain, panic hook, and macros

Installation

Add this to your Cargo.toml:

[dependencies]
rust-loguru = "0.1.15" # Or Newer version

Performance Benchmarks

Basic Logging (single-message overhead at DEBUG, INFO, ERROR levels)

---

Concurrent Logging (INFO-level with 2, 4, 8, 16 threads)

---

High-Volume Logging (bulk emit of 100, 1 000, 10 000 messages)

---

File-Rotation (write and rotate files)

---

Key Findings:

1. Standard Logging Performance:

   • slog shows exceptional performance for most standard operations (3-6 ns)
   • loguru consistently performs well (160-180 ns), significantly faster than log and tracing
   • log and tracing show higher execution times (400-650 ns)

2. Concurrent Logging:

   • All libraries show scaling patterns with more threads, but slog maintains the best performance
   • loguru shows excellent multithreading efficiency, ranking 2nd consistently

3. File Rotation:

   • slog is fastest at 7.08ms
   • tracing follows at 16.65ms
   • log4rs at 32.73ms
   • loguru is slowest at 48.05ms

4. High Volume Logging:

   • For very high volumes (10,000 elements), slog maintains exceptional performance
   • loguru handles large volumes significantly better than both log and tracing

Quick Start

use rust_loguru::{info, debug, error, init, LogLevel, Logger};
use rust_loguru::handler::console::ConsoleHandler;
use std::sync::Arc;
use parking_lot::RwLock;

fn main() {
    // Initialize the global logger with a console handler
    let handler = Arc::new(RwLock::new(
        ConsoleHandler::stderr(LogLevel::Debug)
            .with_colors(true)
    ));
    
    let mut logger = Logger::new(LogLevel::Debug);
    logger.add_handler(handler);
    
    // Set the global logger (required for macros to work)
    init(logger);
    
    // Log messages at different levels
    debug!("This is a debug message");
    info!("This is an info message");
    error!("This is an error message: {}", "something went wrong");
    
    // Log with metadata
    use rust_loguru::log_with_metadata;
    log_with_metadata!(LogLevel::Info, "user_id" => "123", "session" => "abc123"; 
                       "User logged in: {}", "johndoe");
}

Macro Usage Examples

Rust-Loguru provides a rich set of macros for ergonomic and powerful logging, context, and error handling. Here are some advanced macro usages:

Context Macros

use rust_loguru::{push_context, pop_context, set_context, get_context};

push_context!("user" => "alice", "role" => "admin");
set_context!("user", "bob");
let user = get_context!("user");
println!("Current user: {}", user.unwrap());
pop_context!();

Scope Macros

use rust_loguru::{scope, scoped_info};

// Simple scope guard for timing and indentation
let _guard = scope!("my_scope");

// Log entering and exiting a scope with timing
let _scope = scoped_info!("important_section");

Error Integration Macros

use rust_loguru::{log_error, log_error_with_context, try_log};

let err = "something went wrong";
log_error!(err);
log_error!(err, "custom message");
log_error_with_context!(err, "context info");

let res: Result<i32, &str> = Err("fail");
let _ = try_log!(res, "operation failed");
let opt: Option<i32> = None;
let _ = try_log!(option opt, "missing value");

Compile-time Level Filtering

use rust_loguru::{log_if_enabled, LogLevel};

let result = log_if_enabled!(LogLevel::Info, "This will only log if enabled at compile time");

Structured Data in Level Macros

use rust_loguru::info_kv;

info_kv!("User login event"; "user_id" => "123", "ip" => "192.168.1.1");

Core Concepts

Log Levels

Rust-Loguru supports the following log levels, in order of increasing severity:

• TRACE: Very detailed information, typically only useful for debugging specific issues
• DEBUG: Detailed information useful for debugging
• INFO: General information about the application's operation
• SUCCESS: Successful operations (similar to INFO but indicates success)
• WARNING: Potential issues that don't prevent the application from working
• ERROR: Errors that prevent specific operations from working
• CRITICAL: Critical errors that may lead to application failure

Handlers

Handlers determine where log messages are sent. Rust-Loguru comes with:

• ConsoleHandler: Outputs logs to stdout or stderr
• FileHandler: Writes logs to a file with optional rotation
• NullHandler: Discards all logs (useful for testing)

Creating a Console Handler

use rust_loguru::handler::console::ConsoleHandler;
use rust_loguru::LogLevel;

// Output to stderr with INFO level
let handler = ConsoleHandler::stderr(LogLevel::Info)
    .with_colors(true)
    .with_pattern("{time} {level} [{file}:{line}] {message}");

Creating a File Handler

use rust_loguru::handler::file::FileHandler;
use rust_loguru::LogLevel;
use std::path::Path;

// Write to a file with rotation at 10MB and keep 5 old files
let handler = FileHandler::new(Path::new("app.log")).unwrap()
    .with_rotation(10 * 1024 * 1024)
    .with_retention(5)
    .with_colors(false);

Logging with Metadata

You can add structured metadata to log records:

use rust_loguru::{Record, LogLevel, log};

// Using the Record API directly
let record = Record::new(
    LogLevel::Info,
    "User logged in",
    Some("auth_module".to_string()),
    Some("auth.rs".to_string()),
    Some(42),
)
.with_metadata("user_id", "123")
.with_metadata("ip_address", "192.168.1.1");

log(&record);

// Or using the macro
log_with_metadata!(LogLevel::Info, 
    "user_id" => "123", 
    "ip_address" => "192.168.1.1"; 
    "User logged in: {}", "johndoe"
);

Customizing Formatters

Customize how logs are formatted:

use rust_loguru::formatter::Formatter;

let formatter = Formatter::new()
    .with_colors(true)
    .with_timestamp(true)
    .with_level(true)
    .with_module(true)
    .with_location(true)
    .with_pattern("{time} {level} [{file}:{line}] {message}");

Configuration Presets

Use built-in configuration presets:

use rust_loguru::LoggerConfig;

// Development configuration with detailed logging
let config = LoggerConfig::development();

// Production configuration with minimal logging
let config = LoggerConfig::production();

Using TOML Configuration Files

You can load logger configuration from a TOML file or string. This is useful for externalizing configuration and making it easy to adjust logging without code changes.

Example TOML file (loguru_config.toml):

level = "Debug"
capture_source = true
use_colors = false
format = "[TOML] {level} {message}"

Loading from a TOML file:

use rust_loguru::config::LoggerConfigBuilder;

let config = LoggerConfigBuilder::new()
    .from_toml_file("loguru_config.toml")
    .unwrap()
    .build();

Loading from a TOML string:

use rust_loguru::config::LoggerConfigBuilder;

let toml = r#"
level = "Info"
use_colors = true
"#;
let config = LoggerConfigBuilder::new()
    .from_toml_str(toml)
    .unwrap()
    .build();

Precedence:

• Values set via builder methods or environment variables will override those loaded from TOML.
• Supported TOML keys: level, capture_source, use_colors, format.

Scopes and Timed Execution

Rust-Loguru provides a ScopeGuard utility for measuring the duration of code blocks and managing indentation for nested scopes. This is useful for profiling, debugging, and structured logging of code execution.

use rust_loguru::ScopeGuard;
use std::thread;
use std::time::Duration;

fn main() {
    // Enter a scope and measure its duration
    let scope = ScopeGuard::enter("outer");
    println!("Indent level: {}", ScopeGuard::indent_level());
    thread::sleep(Duration::from_millis(50));
    {
        let _inner = ScopeGuard::enter("inner");
        println!("Indent level: {}", ScopeGuard::indent_level());
        thread::sleep(Duration::from_millis(20));
        // _inner dropped here, indentation decreases
    }
    println!("Indent level: {}", ScopeGuard::indent_level());
    println!("Elapsed in outer: {:?}", scope.elapsed());
    // scope dropped here
}

• Indentation is managed per-thread and resets after panics.
• Use ScopeGuard::elapsed() to get the time spent in a scope.
• Indentation increases with nested scopes and decreases on exit.

Error Handling Utilities

Rust-Loguru provides ergonomic helpers for error handling, context, and panic reporting.

Extension Traits for Result and Option

use rust_loguru::{ResultExt, OptionExt};

fn might_fail() -> Result<(), std::io::Error> {
    Err(std::io::Error::new(std::io::ErrorKind::Other, "fail"))
}

fn main() {
    // Log an error if it occurs
    might_fail().log_error("Failed to do something important");

    // Add context to errors
    let res = might_fail().with_context(|| "while reading config file");
    if let Err(e) = res {
        eprintln!("Error with context: {}", e);
    }

    // Log if an Option is None
    let value: Option<u32> = None;
    value.log_none("Expected a value but got None");
}

Error Chain Extraction

use rust_loguru::{ResultExt, error_chain};

fn main() {
    let res: Result<(), std::io::Error> = Err(std::io::Error::new(std::io::ErrorKind::Other, "fail"));
    let res = res.with_context(|| "while doing something");
    if let Err(e) = res {
        for cause in error_chain(&e) {
            eprintln!("Cause: {}", cause);
        }
    }
}

Panic Hook Installation

use rust_loguru::install_panic_hook;

fn main() {
    install_panic_hook(); // Log all panics with file/line info
    // ... rest of your code ...
}

Source Location and Error Logging Macros

use rust_loguru::{source_location, log_error_with_location};

fn main() {
    let err = "Something went wrong";
    log_error_with_location!(err);
    log_error_with_location!(err, "while processing request");
}

Advanced Usage

Creating Custom Handlers

Implement the Handler trait to create custom handlers:

use rust_loguru::handler::Handler;
use rust_loguru::level::LogLevel;
use rust_loguru::record::Record;
use rust_loguru::formatter::Formatter;

#[derive(Debug)]
struct CustomHandler {
    level: LogLevel,
    enabled: bool,
    formatter: Formatter,
}

impl Handler for CustomHandler {
    fn level(&self) -> LogLevel {
        self.level
    }

    fn set_level(&mut self, level: LogLevel) {
        self.level = level;
    }

    fn enabled(&self) -> bool {
        self.enabled
    }

    fn set_enabled(&mut self, enabled: bool) {
        self.enabled = enabled;
    }

    fn formatter(&self) -> &Formatter {
        &self.formatter
    }

    fn set_formatter(&mut self, formatter: Formatter) {
        self.formatter = formatter;
    }

    fn handle(&mut self, record: &Record) -> bool {
        if !self.enabled || record.level() < self.level {
            return false;
        }
        
        let formatted = self.formatter.format(record);
        // Custom handling logic here
        println!("Custom handler: {}", formatted);
        true
    }
}

Structured Logging with JSON

Use the structured data capability:

use rust_loguru::{Record, LogLevel, log};
use serde_json::json;

let record = Record::new(
    LogLevel::Info,
    "API request completed",
    Some("api_module".to_string()),
    Some("api.rs".to_string()),
    Some(120),
)
.with_structured_data("request", &json!({
    "method": "GET",
    "path": "/users",
    "status": 200,
    "duration_ms": 42
}))
.unwrap();

log(&record);

Advanced Context Usage

Rust-Loguru supports structured, thread-local, and async-propagatable context for logs. This allows you to automatically attach metadata (like user IDs, request IDs, etc.) to every log line in a given scope or async task.

use rust_loguru::{info, debug, context};

fn main() {
    // Add context for the current thread (e.g., user ID)
    let mut ctx = context::ContextMap::new();
    ctx.insert("user_id".to_string(), context::ContextValue::String("alice".to_string()));
    context::push_context(ctx);

    // Log a message; context will be attached if integrated into Record/formatters
    info!("User logged in");

    // Add more context (e.g., request ID) in a nested scope
    let mut req_ctx = context::ContextMap::new();
    req_ctx.insert("request_id".to_string(), context::ContextValue::String("req-123".to_string()));
    context::push_context(req_ctx);

    debug!("Processing request");

    // Pop request context when done
    context::pop_context();

    // Pop user context at the end
    context::pop_context();
}

Async Context Propagation

You can propagate context across async tasks:

use rust_loguru::context;
use std::thread;

let mut ctx = context::ContextMap::new();
ctx.insert("trace_id".to_string(), context::ContextValue::String("abc123".to_string()));
context::push_context(ctx);
let arc_ctx = context::propagate_context_for_async();

thread::spawn(move || {
    context::set_context_from_arc(arc_ctx);
    // ... logging here will see the propagated context ...
});

Performance Considerations

• Log records below the configured level are filtered out early for minimal overhead
• File handlers use buffered I/O for efficient disk operations
• Consider using appropriate log levels in production to minimize overhead

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Integration Features

Rust-Loguru provides an integration module for compatibility and middleware with other logging systems and frameworks. This module is designed for advanced use cases where you want to:

• Use Rust-Loguru as the backend for the log crate
• Integrate with async runtimes (e.g., spawn log flushing tasks in tokio)
• Add middleware for web frameworks (e.g., request/response logging)

Log Crate Compatibility

Rust-Loguru can act as the backend for the log crate. This allows you to use the standard log macros (log::info!, log::warn!, etc.) and have them routed through Rust-Loguru.

use rust_loguru::integration::log_compat;
use log::info;

fn main() {
    // Set up your logger as usual
    // ...
    log_compat::init_loguru_as_log();
    info!("This message goes through Rust-Loguru!");
}

Async Runtime Integration (Tokio)

Rust-Loguru can integrate with async runtimes like Tokio to spawn background tasks for log management.

Requires the tokio feature.

use rust_loguru::integration::async_runtime;

#[tokio::main]
async fn main() {
    // This will spawn a background task for log management (e.g., flushing)
    async_runtime::integrate_with_tokio().await;
    // ... your async code ...
}

Framework Middleware (Web Frameworks)

use rust_loguru::integration::middleware;

fn main() {
    // This will eventually provide request/response logging middleware for web frameworks
    // Currently, this will panic with an unimplemented message
    middleware::request_response_logging();
}

Test Utilities

Rust-Loguru provides a set of test utilities to help you capture logs, assert on log output, and use mock loggers in your tests. These are available in the rust_loguru::test_utils module.

Log Capture

You can capture log records during tests and inspect them:

use rust_loguru::test_utils::LogCapture;
use rust_loguru::{LogLevel, Record};

let capture = LogCapture::new();
let record = Record::new(LogLevel::Info, "test message", None, None, None);
capture.handle(&record);
assert!(capture.contains_message("test message"));
assert!(capture.contains_level(LogLevel::Info));

Assertion Macros

Rust-Loguru provides macros to assert that a log capture contains a message or a log level:

use rust_loguru::test_utils::LogCapture;
use rust_loguru::{LogLevel, Record};
use rust_loguru::{assert_log_contains, assert_log_level};

let capture = LogCapture::new();
let record = Record::new(LogLevel::Warning, "something happened", None, None, None);
capture.handle(&record);
assert_log_contains!(capture, "something happened");
assert_log_level!(capture, LogLevel::Warning);

Mock Logger

A mock logger is provided for testing code that expects a logger:

use rust_loguru::test_utils::MockLogger;
use rust_loguru::{LogLevel, Record};

let logger = MockLogger::new(LogLevel::Debug);
let record = Record::new(LogLevel::Info, "mocked log", None, None, None);
logger.log(&record);
assert!(logger.capture.contains_message("mocked log"));

Temporary Log Level Adjustment

You can temporarily set the log level for a logger in a test:

use rust_loguru::test_utils::TempLogLevel;
use rust_loguru::{LogLevel, Record};

struct MyLogger { level: LogLevel }
impl MyLogger {
    fn set_level(&mut self, level: LogLevel) { self.level = level; }
}
impl rust_loguru::logger::Logger for MyLogger {
    fn log(&self, _record: &Record) -> bool { true }
    fn level(&self) -> LogLevel { self.level }
}

let mut logger = MyLogger { level: LogLevel::Info };
{
    let _temp = TempLogLevel::new(
        &mut logger,
        LogLevel::Debug,
        |logger, level| logger.set_level(level),
        |logger| logger.level(),
    );
    assert_eq!(logger.level(), LogLevel::Debug);
}
assert_eq!(logger.level(), LogLevel::Info);

TODO / Roadmap

The following is the prioritized development plan:

1. Performance Improvements

   • Adopt the Zero Overhead of slog to bring down the performance numbers down

2. File Handler Enhancements

   • Time-based rotation (daily, hourly, etc.)
   • Retention policies (max age, max files, cleanup of old logs)
   • File permissions (configurable on creation)
   • Async file writing (true async I/O, not just async logging queue)

3. Configuration System Upgrades

   • Environment variable overrides (e.g., RUST_LOGURU_LEVEL=debug)
   • File-based configuration (TOML/YAML/JSON config loading)
   • Preset configurations (easy-to-use, opinionated defaults for common scenarios)

4. Integration & Extensibility

   • Async runtime integration (fully implement tokio/async-std support, e.g., log flushing, context propagation)
   • Framework middleware (request/response logging for actix, axum, etc.)
   • Network/HTTP/in-memory handlers (implement or stub with clear errors/documentation)

5. Advanced Handler Features

   • Batching for all handlers (not just file, but also network, etc.)
   • Handler-specific filtering (allow each handler to filter by level, target, etc.)
   • Compression options (support for gzip, zip, etc. for rotated files)

6. Context & Scope Improvements

   • Panic/exception capture in scopes (log panics with context and stack trace)
   • Async scope support (ensure scopes work seamlessly with async/await)

7. Documentation & Cleanup

   • Remove legacy files (e.g., src/formatter.rs)
   • Document stubbed/unimplemented features (make it clear what is and isn't available)
   • Update README and module docs to reflect new features and usage patterns

8. Optional/Bonus

   • File permission control for log files
   • Support for emojis/symbols in all formatters
   • More built-in format templates
   • Integration with external services (CloudWatch, Elasticsearch, etc.)

---

Contributions to any of these areas are welcome! See the issues tracker for more details or to discuss implementation approaches.

License

This project is licensed under MIT of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)