Adding `FreedomLogger` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add FreedomLogger

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

FreedomLogger = "1.1.0"

The FreedomLogger library will be automatically available globally. Read the FreedomLogger library documentation.

Back to the crate overview.

Readme

FreedomLogger 🦀

A professional, thread-safe logging library for Rust with automatic rotation, multiple output formats, and error-proof operation.

✨ Features

Multiple log levels with filtering (ERROR, WARNING, INFO, DEBUG, TRACE)
Flexible logging API - Both simple functions and formatted macros
Various output patterns from basic to JSON structured logging
Automatic log rotation based on configurable file size limits
Thread-safe concurrent logging with internal synchronization
Error-proof operation - internal errors never crash your application
Minimal dependencies - only chrono for timestamps
Easy initialization - single function call setup

🚀 Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
freedom_logger = "1.1.0"

Or use cargo:

cargo add freedom_logger

Basic usage:

use freedom_logger::{log_init, log_info, log_warning, log_error, Pattern};

fn main() {
    // Initialize logger once
    log_init(Pattern::Basic, "./logs", "myapp");
    
    // Log anywhere in your application
    log_info("Application started");
    log_warning("This is a warning");
    log_error("Something went wrong");
}

🆕 New in v1.1.0: Formatted Logging Macros

FreedomLogger now supports both simple functions and powerful formatting macros:

Simple Functions (Original)

use freedom_logger::{log_error, log_warning, log_info, log_debug, log_trace};

log_error("Critical system failure");
log_warning("Deprecated API usage detected");
log_info("User authentication successful");
log_debug("Processing request payload");
log_trace("Entering function calculate_metrics");

New Formatting Macros

use freedom_logger::{log_error, log_warning, log_info, log_debug, log_trace};

// Support for formatted strings with automatic type handling
log_info!("User {} logged in successfully", username);
log_debug!("Database path: {:?}", database_path);  // Works with any Debug type!
log_error!("Failed to connect to {}: {}", host, error_message);
log_warning!("Processing {} items in batch {}", item_count, batch_id);

// Complex types work automatically
let config = MyConfig { host: "localhost", port: 5432 };
log_debug!("Server config: {:?}", config);

// Multiple format specifiers
log_info!("User {} from {} logged in at {}", user_id, ip_address, timestamp);

Why Use the Macros?

Before v1.1.0 (would cause compilation errors):

let database_path = PathBuf::from("/var/lib/app.db");
log_debug("Database path: {:?}", database_path); // ❌ Error!

After v1.1.0 (works perfectly):

let database_path = PathBuf::from("/var/lib/app.db");
log_debug!("Database path: {:?}", database_path); // ✅ Perfect!

📋 Initialization Options

Basic Setup

use freedom_logger::{log_init, Pattern};

// Logs all levels, 10MB files, 5 backups
log_init(Pattern::Basic, "/var/log/myapp", "application");

With Log Level Filtering

use freedom_logger::{log_init_with_level, Pattern, LogLevel};

// Only log WARNING and ERROR messages
log_init_with_level(Pattern::Detailed, "./logs", "app", LogLevel::Warning);

Full Configuration

use freedom_logger::{log_init_with_rotation, Pattern, LogLevel};

// 50MB files, keep 10 backups
log_init_with_rotation(
    Pattern::Json,
    "./logs",
    "service",
    LogLevel::Info,
    50 * 1024 * 1024, // 50MB
    10 // 10 backup files
);

📝 Output Formats

Basic Pattern

[2025-09-09 14:30:45] INFO: User logged in successfully
[2025-09-09 14:30:46] ERROR: Database connection failed

Detailed Pattern (with source location)

[2025-09-09 14:30:45] [main.rs:42] INFO: User logged in successfully
[2025-09-09 14:30:46] [db.rs:158] ERROR: Database connection failed

JSON Pattern (structured logging)

{"timestamp":"2025-09-09 14:30:45","level":"INFO","message":"User logged in successfully","file":"main.rs","line":42,"thread":"main"}
{"timestamp":"2025-09-09 14:30:46","level":"ERROR","message":"Database connection failed","file":"db.rs","line":158,"thread":"worker-1"}

🔄 Automatic Log Rotation

FreedomLogger automatically rotates log files when they exceed the configured size:

app.log      (current log file)
app.1.log    (most recent backup)
app.2.log    (older backup)
app.N.log    (oldest backup, deleted when limit reached)

Default settings: 10MB max file size, 5 backup files retained.

🛡️ Error-Proof Operation

FreedomLogger is designed to be error-proof:

Never panics - Internal errors are handled gracefully
Silent operation - Logging failures don't interrupt your application
Separate error log - Internal issues logged to logger_errors.log
Automatic fallbacks - Invalid configurations use safe defaults
Directory creation - Creates log directories automatically

🧵 Thread Safety

FreedomLogger is fully thread-safe:

use std::thread;
use freedom_logger::{log_init, Pattern};

fn main() {
    log_init(Pattern::Basic, "./logs", "threaded_app");
    
    let handles: Vec<_> = (0..10)
        .map(|i| {
            thread::spawn(move || {
                // Both styles work in threads
                log_info!("Message from thread {}", i);
                log_debug!("Thread {} processing data: {:?}", i, some_data);
            })
        })
        .collect();
    
    for handle in handles {
        handle.join().unwrap();
    }
}

📊 Configuration Quick Reference

Function	Log Level	Rotation	Use Case
`log_init()`	All levels	Default (10MB, 5 backups)	Development, testing
`log_init_with_level()`	Filtered	Default (10MB, 5 backups)	Production with filtering
`log_init_with_rotation()`	Filtered	Custom	High-volume production

📈 Log Levels

ERROR - Critical failures, system errors
WARNING - Potential issues, deprecated usage
INFO - General application flow information
DEBUG - Detailed debugging information
TRACE - Very verbose tracing information

🎨 Available Patterns

Basic - Simple timestamp, level, message format
Detailed - Includes source file and line number
Extended - Adds thread information (planned)
JSON - Structured logging for analysis tools
Custom - User-defined format strings (planned)

📁 File Extensions

FreedomLogger automatically uses appropriate file extensions:

Text patterns (Basic, Detailed, Extended, Custom) → .log files
JSON pattern → .json files

⚡ Performance

Buffered I/O - Uses BufWriter for optimal write performance
Minimal allocations - Efficient string formatting and memory usage
Thread synchronization - Mutex-protected writes prevent data corruption
Lazy initialization - Logger components created only when needed

📚 Examples

Complete examples are available in the examples/ directory:

# Basic logging example
cargo run --example basic_usage

# JSON structured logging  
cargo run --example json_logging

# High-volume logging with rotation
cargo run --example rotation_demo

# NEW: Formatted logging examples
cargo run --example formatted_logging

📋 Requirements

Rust 1.70 or later
Dependencies: chrono (timestamps), tempfile (dev/testing only)

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🛣️ Roadmap

v2.0.0 (Planned)

Database integration for direct log storage
Time-based rotation (daily, weekly, monthly)
Async logging for high-performance applications
Enhanced caller location tracking
Full custom pattern parsing

Ongoing

Bug fixes and performance improvements
Additional output formats
Extended platform support

📄 License

Licensed under the MIT License.

See CHANGELOG for detailed version history.

🔗 Links

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs.rs/freedom_logger

Built with Rust for performance, safety, and reliability. 🦀

Adding FreedomLogger library as a dependency

Adding `FreedomLogger` library as a dependency