Logly Configuration Guide

Out-of-the-Box Usage

Logly works immediately without any configuration:

#![allow(unused)]
fn main() {
use logly::prelude::*;

let logger = Logger::new();
// Auto-sink is enabled by default - logs to console
logger.info("Works out of the box!".to_string())?;
}

Global Configuration Options

LoggerConfig Structure

The LoggerConfig struct contains all configuration options:

pub struct LoggerConfig {
    // Log level filtering
    pub level: Level,                              // Minimum log level (default: Info)
    
    // Global display controls
    pub global_color_display: bool,                // Enable/disable colors globally (default: true)
    pub global_console_display: bool,              // Enable/disable console output (default: true)
    pub global_file_storage: bool,                 // Enable/disable file storage (default: true)
    
    // Color settings
    pub color: bool,                               // Enable colors (default: true)
    pub level_colors: HashMap<Level, String>,      // Per-level color codes
    
    // Custom levels
    pub custom_levels: HashMap<String, CustomLevel>, // User-defined levels
    
    // Output format
    pub json: bool,                                // JSON output (default: false)
    pub pretty_json: bool,                         // Pretty-print JSON (default: false)
    pub log_compact: bool,                         // Compact format (default: false)
    
    // Display options
    pub console: bool,                             // Console output (default: true)
    pub show_time: bool,                           // Show timestamp (default: true)
    pub show_module: bool,                         // Show module name (default: true)
    pub show_function: bool,                       // Show function name (default: true)
    pub show_filename: bool,                       // Show filename (default: false)
    pub show_lineno: bool,                         // Show line number (default: false)
    
    // Per-level controls
    pub console_levels: HashMap<Level, bool>,      // Per-level console output
    pub time_levels: HashMap<Level, bool>,         // Per-level timestamp display
    pub color_levels: HashMap<Level, bool>,        // Per-level color enable
    pub storage_levels: HashMap<Level, bool>,      // Per-level file storage
    
    // Sink management
    pub auto_sink: bool,                           // Auto-initialize console sink (default: true)
    
    // GPU support (experimental)
    pub enable_gpu: bool,                          // Enable GPU acceleration (default: false)
    pub gpu_buffer_size: usize,                    // GPU buffer size (default: 1MB)
    
    // Features
    pub enable_callbacks: bool,                    // Enable callback system (default: true)
    pub enable_exception_handling: bool,           // Enable exception handling (default: true)
    pub enable_version_check: bool,                // Enable auto-update check (default: true)
    
    // Debug mode
    pub debug_mode: bool,                          // Enable debug logging (default: false)
    pub debug_log_file: Option<PathBuf>,           // Debug log file path (default: None = stderr)
}

Configuration Examples

1. Default Configuration (Out of Box)

#![allow(unused)]
fn main() {
let logger = Logger::new();
// Auto-sink enabled, logs to console with colors
logger.info("Ready to use!".to_string())?;
}

2. Console Only (No File Storage)

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.global_console_display = true;   // Console enabled
config.global_file_storage = false;     // No file storage

logger.configure(config);
logger.info("Console only".to_string())?;
}

3. File Storage Only (No Console)

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.global_console_display = false;  // No console
config.global_file_storage = true;      // File storage enabled
config.auto_sink = false;               // Disable auto-sink

logger.configure(config);

// Add file sink manually
logger.add_sink(SinkConfig {
    path: Some(PathBuf::from("app.log")),
    ..Default::default()
})?;

logger.info("File only".to_string())?;
}

4. No Output (Silent Mode)

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.global_console_display = false;  // No console
config.global_file_storage = false;     // No file storage

logger.configure(config);
logger.info("Not displayed or stored".to_string())?;
}

5. Debug Mode with File Logging

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.debug_mode = true;
config.debug_log_file = Some(PathBuf::from("logly_debug.log"));

logger.configure(config);
// All logly internal operations logged to logly_debug.log
}

6. Custom Colors

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.level_colors.insert(Level::Info, "92".to_string());    // Bright green
config.level_colors.insert(Level::Error, "91".to_string());   // Bright red

logger.configure(config);
}

7. Disable Colors Globally

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.global_color_display = false;

logger.configure(config);
}

8. JSON Output

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.json = true;
config.pretty_json = true;

logger.configure(config);
}

File Rotation Configuration

Rotation Intervals

hourly - Rotate every hour
daily - Rotate every day
weekly - Rotate every week
monthly - Rotate every 30 days
yearly - Rotate every 365 days

Size-Based Rotation

#![allow(unused)]
fn main() {
SinkConfig {
    path: Some(PathBuf::from("app.log")),
    size_limit: Some(10 * 1024 * 1024),  // 10MB
    retention: Some(5),                   // Keep 5 files
    ..Default::default()
}
}

Time-Based Rotation

#![allow(unused)]
fn main() {
SinkConfig {
    path: Some(PathBuf::from("app.log")),
    rotation: Some("daily".to_string()),
    retention: Some(7),  // Keep 7 days
    ..Default::default()
}
}

