Language: English | 한국어

A high-performance C++20 asynchronous logging framework designed for multithreaded applications. Built with a modular, interface-based architecture and seamless ecosystem integration.

Key Features:

• 🚀 Ultra-fast async logging: 4.34M messages/second, 148ns latency
• 🔒 Thread-safe by design: Zero data races, production-proven
• 🏗️ Modular architecture: Interface-driven, pluggable components
• 🛡️ Production-grade: Comprehensive CI/CD, sanitizers, benchmarks
• 🔐 Security-first: Path validation, secure storage, audit logging
• 🌐 Cross-platform: Windows, Linux, macOS with GCC, Clang, MSVC

#include <kcenon/logger/core/logger_builder.h>
#include <kcenon/logger/writers/console_writer.h>
#include <kcenon/logger/writers/file_writer.h>

int main() {
    // Create logger using builder pattern with automatic validation
    auto result = kcenon::logger::logger_builder()
        .use_template("production")  // Predefined configuration
        .with_min_level(kcenon::logger::log_level::info)
        .add_writer("console", std::make_unique<kcenon::logger::console_writer>())
        .add_writer("file", std::make_unique<kcenon::logger::file_writer>("app.log"))
        .build();

    if (result.is_err()) {
        const auto& err = result.error();
        std::cerr << "Failed to create logger: " << err.message
                  << " (code: " << err.code << ")\n";
        return -1;
    }

    auto logger = std::move(result.value());

    // Log messages with error handling
    logger->log(kcenon::logger::log_level::info, "Application started");
logger->log(kcenon::logger::log_level::error, "Something went wrong");

return 0;
}

Need a quick reminder later? See the Result Handling Cheatsheet for canonical snippets that can be reused across the ecosystem.

Using CMake:

mkdir build && cd build
cmake ..
cmake --build .
cmake --build . --target install

Using in Your Project:

find_package(LoggerSystem REQUIRED)
target_link_libraries(your_app PRIVATE LoggerSystem::logger)

logger_system
├── common_system (required)
└── thread_system (optional, for async logging with thread pool)
    └── common_system (required)

# Clone dependencies
git clone https://github.com/kcenon/common_system.git
git clone https://github.com/kcenon/thread_system.git  # Optional

# Clone and build logger_system
git clone https://github.com/kcenon/logger_system.git
cd logger_system
cmake -B build -DLOGGER_USE_THREAD_SYSTEM=ON  # Enable thread_system integration
cmake --build build

• Non-blocking operations: Background thread handles I/O without blocking
• Batched processing: Processes multiple log entries efficiently
• Adaptive batching: Intelligent optimization based on queue utilization
• Zero-copy design: Minimal allocations and overhead

• Console Writer: ANSI colored output for different log levels
• File Writer: Buffered file output with configurable settings
• Rotating File Writer: Size/time-based rotation with compression
• Network Writer: TCP/UDP remote logging
• Critical Writer: Synchronous logging for critical messages
• Hybrid Writer: Automatic async/sync switching based on log level

📚 Detailed Writer Documentation →

• Secure Key Storage: RAII-based encryption key management with automatic cleanup
• Path Validation: Protection against path traversal attacks
• Signal Handler Safety: Emergency flush for crash scenarios
• Security Audit Logging: Tamper-evident audit trail with HMAC-SHA256
• Compliance Support: GDPR, PCI DSS, ISO 27001, SOC 2

🔒 Complete Security Guide →

Benchmarked on Apple M1 (8-core) @ 3.2GHz, 16GB, macOS Sonoma

• Baseline: 1.8 MB (vs spdlog: 4.2 MB, 57% less)
• Peak: 2.4 MB
• Allocations/msg: 0.12

Key Insights:

• 🏃 Multi-threaded advantage: Adaptive batching provides superior scaling
• ⏱️ Ultra-low latency: Industry-leading 148ns average enqueue time
• 💾 Memory efficient: Minimal footprint with zero-copy design

⚡ Full Benchmarks & Methodology →

┌─────────────────────────────────────────────────────────────┐
│                      Logger Core                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Builder    │  │  Async Queue │  │   Metrics    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└───────────────────────┬─────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        │               │               │
        ▼               ▼               ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│   Writers    │ │   Filters    │ │  Formatters  │
│              │ │              │ │              │
│ • Console    │ │ • Level      │ │ • Plain Text │
│ • File       │ │ • Regex      │ │ • JSON       │
│ • Rotating   │ │ • Function   │ │ • Logfmt     │
│ • Network    │ │ • Composite  │ │ • Custom     │
│ • Critical   │ │              │ │              │
│ • Hybrid     │ │              │ │              │
└──────────────┘ └──────────────┘ └──────────────┘

• Logger Core: Main async processing engine with builder pattern
• Writers: Pluggable output destinations (file, console, network, etc.)
• Filters: Conditional logging based on level, pattern, or custom logic
• Formatters: Configurable output formats (plain, JSON, logfmt, custom)
• Security: Path validation, secure storage, audit logging

🏛️ Detailed Architecture Guide →

Part of a modular C++ ecosystem with clean interface boundaries:

Required:

• common_system: Core interfaces (ILogger, IMonitor, Result) with C++20 Concepts support

Optional:

• thread_system: Enhanced threading primitives (optional since v3.1.0)
• monitoring_system: Metrics and health monitoring

