logly

High-performance, production-ready structured logging library for Rust

📚 Documentation | API Reference | Quick Start

Overview

logly-rs is a high-performance, production-ready structured logging library for Rust with async support, GPU acceleration, rotation, filtering, callbacks, and comprehensive error handling.

🚀 Core Features

• 8 Log Levels: TRACE (5), DEBUG (10), INFO (20), SUCCESS (25), WARNING (30), ERROR (40), FAIL (45), CRITICAL (50)
• Custom Log Levels: Add your own levels with custom priorities and colors
• Structured Logging: JSON and custom format support
• Context Binding: Persistent and temporary context fields
• Out-of-Box Ready: Works immediately with auto-sink enabled by default

⚡ Performance & Scalability

• Async Logging: Non-blocking writes with configurable buffers
• GPU/CUDA Support: Optional GPU acceleration (compile with --features gpu)
• Thread-Safe: Lock-free operations with concurrent logging support
• Zero-Copy: Efficient memory management
• High Throughput: 13,000+ operations per second

📝 Output Management

• Multiple Sinks: Console, file, and custom outputs
• Auto-Sinks: Automatic sink initialization (enabled by default)
• Manual Sink Management: Full control over sink lifecycle
• File Rotation: Time-based (hourly, daily, weekly, monthly, yearly) and size-based rotation
• Retention Policies: Automatic cleanup of old log files
• Global Controls: Enable/disable console display and file storage globally

🔧 Filtering & Formatting

• Level Filtering: Filter by minimum log level
• Module/Function Filtering: Target specific code sections
• Custom Formatters: Template-based formatting with placeholders
• Colored Output: ANSI colors with custom color callbacks
• Custom Time Formats: YYYY-MM-DD HH:mm:ss.SSS patterns

🎯 Advanced Features

• Callbacks: Log callbacks, color callbacks, exception callbacks
• Exception Handling: Comprehensive error handling with backtraces
• Auto-Update Check: Checks for new versions automatically (enabled by default)
• Debug Mode: Detailed internal logging for troubleshooting
• Runtime Configuration: Change all settings at runtime
• Enable/Disable: Toggle logging on/off without removing sinks

Installation

Add to your Cargo.toml:

[dependencies]
logly = "0.0.4"

# With GPU support (experimental)
logly = { version = "0.0.4", features = ["gpu"] }

Quick Start

use logly::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let logger = Logger::new();
    logger.add_sink(SinkConfig::default())?;
    
    logger.info("Application started".to_string())?;
    logger.success("Operation completed!".to_string())?;
    logger.warning("Warning message".to_string())?;
    logger.error("Error occurred".to_string())?;
    
    Ok(())
}

Performance Benchmarks

Real benchmark results from criterion (measured on your system):

Benchmarks run with criterion on Windows. Times include formatting, serialization, and I/O.

Performance Characteristics

• Memory: <1MB base overhead
• CPU: Minimal impact with async writes
• Latency: Sub-millisecond for most operations
• Scalability: Linear scaling up to 10 threads

See Performance Guide for optimization techniques.

Platform Support

• ✅ Windows: Full support (tested on Windows 11)
• ✅ Linux: Full support (Ubuntu 20.04+)
• ✅ macOS: Full support (macOS 11+)
• ⚠️ GPU: Requires CUDA toolkit (Linux/Windows only)

Advanced Usage

File Logging with Rotation

use logly::prelude::*;
use std::path::PathBuf;

let logger = Logger::new();

let config = SinkConfig {
    path: Some(PathBuf::from("logs/app.log")),
    rotation: Some("daily".to_string()),
    size_limit: Some(10 * 1024 * 1024), // 10MB
    retention: Some(7), // Keep 7 files
    async_write: true,
    ..Default::default()
};

logger.add_sink(config)?;

Custom Log Levels

// Add custom level with priority between WARNING (30) and ERROR (40)
logger.add_custom_level("NOTICE".to_string(), 35, "96".to_string())?;

// Use custom level
logger.log_custom("NOTICE", "Custom level message".to_string())?;

Callbacks

// Log callback for monitoring
logger.add_log_callback(|record| {
    if record.level >= Level::Error {
        println!("High severity: {}", record.message);
    }
    Ok(())
});

// Custom color callback
logger.add_color_callback(|level, message| {
    format!("\x1b[1m[{}]\x1b[0m {}", level.as_str(), message)
});

// Exception callback
logger.add_exception_callback(|error, backtrace| {
    eprintln!("Exception: {}\n{}", error, backtrace);
});

Context Binding

// Bind persistent context
logger.bind("user_id".to_string(), serde_json::json!("12345"));
logger.bind("session".to_string(), serde_json::json!("abc-def"));

logger.info("User action logged".to_string())?;

// Remove binding
logger.unbind("user_id");

// Clear all bindings
logger.clear_bindings();

GPU Acceleration

let mut config = LoggerConfig::default();
config.enable_gpu = true;
config.gpu_buffer_size = 2 * 1024 * 1024; // 2MB

logger.configure(config);
logger.enable_gpu()?;

println!("{}", logger.gpu_info());

Configuration

Basic Configuration

let mut config = LoggerConfig::default();
config.level = Level::Debug;
config.color = true;
config.json = false;
logger.configure(config);

Configuration File

Create logly.toml:

[logly.configuration]
level = "DEBUG"
auto_sink = true

[logly.display]
color = true
global_console_display = true
global_file_storage = true

[logly.features]
enable_callbacks = true
enable_exception_handling = true
enable_version_check = true

See Configuration Guide for all options.

Documentation

Full documentation available at: https://muhammad-fiaz.github.io/logly-rs

Getting Started

• Installation Guide - Complete installation instructions
• Quick Start - Get started in minutes
• Configuration Guide - Complete configuration reference

Feature Guides

• Log Levels - All 8 levels and custom levels
• Sinks - Multiple sinks, auto-sinks, manual management
• Rotation & Retention - File rotation (hourly to yearly)
• Configuration File - logly.toml support
• Template Formatting - Custom time formats and placeholders
• Callbacks - Log, color, and exception callbacks
• GPU Support - GPU/CUDA acceleration
• Troubleshooting - Common issues and solutions
• Performance - Optimization techniques

Project Information

• Changelog - Release history and changes
• Contributing - How to contribute
• License - MIT License
• Code of Conduct - Community guidelines

Examples

Run the examples:

# Basic usage
cargo run --example basic

# Advanced features
cargo run --example advanced

# Complete configuration
cargo run --example configuration

# GPU logging (requires CUDA)
cargo run --example gpu_logging --features gpu

# Callbacks and custom colors
cargo run --example callbacks

# File rotation
cargo run --example rotation

# Custom log levels
cargo run --example custom_levels

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_level_priority

# Run benchmarks
cargo bench

Error Reporting

If you encounter any bugs or issues:

• Rust crate: https://github.com/muhammad-fiaz/logly-rs/issues
• Python package: https://github.com/muhammad-fiaz/logly/issues

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Repository

• Rust: https://github.com/muhammad-fiaz/logly-rs
• Python: https://github.com/muhammad-fiaz/logly

Version

Current version: 0.0.4

See CHANGELOG.md for release history.

Check for updates:

if let Ok(Some(msg)) = logger.check_version() {
    println!("{}", msg);
}

Author

muhammad-fiaz