Loglet 1.0.0

Loglet

A high-performance, lightweight logging library for .NET with asynchronous writing and minimal blocking.

Overview

Loglet is a simple yet powerful logging framework designed for high-throughput applications. It features:

• Asynchronous Logging: Non-blocking log writes using a background queue processor
• Minimal Overhead: Lightweight implementation with cached operations to reduce performance impact
• Multiple Log Levels: Support for DEBUG, INFO, WARNING, and ERROR levels
• Automatic Log Rotation: Daily log files with automatic cleanup of old logs
• Exception Handling: Comprehensive exception logging with stack traces and inner exceptions
• Thread-Safe: Safe for concurrent logging from multiple threads

Features

Asynchronous Processing

Logs are queued and written asynchronously in the background, ensuring your application code never blocks waiting for disk I/O operations. If the queue becomes full, there's an automatic fallback to synchronous writing.

Auto-Cleanup

Automatically removes log files older than a configurable number of days, helping manage disk space without manual intervention.

Lazy Initialization

Expensive operations like assembly information retrieval and path resolution are cached using lazy evaluation for optimal performance.

Exception Logging

Dedicated Error(Exception) method that captures the full exception context including stack traces and inner exceptions.

Installation

Install Loglet via NuGet Package Manager:

dotnet add package Loglet

Or using the Package Manager Console:

Install-Package Loglet

Quick Start

Basic Usage

using Loglet;

// Create a logger instance
var logger = new LogManager();

// Log messages at different levels
logger.Debug("Debug message");
logger.Info("Application started");
logger.Warning("This is a warning");
logger.Error("An error occurred");

// Log exceptions
try
{
    // Your code here
}
catch (Exception ex)
{
    logger.Error(ex);
}

// Cleanup
logger.Dispose();

Configuration

var logger = new LogManager()
{
    // Set the log folder (default: "logs")
    LogFolder = "myapp_logs",

    // Set minimum log level (default: DEBUG)
    MinLogLevel = LogLevel.INFO,

    // Enable/disable automatic log cleanup (default: true)
    AutoDeleteLogs = true,

    // Delete logs older than X days (default: 14)
    DeleteLogsAfterXDays = 7
};

// Custom filename template
logger.FileNameTemplate = "MyApp_{0:yyyyMMdd}.log";

Custom Log File Names

By default, log files are named using the application's product name and date:

MyApplication_20240115.log

You can customize the template:

logger.FileNameTemplate = "custom_log_{0:yyyyMMdd}.log";

When set to null, the default template with the current date is used.

Log Levels

Loglet supports four log levels:

• DEBUG: Detailed diagnostic information (lowest priority)
• INFO: General informational messages
• WARNING: Warning messages for potentially problematic situations
• ERROR: Error messages for critical failures (highest priority)

The MinLogLevel property filters logs - only messages at or above the configured level are logged.

API Reference

Main Methods

void Info(string message)

Logs an informational message.

void Debug(string message)

Logs a debug message.

void Warning(string message)

Logs a warning message.

void Error(string message)

Logs an error message.

void Error(Exception ex)

Logs an exception with its full context (message, stack trace, and inner exceptions).

void Write(LogLevel logLevel, string message)

Logs a message at the specified log level.

void Flush(int timeoutMs = 5000)

Flushes all pending logs and waits for completion. Useful before application shutdown to ensure all logs are written.

void ClearLogFolder()

Manually removes log files older than DeleteLogsAfterXDays. Called automatically when AutoDeleteLogs is enabled.

Properties

Log File Format

Each log entry follows this format:

2024-01-15 10:30:45.123	INFO	Application started
2024-01-15 10:30:46.456	ERROR	An error occurred

Fields are tab-separated:

• Timestamp: yyyy-MM-dd HH:mm:ss.fff
• Level: Log level (DEBUG, INFO, WARNING, ERROR)
• Message: The log message

Advanced Usage

Exception Logging with Inner Exceptions

try
{
    // Outer exception
    try
    {
        // Inner exception
        throw new InvalidOperationException("Inner error");
    }
    catch (Exception innerEx)
    {
        throw new ApplicationException("Outer error", innerEx);
    }
}
catch (Exception ex)
{
    logger.Error(ex);  // Logs both outer and inner exceptions
}

Graceful Shutdown

// Ensure all pending logs are written before shutdown
logger.Flush(timeoutMs: 5000);
logger.Dispose();

Custom Log Writing

// Write directly with a specific log level
logger.Write(LogLevel.WARNING, "Custom log message");

Performance Characteristics

• Queue-Based Processing: Log entries are queued (max capacity: 1000) and processed in the background
• Cached Operations: Product name, assembly path, and file paths are cached to minimize overhead
• Daily Log Rotation: Log files automatically change at midnight
• Memory Efficient: Old log files are automatically cleaned up based on age

Thread Safety

Loglet is fully thread-safe and designed for concurrent logging from multiple threads. The implementation uses:

• BlockingCollection<T> for thread-safe queue operations
• Lock-protected cache invalidation for file path management
• Exception handling to prevent logging failures from affecting your application

Error Handling

Loglet is designed with defensive error handling:

• If the log queue becomes full, it falls back to synchronous writing
• Individual file access errors don't stop the cleanup process
• Logging errors never crash your application
• Background processing errors are silently handled

Compatibility

• Target Frameworks: .NET Standard 2.0, .NET 10
• C# Version: 8.0+
• License: Check repository for license information

Contributing

For issues, feature requests, or contributions, visit the GitHub repository.

License

See the LICENSE file in the repository for details.

Loglet: Because high-performance logging should be simple.