kcenon::logger::rotating_file_writer Class Reference

File writer with automatic log rotation support. More...

#include <rotating_file_writer.h>

Inheritance diagram for kcenon::logger::rotating_file_writer:

Collaboration diagram for kcenon::logger::rotating_file_writer:

Public Member Functions
	rotating_file_writer (const std::string &filename, size_t max_size, size_t max_files, size_t check_interval=100)
	Construct with size-based rotation.
	rotating_file_writer (const std::string &filename, rotation_type type, size_t max_files, size_t check_interval=100)
	Construct with time-based rotation.
	rotating_file_writer (const std::string &filename, rotation_type type, size_t max_size, size_t max_files, size_t check_interval=100)
	Construct with combined size and time rotation.
std::string	get_name () const override
	Get writer name.
void	rotate ()
	Manually trigger log rotation (thread-safe)
common::VoidResult	write (const log_entry &entry) override
	Write operation with automatic rotation check.
Public Member Functions inherited from kcenon::logger::file_writer
	file_writer (const std::string &filename, bool append=true, std::unique_ptr< log_formatter_interface > formatter=nullptr, bool binary=false)
	Constructor.
	~file_writer () override
	Destructor.
	file_writer (const file_writer &)=delete
file_writer &	operator= (const file_writer &)=delete
	file_writer (file_writer &&)=delete
file_writer &	operator= (file_writer &&)=delete
common::VoidResult	flush () override
	Flush file stream.
common::VoidResult	close () override
	Close the file.
bool	is_open () const override
	Check if file is open.
bool	is_healthy () const override
	Check if writer is healthy.
size_t	get_file_size () const
	Get current file size.
void	set_integrity_policy (std::shared_ptr< security::integrity_policy > policy)
	Enable tamper-evident integrity signing for every record.
Public Member Functions inherited from kcenon::logger::log_writer_interface
virtual	~log_writer_interface ()=default

Private Member Functions
bool	should_rotate () const
	Check if rotation should occur.
void	perform_rotation ()
	Perform the actual rotation operation.
std::string	generate_rotated_filename (int index=-1) const
	Generate filename for rotated log.
void	cleanup_old_files ()
	Remove old backup files beyond max_files limit.
std::vector< std::string >	get_backup_files () const
	Get list of existing backup files.
bool	should_rotate_by_time () const
	Check if time-based rotation should occur.
std::size_t	get_file_size () const
	Get current file size from filesystem.

Private Attributes
rotation_type	rotation_type_
size_t	max_size_
size_t	max_files_
size_t	check_interval_
	Number of writes between rotation checks.
size_t	writes_since_check_ {0}
	Counter for writes since last check.
std::string	base_filename_
std::string	file_extension_
std::chrono::system_clock::time_point	last_rotation_time_
std::chrono::system_clock::time_point	current_period_start_

Additional Inherited Members
Static Public Attributes inherited from kcenon::logger::sync_writer_tag
static constexpr writer_category	category = writer_category::synchronous
Protected Member Functions inherited from kcenon::logger::file_writer
std::string	format_entry (const log_entry &entry) const
	Format a log entry using the current formatter.
common::VoidResult	open_internal ()
	Open the file (internal, caller must hold mutex)
void	close_internal ()
	Close the file (internal, caller must hold mutex)
std::mutex &	get_mutex () const
	Access the writer mutex for extended operations.
Protected Attributes inherited from kcenon::logger::file_writer
std::string	filename_
bool	append_mode_
bool	binary_mode_ = false
std::ofstream	file_stream_
std::atomic< bool >	is_open_ {false}
std::atomic< size_t >	bytes_written_ {0}
std::unique_ptr< log_formatter_interface >	formatter_
std::shared_ptr< security::integrity_policy >	integrity_policy_
	Integrity policy shared with derived writers (e.g. rotating_file_writer).
std::mutex	mutex_

Detailed Description

File writer with automatic log rotation support.

