GETTING_STARTED

autotoc_md1966

doc_id: "LOG-GUID-021" doc_title: "Getting Started with Logger System" doc_version: "1.0.0" doc_date: "2026-04-04" doc_status: "Released" project: "logger_system"

category: "GUID"

‍Language: English | 한국어

Getting Started with Logger System

‍SSOT: This document is the single source of truth for Getting Started with Logger System.

This guide will help you get started with the Logger System quickly.

Table of Contents

• Requirements
• Installation
• Basic Usage
• Configuration
• Integration with Thread System

Requirements

• C++20 compatible compiler:
  • GCC 10+
  • Clang 12+
  • MSVC 2019+ (Visual Studio 2019 version 16.11+)
• CMake 3.16 or higher
• Operating System:
  • Linux (Ubuntu 20.04+, CentOS 8+, etc.)
  • macOS 10.15+
  • Windows 10+

Installation

Using CMake FetchContent (Recommended)

Add the following to your CMakeLists.txt:

include(FetchContent)
 
FetchContent_Declare(
    LoggerSystem
    GIT_REPOSITORY https://github.com/kcenon/logger_system.git
    GIT_TAG v0.1.0  # Pin to a specific release tag; do NOT use main
)
FetchContent_MakeAvailable(LoggerSystem)
 
# Link to your target
target_link_libraries(your_target PRIVATE LoggerSystem::logger)

Building from Source

# Clone the repository
git clone https://github.com/kcenon/logger_system.git
cd logger_system
 
# Create build directory
mkdir build && cd build
 
# Configure
cmake .. -DCMAKE_BUILD_TYPE=Release
 
# Build
cmake --build .
 
# Install (optional)
sudo cmake --install .

Using as Installed Package

If you've installed the logger system:

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

Basic Usage

Simple Console Logging

#include <logger_system/logger.h>
#include <logger_system/writers/console_writer.h>
 
int main() {
    // Create logger instance
    auto logger = std::make_shared<logger_module::logger>();
    
    // Add console output
    logger->add_writer(std::make_unique<logger_module::console_writer>());
    
    // Start logger (for async mode)
    logger->start();
    
    // Log messages
    logger->log(thread_module::log_level::info, "Application started");
    logger->log(thread_module::log_level::warning, "This is a warning");
    logger->log(thread_module::log_level::error, "An error occurred!");
    
    // Stop logger
    logger->stop();
    
    return 0;
}

Logging with Source Location

Source location is automatically captured in v2.x+ using C++20's std::source_location. You no longer need to pass __FILE__, __LINE__, and __func__ manually.

// Simple logging - source location is auto-captured
logger->log(thread_module::log_level::debug, "Debug information");
 
// For explicit source location, use the common::interfaces::ILogger interface:
#include <kcenon/common/interfaces/logger_interface.h>
logger->log(common::interfaces::log_level::debug, "Debug with explicit location");
 
// Or use the LOG_* convenience macros from common_system:
#include <kcenon/common/logging/log_macros.h>
LOG_DEBUG("This includes auto-captured source location");

‍Note: The legacy API with __FILE__, __LINE__, __func__ is deprecated and will be removed in v3.0.0.

Structured JSON Output

The structured_logger provides JSON/logfmt/plain output. For strict JSON compliance at scale, consider integrating a JSON library (e.g., nlohmann/json):

// Example using nlohmann::json (optional dependency)
// #include <nlohmann/json.hpp>
// nlohmann::json j = {
//     {"@timestamp", std::time(nullptr)},
//     {"level", "INFO"},
//     {"message", "User logged in"},
//     {"user_id", 12345}
// };
// logger->log(log_level::info, j.dump());

Alternatively, keep using structured_logger and route JSON output to file/network. When adding a JSON library, prefer compile-time options to keep it optional.

Log Levels

The logger supports six log levels:

enum class log_level {
    trace,    // Most detailed information
    debug,    // Debug information
    info,     // Informational messages
    warning,  // Warning messages
    error,    // Error messages
    critical  // Critical errors
};

Filtering by Level

// Set minimum log level
logger->set_min_level(thread_module::log_level::info);
 
// These won't be logged
logger->log(thread_module::log_level::trace, "Too detailed");
logger->log(thread_module::log_level::debug, "Debug info");
 
// These will be logged
logger->log(thread_module::log_level::info, "Important info");
logger->log(thread_module::log_level::error, "Error!");

Configuration

Synchronous vs Asynchronous Logging

// Asynchronous logger (default)
auto async_logger = std::make_shared<logger_module::logger>(true, 8192);
 
// Synchronous logger
auto sync_logger = std::make_shared<logger_module::logger>(false);

Multiple Writers

// Console output with color
auto console = std::make_unique<logger_module::console_writer>();
logger->add_writer(std::move(console));
 
// File output (when implemented)
// auto file = std::make_unique<logger_module::file_writer>("app.log");
// logger->add_writer(std::move(file));
 
// Custom writer
class my_writer : public logger_module::base_writer {
    void write(thread_module::log_level level,
               const std::string& message,
               const std::string& file,
               int line,
               const std::string& function,
               const std::chrono::system_clock::time_point& timestamp) override {
        // Custom implementation
    }
    
    void flush() override {
        // Flush implementation
    }
};
 
logger->add_writer(std::make_unique<my_writer>());

Windows Notes (Networking)

The network writer/server use POSIX sockets. On Windows, add WinSock initialization and adapt socket calls:

• Call WSAStartup(MAKEWORD(2,2), &wsaData) before creating sockets and WSACleanup() at shutdown.
• Replace close(fd) with closesocket(fd) and use appropriate error codes (e.g., WSAGetLastError()).
• Consider a small socket abstraction layer guarded by #ifdef _WIN32 to keep code portable.

Console Writer Options

// Output to stderr instead of stdout
auto console = std::make_unique<logger_module::console_writer>(true);
 
// Disable color output
auto console = std::make_unique<logger_module::console_writer>(false, false);
console->set_use_color(false);

Integration with Thread System

Using Service Container

#include <logger_system/logger.h>
#include <logger_system/writers/console_writer.h>
#include <thread_system/interfaces/service_container.h>
#include <thread_system/interfaces/thread_context.h>
#include <thread_system/thread_pool/core/thread_pool.h>
 
int main() {
    // Create and configure logger
    auto logger = std::make_shared<logger_module::logger>();
    logger->add_writer(std::make_unique<logger_module::console_writer>());
    logger->start();
    
    // Register in service container
    thread_module::service_container::global()
        .register_singleton<thread_module::logger_interface>(logger);
    
    // Create thread pool - it will use the logger automatically
    thread_module::thread_context context;
    auto pool = std::make_shared<thread_pool_module::thread_pool>("MyPool", context);
    
    // The pool will now log its operations
    pool->start();
    
    // Clean up
    pool->stop();
    logger->stop();
    
    return 0;
}

Direct Integration

// Create logger
auto logger = std::make_shared<logger_module::logger>();
logger->add_writer(std::make_unique<logger_module::console_writer>());
logger->start();
 
// Use directly as logger_interface
std::shared_ptr<thread_module::logger_interface> logger_interface = logger;
 
// Pass to components that need logging
auto context = thread_module::thread_context(logger_interface);

Next Steps

• Read the Architecture Overview to understand the system design
• Check the API Reference for detailed documentation
• See Performance Guide for optimization tips
• Learn about Custom Writers for specialized output

---

Last Updated: 2025-10-20