Note: Since v3.1.0, thread_system is optional. The logger system uses a standalone std::jthread implementation by default. For advanced async processing, enable thread_system integration with -DLOGGER_USE_THREAD_SYSTEM=ON (see Issue #224).

#include <kcenon/logger/core/logger.h>
#include <kcenon/logger/core/logger_builder.h>
#include <kcenon/logger/writers/console_writer.h>

int main() {
    // Create logger using builder pattern (standalone mode, no thread_system required)
    auto logger = kcenon::logger::logger_builder()
        .use_template("production")
        .add_writer("console", std::make_unique<kcenon::logger::console_writer>())
        .build()
        .value();

    // Use logger anywhere in your application
    logger->log(kcenon::logger::log_level::info, "System initialized");

    return 0;
}

Note: When thread_system is available and LOGGER_HAS_THREAD_SYSTEM is defined (via -DLOGGER_USE_THREAD_SYSTEM=ON), additional integration features are enabled including shared thread pool for async processing. See thread_system integration for details.

Benefits:

• Interface-only dependencies (no circular references)
• Independent compilation and deployment
• Runtime component injection via DI pattern
• Clean separation of concerns

🔗 Ecosystem Integration Guide →

• 📖 Getting Started Guide - Step-by-step setup and basic usage
• 🚀 Quick Start Examples - Hands-on examples
• 🔧 Build Guide - Detailed build instructions

• 📘 Features - Comprehensive feature documentation
• 📊 Benchmarks - Performance analysis and comparisons
• 🏗️ Architecture - System design and internals
• 📋 Project Structure - Directory organization and files
• 🔧 API Reference - Complete API documentation

• ⚡ Performance Guide - Optimization tips and tuning
• 🔒 Security Guide - Security considerations and best practices
• ✅ Production Quality - CI/CD, testing, quality metrics
• 🎨 Custom Writers - Creating custom log writers
• 🔄 Integration Guide - Ecosystem integration patterns

• 🤝 Contributing Guide - How to contribute
• 📋 FAQ - Frequently asked questions
• 🔍 Troubleshooting - Common issues and solutions
• 📝 Changelog - Release history and changes

The logger system provides predefined templates for common scenarios:

// Production: Optimized for production environments
auto logger = kcenon::logger::logger_builder()
    .use_template("production")
    .build()
    .value();

// Debug: Immediate output for development
auto logger = kcenon::logger::logger_builder()
    .use_template("debug")
    .build()
    .value();

// High-performance: Maximized throughput
auto logger = kcenon::logger::logger_builder()
    .use_template("high_performance")
    .build()
    .value();

// Low-latency: Minimized latency for real-time systems
auto logger = kcenon::logger::logger_builder()
    .use_template("low_latency")
    .build()
    .value();

auto logger = kcenon::logger::logger_builder()
    // Core settings
    .with_min_level(kcenon::logger::log_level::info)
    .with_buffer_size(16384)
    .with_batch_size(200)
    .with_queue_size(20000)

    // Add multiple writers
    .add_writer("console", std::make_unique<kcenon::logger::console_writer>())
    .add_writer("file", std::make_unique<kcenon::logger::rotating_file_writer>(
        "app.log",
        10 * 1024 * 1024,  // 10MB per file
        5                   // Keep 5 files
    ))

    // Build with validation
    .build()
    .value();

📚 Complete Configuration Guide →

# Core Features
cmake -DLOGGER_USE_DI=ON              # Dependency injection (default: ON)
cmake -DLOGGER_USE_MONITORING=ON      # Monitoring support (default: ON)
cmake -DLOGGER_ENABLE_ASYNC=ON        # Async logging (default: ON)
cmake -DLOGGER_ENABLE_CRASH_HANDLER=ON # Crash handler (default: ON)

# Advanced Features
cmake -DLOGGER_ENABLE_STRUCTURED_LOGGING=ON # JSON logging (default: OFF)
cmake -DLOGGER_ENABLE_NETWORK_WRITER=ON # Network writer (default: OFF)
cmake -DLOGGER_ENABLE_FILE_ROTATION=ON  # File rotation (default: ON)

# Performance Tuning
cmake -DLOGGER_DEFAULT_BUFFER_SIZE=16384 # Buffer size in bytes
cmake -DLOGGER_DEFAULT_BATCH_SIZE=200    # Batch processing size
cmake -DLOGGER_DEFAULT_QUEUE_SIZE=20000  # Maximum queue size

# Quality Assurance
cmake -DLOGGER_ENABLE_SANITIZERS=ON   # Enable sanitizers
cmake -DLOGGER_ENABLE_COVERAGE=ON     # Code coverage
cmake -DLOGGER_WARNINGS_AS_ERRORS=ON  # Treat warnings as errors

🔧 Complete Build Options →

Minimum Requirements:

• C++20 compiler
• CMake 3.20+
• fmt library

🖥️ Platform Details →

The logger system includes comprehensive testing infrastructure:

• Unit Tests: 150+ test cases (GTest)
• Integration Tests: 30+ scenarios
• Benchmarks: 20+ performance tests
• Coverage: ~65% (growing)

# Build with tests
cmake -DBUILD_TESTS=ON ..
cmake --build .

# Run all tests
ctest --output-on-failure

# Run specific test suite
./build/bin/core_tests
./build/bin/writer_tests

# Run benchmarks
./build/bin/benchmarks

All pipelines green:

• ✅ Multi-platform builds (Ubuntu, macOS, Windows)
• ✅ Sanitizers (Thread, Address, UB)
• ✅ Performance benchmarks
• ✅ Code coverage
• ✅ Static analysis (clang-tidy, cppcheck)

✅ Production Quality Metrics →

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

• Follow modern C++ best practices
• Use RAII and smart pointers
• Write comprehensive unit tests
• Maintain consistent formatting (clang-format)
• Document public APIs

🤝 Contributing Guidelines →

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: kcenon@naver.com

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

• Inspired by modern logging frameworks (spdlog, Boost.Log, glog)
• Built with C++20 features (GCC 11+, Clang 14+, MSVC 2022+) for maximum performance and safety
• Maintained by kcenon@naver.com

Made with ❤️ by 🍀☀🌕🌥 🌊