This writer extends file_writer to add automatic log rotation based on file size, time intervals, or both. When rotation occurs, the current log file is renamed with a timestamp or index, and a new file is created.

Rotation strategies:

• Size-based: Rotates when file reaches max_size bytes
• Time-based: Rotates daily or hourly
• Combined: Rotates when either condition is met

Thread Safety:

• All public methods are thread-safe
• Uses mutex from thread_safe_writer base class

Category: Synchronous (blocking I/O, inherits from file_writer)

Since

1.0.0

1.3.0 Refactored to use thread_safe_writer via file_writer

1.4.0 Inherits sync_writer_tag from file_writer

Definition at line 60 of file rotating_file_writer.h.

Constructor & Destructor Documentation

rotating_file_writer() [1/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		size_t	max_size,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with size-based rotation.

Parameters

filename	Path to the log file
max_size	Maximum file size in bytes before rotation
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Definition at line 16 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(rotation_type::size)
    , max_size_(max_size)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, and file_extension_.

rotating_file_writer() [2/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		rotation_type	type,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with time-based rotation.

Parameters

filename	Path to the log file
type	Rotation type (daily or hourly)
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Definition at line 37 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(type)
    , max_size_(0)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, and file_extension_.

rotating_file_writer() [3/3]

kcenon::logger::rotating_file_writer::rotating_file_writer	(	const std::string &	filename,
		rotation_type	type,
		size_t	max_size,
		size_t	max_files,
		size_t	check_interval = 100 )

Construct with combined size and time rotation.

Parameters

filename	Path to the log file
type	Must be rotation_type::size_and_time
max_size	Maximum file size in bytes before rotation
max_files	Maximum number of backup files to keep
check_interval	Number of writes between rotation checks (default: 100)

Exceptions

std::invalid_argument

if type is not size_and_time

Definition at line 58 of file rotating_file_writer.cpp.

    : file_writer(filename, true)
    , rotation_type_(type)
    , max_size_(max_size)
    , max_files_(max_files)
    , check_interval_(check_interval)
    , last_rotation_time_(std::chrono::system_clock::now())
    , current_period_start_(std::chrono::system_clock::now()) {
 
    if (type != rotation_type::size_and_time) {
        throw std::invalid_argument("This constructor is only for size_and_time rotation");
    }
 
    // Extract base filename and extension
    std::filesystem::path path(filename);
    base_filename_ = path.stem().string();
    file_extension_ = path.extension().string();
    if (file_extension_.empty()) {
        file_extension_ = ".log";
    }
}

References base_filename_, file_extension_, and kcenon::logger::size_and_time.

Member Function Documentation

cleanup_old_files()

void kcenon::logger::rotating_file_writer::cleanup_old_files ( )

private

Remove old backup files beyond max_files limit.

Definition at line 261 of file rotating_file_writer.cpp.

                                             {
    auto backup_files = get_backup_files();
 
    if (backup_files.size() > max_files_) {
        // Sort by modification time (oldest first)
        std::sort(backup_files.begin(), backup_files.end(),
                 [](const std::string& a, const std::string& b) {
                     return std::filesystem::last_write_time(a) <
                            std::filesystem::last_write_time(b);
                 });
 
        // Remove oldest files
        size_t files_to_remove = backup_files.size() - max_files_;
        for (size_t i = 0; i < files_to_remove; ++i) {
            auto remove_result = utils::try_write_operation([&]() -> common::VoidResult {
                std::filesystem::remove(backup_files[i]);
                return common::ok();
            }, logger_error_code::file_rotation_failed);
 
            if (remove_result.is_err()) {
                std::cerr << "Failed to remove old log file: " << remove_result.error().message << std::endl;
            }
        }
    }
}

References kcenon::logger::file_rotation_failed, get_backup_files(), max_files_, kcenon::common::ok(), and kcenon::logger::utils::try_write_operation().

Referenced by perform_rotation().

Here is the call graph for this function:

Here is the caller graph for this function:

generate_rotated_filename()

std::string kcenon::logger::rotating_file_writer::generate_rotated_filename ( int index = -1 ) const

private

Generate filename for rotated log.

Parameters

index

Optional index for size-based rotation (-1 for auto)

Definition at line 206 of file rotating_file_writer.cpp.

                                                                         {
    std::ostringstream oss;
    std::filesystem::path dir = std::filesystem::path(filename_).parent_path();
 
    if (!dir.empty()) {
        oss << dir.string() << "/";
    }
 
    // Build: base + extension + separator + timestamp/index
    // Example: "test.log.1" instead of "test.1.log"
    oss << base_filename_ << file_extension_;
 
    // Add timestamp or index
    auto now = std::chrono::system_clock::now();
    auto time_t = std::chrono::system_clock::to_time_t(now);
 
    // Use thread-safe time conversion
    std::tm tm_buf{};
#ifdef _WIN32
    localtime_s(&tm_buf, &time_t);  // Windows thread-safe version
#else
    localtime_r(&time_t, &tm_buf);  // POSIX thread-safe version
#endif
 
    switch (rotation_type_) {
        case rotation_type::size:
            if (index >= 0) {
                oss << "." << index;
            } else {
                // Find next available index
                std::string base_with_ext = oss.str();
                int next_index = 1;
                while (std::filesystem::exists(base_with_ext + "." + std::to_string(next_index))) {
                    next_index++;
                }
                oss << "." << next_index;
            }
            break;
 
        case rotation_type::daily:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d");
            break;
 
        case rotation_type::hourly:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d_%H");
            break;
 
        case rotation_type::size_and_time:
            oss << "." << std::put_time(&tm_buf, "%Y%m%d_%H%M%S");
            break;
    }
 
    return oss.str();
}

References base_filename_, kcenon::logger::daily, file_extension_, kcenon::logger::file_writer::filename_, kcenon::logger::hourly, rotation_type_, kcenon::logger::size, and kcenon::logger::size_and_time.

Referenced by perform_rotation().

Here is the caller graph for this function:

get_backup_files()

std::vector< std::string > kcenon::logger::rotating_file_writer::get_backup_files ( ) const

private

Get list of existing backup files.

Definition at line 287 of file rotating_file_writer.cpp.

                                                                  {
    std::vector<std::string> files;
    std::filesystem::path dir = std::filesystem::path(filename_).parent_path();
    if (dir.empty()) {
        dir = ".";
    }
 
    // Create regex pattern for backup files
    // Pattern: base_filename + file_extension + "." + (number or timestamp)
    // Example: "test_rotating.log.1" or "test.log.20250108"
    std::string escaped_ext = std::regex_replace(file_extension_, std::regex(R"(\.)"), R"(\\.)");
    std::string pattern = base_filename_ + escaped_ext + R"(\.(\d+|\d{8}|\d{8}_\d{2}|\d{8}_\d{6}))";
    std::regex backup_regex(pattern);
 
    // Use error handling utility for directory iteration
    auto result = utils::try_write_operation([&]() -> common::VoidResult {
        for (const auto& entry : std::filesystem::directory_iterator(dir)) {
            if (entry.is_regular_file()) {
                std::string filename = entry.path().filename().string();
                if (std::regex_match(filename, backup_regex)) {
                    files.push_back(entry.path().string());
                }
            }
        }
        return common::ok();
    }, logger_error_code::file_rotation_failed);
 
    if (result.is_err()) {
        std::cerr << "Error listing backup files: " << result.error().message << std::endl;
    }
 
    return files;
}

References base_filename_, file_extension_, kcenon::logger::file_rotation_failed, kcenon::logger::file_writer::filename_, kcenon::common::ok(), and kcenon::logger::utils::try_write_operation().

Referenced by cleanup_old_files().

Here is the call graph for this function:

Here is the caller graph for this function:

get_file_size()

std::size_t kcenon::logger::rotating_file_writer::get_file_size ( ) const

private

Get current file size from filesystem.

Definition at line 358 of file rotating_file_writer.cpp.

                                                    {
    // IMPORTANT: This method should only be called while holding the mutex
    // to avoid race conditions with concurrent writes and file rotation.
    //
    // Race condition example:
    // - Thread A: Calls should_rotate() -> get_file_size() reads filesystem
    // - Thread B: Simultaneously writing, bytes_written_ is updating
    // - Result: get_file_size() returns stale data, rotation check is incorrect
    //
    // Better approach: Always use bytes_written_.load() which is atomic and
    // thread-safe. Only call filesystem functions during actual rotation when
    // the caller already holds the mutex.
 
    if (!file_stream_.is_open()) {
        return 0;
    }
 
    // Prefer atomic counter for thread safety
    // Only fall back to filesystem if absolutely necessary
    std::size_t atomic_size = bytes_written_.load(std::memory_order_relaxed);
 
    // Optional: Validate with filesystem size for debugging
    // (Remove in production for performance)
    #ifdef DEBUG_FILE_SIZE_VALIDATION
    std::error_code ec;
    auto fs_size = std::filesystem::file_size(filename_, ec);
    if (!ec && fs_size != atomic_size) {
        // Log discrepancy for debugging
        std::cerr << "File size mismatch: atomic=" << atomic_size
                  << " filesystem=" << fs_size << std::endl;
    }
    #endif
 
    return atomic_size;
}

References kcenon::logger::file_writer::bytes_written_, kcenon::logger::file_writer::file_stream_, and kcenon::logger::file_writer::filename_.

Referenced by should_rotate().

Here is the caller graph for this function:

get_name()

std::string kcenon::logger::rotating_file_writer::get_name ( ) const

inlineoverridevirtual

Get writer name.

Reimplemented from kcenon::logger::file_writer.

Definition at line 104 of file rotating_file_writer.h.

{ return "rotating_file"; }

perform_rotation()

void kcenon::logger::rotating_file_writer::perform_rotation ( )

private

Perform the actual rotation operation.

Note

Caller must hold the mutex

Definition at line 148 of file rotating_file_writer.cpp.

                                            {
    // IMPORTANT: Caller must hold the mutex before calling this method
    // This ensures thread safety for all file operations and mutable state modifications
 
    // Close current file
    if (file_stream_.is_open()) {
        file_stream_.flush();
        file_stream_.close();
    }
 
    // Generate new filename for the current log
    std::string rotated_name = generate_rotated_filename();
 
    // Rename current file (with error handling)
    auto rename_result = utils::try_write_operation([&]() -> common::VoidResult {
        if (std::filesystem::exists(filename_)) {
            std::filesystem::rename(filename_, rotated_name);
        }
        return common::ok();
    }, logger_error_code::file_rotation_failed);
 
    if (rename_result.is_err()) {
        std::cerr << "Failed to rotate log file: " << rename_result.error().message << std::endl;
    }
 
    // Clean up old files
    cleanup_old_files();
 
    // Open new file (with error handling)
    auto open_result = utils::try_open_operation([&]() -> common::VoidResult {
        std::filesystem::path file_path(filename_);
        std::filesystem::path dir = file_path.parent_path();
 
        auto dir_result = utils::ensure_directory_exists(dir);
        if (dir_result.is_err()) return dir_result;
 
        auto mode = append_mode_ ? std::ios::app : std::ios::trunc;
        file_stream_.open(filename_, std::ios::out | mode);
 
        if (file_stream_.is_open()) {
            bytes_written_ = 0;
        }
 
        return common::ok();
    });
 
    if (open_result.is_err()) {
        std::cerr << "Failed to open new log file: " << open_result.error().message << std::endl;
    }
 
    // Update rotation time - protected by mutex
    last_rotation_time_ = std::chrono::system_clock::now();
    current_period_start_ = last_rotation_time_;
 
    // Reset write counter after rotation
    writes_since_check_ = 0;
}

References kcenon::logger::file_writer::append_mode_, kcenon::logger::file_writer::bytes_written_, cleanup_old_files(), current_period_start_, kcenon::logger::utils::ensure_directory_exists(), kcenon::logger::file_rotation_failed, kcenon::logger::file_writer::file_stream_, kcenon::logger::file_writer::filename_, generate_rotated_filename(), last_rotation_time_, kcenon::common::ok(), kcenon::logger::utils::try_open_operation(), kcenon::logger::utils::try_write_operation(), and writes_since_check_.

Referenced by rotate(), and write().

Here is the call graph for this function:

Here is the caller graph for this function:

rotate()

void kcenon::logger::rotating_file_writer::rotate

(

)

Manually trigger log rotation (thread-safe)

Definition at line 125 of file rotating_file_writer.cpp.

                                  {
    // Public API for manual rotation
    std::lock_guard<std::mutex> lock(get_mutex());
    perform_rotation();
}

References kcenon::logger::file_writer::get_mutex(), and perform_rotation().

Here is the call graph for this function:

should_rotate()

bool kcenon::logger::rotating_file_writer::should_rotate ( ) const

private

Check if rotation should occur.

Definition at line 131 of file rotating_file_writer.cpp.

                                               {
    switch (rotation_type_) {
        case rotation_type::size:
            return get_file_size() >= max_size_;
            
        case rotation_type::daily:
        case rotation_type::hourly:
            return should_rotate_by_time();
            
        case rotation_type::size_and_time:
            return get_file_size() >= max_size_ || should_rotate_by_time();
            
        default:
            return false;
    }
}

References kcenon::logger::daily, get_file_size(), kcenon::logger::hourly, max_size_, rotation_type_, should_rotate_by_time(), kcenon::logger::size, and kcenon::logger::size_and_time.

Referenced by write().

Here is the call graph for this function:

Here is the caller graph for this function:

should_rotate_by_time()

bool kcenon::logger::rotating_file_writer::should_rotate_by_time ( ) const

private

Check if time-based rotation should occur.

Definition at line 321 of file rotating_file_writer.cpp.

                                                       {
    auto now = std::chrono::system_clock::now();
    
    switch (rotation_type_) {
        case rotation_type::daily:
        case rotation_type::size_and_time: {
            // Check if we're in a new day
            auto now_time_t = std::chrono::system_clock::to_time_t(now);
            auto start_time_t = std::chrono::system_clock::to_time_t(current_period_start_);
 
            // Use thread-safe time conversion
            std::tm now_tm{};
            std::tm start_tm{};
#ifdef _WIN32
            localtime_s(&now_tm, &now_time_t);
            localtime_s(&start_tm, &start_time_t);
#else
            localtime_r(&now_time_t, &now_tm);
            localtime_r(&start_time_t, &start_tm);
#endif
 
            return now_tm.tm_year != start_tm.tm_year ||
                   now_tm.tm_mon != start_tm.tm_mon ||
                   now_tm.tm_mday != start_tm.tm_mday;
        }
        
        case rotation_type::hourly: {
            // Check if we're in a new hour
            auto duration = now - current_period_start_;
            return duration >= std::chrono::hours(1);
        }
        
        default:
            return false;
    }
}

References current_period_start_, kcenon::logger::daily, kcenon::logger::hourly, rotation_type_, and kcenon::logger::size_and_time.

Referenced by should_rotate().

Here is the caller graph for this function:

write()

common::VoidResult kcenon::logger::rotating_file_writer::write ( const log_entry & entry )

overridevirtual

Write operation with automatic rotation check.

Parameters

entry

The log entry to write (includes structured fields)

Since

3.4.0

3.5.0 This is now the only write implementation (legacy API removed)

4.0.0 Changed to override write() directly after Decorator pattern refactoring

Reimplemented from kcenon::logger::file_writer.

Definition at line 84 of file rotating_file_writer.cpp.

                                                                   {
    std::lock_guard<std::mutex> lock(get_mutex());
 
    // Check precondition
    if (!file_stream_.is_open()) {
        return make_logger_void_result(logger_error_code::file_write_failed, "File stream is not open");
    }
 
    // Format and write - preserves all structured fields
    std::string formatted = format_entry(entry);
 
    // Apply integrity signature (Issue #612) if the parent file_writer
    // was configured with a policy. We reach into the parent's protected
    // integrity_policy_ to keep the behavior consistent across size-based
    // and time-based rotation paths.
    if (integrity_policy_) {
        formatted.append(
            security::format_signature_suffix(*integrity_policy_, formatted));
    }
 
    file_stream_ << formatted << '\n';
    bytes_written_.fetch_add(formatted.size() + 1);
 
    // Verify stream state
    if (file_stream_.fail()) {
        return make_logger_void_result(logger_error_code::file_write_failed, "Write failed");
    }
 
    // Periodic rotation check optimization (Phase 2)
    ++writes_since_check_;
 
    if (writes_since_check_ >= check_interval_) {
        if (should_rotate()) {
            perform_rotation();
        }
        writes_since_check_ = 0;
    }
 
    return common::ok();
}

References kcenon::logger::file_writer::bytes_written_, check_interval_, kcenon::logger::file_writer::file_stream_, kcenon::logger::file_write_failed, kcenon::logger::file_writer::format_entry(), kcenon::logger::security::format_signature_suffix(), kcenon::logger::file_writer::get_mutex(), kcenon::logger::file_writer::integrity_policy_, kcenon::logger::make_logger_void_result(), kcenon::common::ok(), perform_rotation(), should_rotate(), and writes_since_check_.

Here is the call graph for this function:

Member Data Documentation

base_filename_

std::string kcenon::logger::rotating_file_writer::base_filename_

private

Definition at line 165 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), get_backup_files(), rotating_file_writer(), rotating_file_writer(), and rotating_file_writer().

check_interval_

size_t kcenon::logger::rotating_file_writer::check_interval_

private

Number of writes between rotation checks.

Definition at line 163 of file rotating_file_writer.h.

Referenced by write().

current_period_start_

std::chrono::system_clock::time_point kcenon::logger::rotating_file_writer::current_period_start_

private

Definition at line 168 of file rotating_file_writer.h.

Referenced by perform_rotation(), and should_rotate_by_time().

file_extension_

std::string kcenon::logger::rotating_file_writer::file_extension_

private

Definition at line 166 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), get_backup_files(), rotating_file_writer(), rotating_file_writer(), and rotating_file_writer().

last_rotation_time_

std::chrono::system_clock::time_point kcenon::logger::rotating_file_writer::last_rotation_time_

private

Definition at line 167 of file rotating_file_writer.h.

Referenced by perform_rotation().

max_files_

size_t kcenon::logger::rotating_file_writer::max_files_

private

Definition at line 162 of file rotating_file_writer.h.

Referenced by cleanup_old_files().

max_size_

size_t kcenon::logger::rotating_file_writer::max_size_

private

Definition at line 161 of file rotating_file_writer.h.

Referenced by should_rotate().

rotation_type_

rotation_type kcenon::logger::rotating_file_writer::rotation_type_

private

Definition at line 160 of file rotating_file_writer.h.

Referenced by generate_rotated_filename(), should_rotate(), and should_rotate_by_time().

writes_since_check_

size_t kcenon::logger::rotating_file_writer::writes_since_check_ {0}

private

Counter for writes since last check.

Definition at line 164 of file rotating_file_writer.h.

{0};    

Referenced by perform_rotation(), and write().

---

The documentation for this class was generated from the following files:

• include/kcenon/logger/writers/rotating_file_writer.h
• src/impl/writers/rotating_file_writer.cpp