Summary

Document the log server (server/log_server.h) for centralized log collection and the crash-safe logger (safety/crash_safe_logger.h) for guaranteed log persistence during application crashes.

Parent Issue

Part of: [EPIC] docs: Address documentation gaps across all ecosystem systems (kcenon/common_system#325)

Background (Why)

logger_system includes two advanced features that are completely undocumented:

1. Log Server — A network-accessible log collection server that receives logs from remote network_writer clients
2. Crash-Safe Logger — Ensures log data survives application crashes through techniques like memory-mapped files or write-ahead logging

Both are critical for production deployments but users cannot discover or configure them.

Source files:

• include/kcenon/logger/server/log_server.h — Log collection server
• include/kcenon/logger/safety/crash_safe_logger.h — Crash-resistant logging

Scope (What)

1. Log Server (log_server.h)

Architecture

• Server role in distributed logging topology
• Protocol for client-server communication
• Relationship with network_writer (client side)

API Reference

• Server creation and configuration
• Start/stop lifecycle
• Client connection management
• Authentication and authorization (if any)
• TLS support for encrypted transport

Configuration

auto server = log_server::create()
    .bind("0.0.0.0", 9500)
    .max_clients(100)
    .with_tls(cert_path, key_path)
    .storage(rotating_file_writer{"server_logs/"})
    .build();
server.start();

Deployment Patterns

• Single server with multiple application clients
• Log aggregation architecture
• Integration with existing log infrastructure (ELK, Loki)

2. Crash-Safe Logger (crash_safe_logger.h)

Crash Safety Mechanism

• How logs survive process crashes
• Write-ahead log or memory-mapped file approach
• Recovery procedure on restart

API Reference

• How to enable crash-safe mode
• Performance overhead vs standard logging
• Recovery API for reading crash logs

Configuration

• Crash log file location
• Buffer size and sync policy
• Recovery on startup behavior

When to Use

• Critical financial/medical applications
• Debugging intermittent crashes
• Compliance requirements for log completeness

3. Combined Usage

• Crash-safe local logging + network forwarding
• Server-side crash safety
• Complete production logging topology

Acceptance Criteria

• Log server architecture documented with diagram
• Log server API fully documented
• Server configuration examples provided
• Crash-safe logger mechanism explained
• Crash-safe logger API documented
• Recovery procedure documented
• Performance overhead noted for both features
• Deployment topology examples