Combined Rotation

#![allow(unused)]
fn main() {
SinkConfig {
    path: Some(PathBuf::from("app.log")),
    rotation: Some("daily".to_string()),
    size_limit: Some(10 * 1024 * 1024),  // Rotate if daily OR 10MB
    retention: Some(7),
    ..Default::default()
}
}

Yearly Rotation Example

#![allow(unused)]
fn main() {
SinkConfig {
    path: Some(PathBuf::from("yearly.log")),
    rotation: Some("yearly".to_string()),
    retention: Some(5),  // Keep 5 years
    ..Default::default()
}
}

Runtime Configuration Changes

All configuration can be changed at runtime:

#![allow(unused)]
fn main() {
// Initial configuration
let mut config = LoggerConfig::default();
config.level = Level::Info;
logger.configure(config);

logger.info("Info message".to_string())?;

// Change at runtime
let mut new_config = LoggerConfig::default();
new_config.level = Level::Warning;
logger.configure(new_config);

logger.info("Not shown (below WARNING)".to_string())?;
logger.warning("Shown".to_string())?;
}

Enable/Disable at Runtime

#![allow(unused)]
fn main() {
logger.enable();
logger.info("Logged".to_string())?;

logger.disable();
logger.info("Not logged".to_string())?;

logger.enable();
logger.info("Logged again".to_string())?;
}

Auto-Sink Behavior

By default, auto_sink is enabled:

#![allow(unused)]
fn main() {
let logger = Logger::new();
// Automatically has a console sink
logger.info("Works immediately!".to_string())?;
}

Disable auto-sink for manual control:

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.auto_sink = false;
logger.configure(config);

// Now you must add sinks manually
logger.add_sink(SinkConfig::default())?;
}

Global Settings Interaction

Priority Rules

If global_console_display = false AND global_file_storage = false:
- No output anywhere (silent mode)
If global_console_display = true AND global_file_storage = false:
- Console output only, no file storage
If global_console_display = false AND global_file_storage = true:
- File storage only, no console output
If both are true:
- Both console and file storage work normally

Example: Console Display Control

#![allow(unused)]
fn main() {
// Enable console
config.global_console_display = true;
logger.configure(config);
logger.info("Shows on console".to_string())?;

// Disable console
config.global_console_display = false;
logger.configure(config);
logger.info("Not shown on console".to_string())?;
}

Example: File Storage Control

#![allow(unused)]
fn main() {
// Enable file storage
config.global_file_storage = true;
logger.configure(config);
logger.add_sink(SinkConfig {
    path: Some(PathBuf::from("app.log")),
    ..Default::default()
})?;
logger.info("Stored in file".to_string())?;

// Disable file storage
config.global_file_storage = false;
logger.configure(config);
logger.info("Not stored in file".to_string())?;
}

Version Checking

Enabled by default:

#![allow(unused)]
fn main() {
// Check for updates
if let Ok(Some(msg)) = logger.check_version() {
    println!("{}", msg);
}

// Disable version checking
let mut config = LoggerConfig::default();
config.enable_version_check = false;
logger.configure(config);
}

GPU Support (Experimental)

GPU support is optional and requires compilation with --features gpu:

#![allow(unused)]
fn main() {
let mut config = LoggerConfig::default();
config.enable_gpu = true;
config.gpu_buffer_size = 2 * 1024 * 1024;  // 2MB

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

Complete Example

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let logger = Logger::new();
    
    let mut config = LoggerConfig::default();
    
    // Global controls
    config.global_color_display = true;
    config.global_console_display = true;
    config.global_file_storage = true;
    
    // Log level
    config.level = Level::Debug;
    
    // Display options
    config.show_time = true;
    config.show_module = true;
    
    // Features
    config.enable_callbacks = true;
    config.enable_exception_handling = true;
    config.enable_version_check = true;
    config.debug_mode = false;
    
    // Auto-sink
    config.auto_sink = true;
    
    logger.configure(config);
    
    // Add file sink with rotation
    logger.add_sink(SinkConfig {
        path: Some(PathBuf::from("logs/app.log")),
        rotation: Some("daily".to_string()),
        size_limit: Some(10 * 1024 * 1024),
        retention: Some(7),
        ..Default::default()
    })?;
    
    // Use logger
    logger.debug("Debug message".to_string())?;
    logger.info("Info message".to_string())?;
    logger.warning("Warning message".to_string())?;
    logger.error("Error message".to_string())?;
    
    Ok(())
}

Summary

✅ Works out of box with auto-sink
✅ Global console display control
✅ Global file storage control
✅ All rotation intervals (hourly to yearly)
✅ Runtime configuration changes
✅ Enable/disable at runtime
✅ Debug mode with file logging
✅ Auto-update checking (enabled by default)
✅ Full customization of all features
✅ Professional production-ready configuration

Keyboard shortcuts

Logly-rs Documentation