Crate firo_logger

firo_logger

A high-performance, feature-rich logger for Rust applications with colored output, structured logging, file rotation, async logging, and advanced configuration.

Features

• Colored console output with customizable colors
• Structured logging with JSON format support
• File logging with rotation (size-based and time-based)
• Async logging for high-performance applications
• Level filtering with module-specific filters
• Thread-safe with minimal overhead
• Caller information (file, line, module)
• Custom metadata support
• Environment configuration support
• Builder pattern for easy configuration

Quick Start

use firo_logger::{init_default, log_info, log_error, log_success};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the logger with default settings
    init_default()?;

    // Log some messages
    log_info!("Application started").unwrap();
    log_success!("Configuration loaded successfully").unwrap();
    log_error!("Failed to connect to database: {}", "Connection timeout").unwrap();

    Ok(())
}

Configuration

use firo_logger::{LoggerConfig, LogLevel, OutputFormat, init, log_info};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = LoggerConfig::builder()
        .level(LogLevel::Debug)
        .format(OutputFormat::Json)
        .console(true)
        .colors(true)
        .file("app.log")
        .rotate_by_size(10 * 1024 * 1024, 5) // 10MB, keep 5 files
        .async_logging(1000)
        .include_caller(true)
        .include_thread(true)
        .metadata("app", "my-app")
        .metadata("version", "1.0.0")
        .build();

    init(config)?;

    log_info!("Logger initialized with custom configuration").unwrap();

    Ok(())
}

Environment Configuration

The logger can be configured using environment variables:

• FIRO_LOG_LEVEL: Set log level (ERROR, WARNING, INFO, SUCCESS, DEBUG)
• FIRO_LOG_FILE: Set log file path
• FIRO_LOG_FORMAT: Set output format (text, json, plain)
• NO_COLOR: Disable colored output
• FORCE_COLOR: Force colored output even when not in a terminal

use firo_logger::{init_from_env, log_info};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_from_env()?;
    log_info!("Logger configured from environment").unwrap();
    Ok(())
}

Advanced Usage

Structured Logging with Metadata

use firo_logger::{log_with_metadata, LogLevel};

log_with_metadata!(
    LogLevel::Info,
    "User login",
    "user_id" => "12345",
    "ip_address" => "192.168.1.100",
    "user_agent" => "Mozilla/5.0...",
);

Conditional and Rate-Limited Logging

use firo_logger::{log_if, log_rate_limited, LogLevel};
use std::time::Duration;

let debug_mode = std::env::var("DEBUG").is_ok();
log_if!(debug_mode, LogLevel::Debug, "Debug mode is enabled");

// Rate-limited logging (max once per second)
for i in 0..1000 {
    log_rate_limited!(Duration::from_secs(1), LogLevel::Info, "Processing item {}", i);
}

Function Tracing

use firo_logger::trace_function;

fn process_data(data: &[u8]) -> Result<(), std::io::Error> {
    trace_function!("process_data", data.len());
    // Function implementation...
    Ok(())
}

Performance Timing

use firo_logger::{time_block, LogLevel};

let result = time_block!(LogLevel::Info, "Database query", {
    // Your expensive operation here
    std::thread::sleep(std::time::Duration::from_millis(100));
    "query result"
});

Re-exports

pub use config::Colors;

pub use config::ConsoleConfig;

pub use config::FileConfig;

pub use config::LogLevel;

pub use config::LoggerConfig;

pub use config::LoggerConfigBuilder;

pub use config::OutputFormat;

pub use config::RotationConfig;

pub use config::RotationFrequency;

pub use error::LoggerError;

pub use error::Result;

pub use formatters::CallerInfo;

pub use formatters::Formatter;

pub use formatters::LogRecord;

pub use formatters::ThreadInfo;

pub use logger::config;

pub use logger::current_logger;

pub use logger::flush;

pub use logger::init;

pub use logger::init_default;

pub use logger::init_from_env;

pub use logger::is_initialized;

pub use logger::log_debug;

pub use logger::log_error;

pub use logger::log_info;

pub use logger::log_success;

pub use logger::log_warning;

pub use logger::log_with_caller;

pub use logger::logger;

pub use logger::stats;

pub use logger::with_scoped_logger;

pub use logger::LoggerInstance;

pub use logger::LoggerStats;

Modules

config

Configuration system for firo_logger.

error

Error types for the firo_logger crate.

formatters

Formatters for different log output formats.

legacy

Legacy compatibility module for the old firo_logger API.

logger

Core logger implementation with async support and dual singleton/instance pattern.

macros

Convenient macros for logging.

utils

Utility functions for common logging patterns.

writers

Writers for different log output destinations.

Macros

log

Logs a message with a specific level.

log_assert

Assert macro that logs the assertion failure.

log_at_most

Logs at most N times per program execution.

log_debug

Logs a debug message.

log_debug_assert

Debug assert macro that only works in debug builds and logs failures.

log_error

Logs an error message.

log_error_and_return

Logs an error and returns the error for further handling.

log_if

Conditional logging macro that only logs if a condition is true.

log_info

Logs an info message.

log_once

Logs once per program execution.

log_rate_limited

Logs with a specific rate limit (maximum once per duration).

log_success

Logs a success message.

log_warning

Logs a warning message.

log_with_metadata

Logs a message with metadata.

time_block

Times a block of code and logs the execution time.

trace_function

Logs entry and exit of a function.