util.nix/package/c/hectic/docs/file_logging.md

File Logging in Hectic Library

This document covers the file logging functionality in the Hectic library, including its configuration and usage in different scenarios.

Overview

Hectic's logging system now supports logging to files, offering three output modes:

1. Stderr only (default)
2. File only
3. Both stderr and file

This gives you flexibility to route logs where they're most needed while maintaining the same structured logging interface.

Configuration Methods

1. Environment Variables

Configure logging with environment variables:

# Set log file path
export LOG_FILE=/path/to/your/logfile.log

# Set output mode (STDERR_ONLY, FILE_ONLY, BOTH)
export LOG_OUTPUT_MODE=BOTH

# Set log level as usual
export LOG_LEVEL=DEBUG

# Run your application
./your_program

2. Programmatic Configuration

Configure logging in your code:

#include "hectic.h"

int main() {
    // Initialize logger
    logger_init();
    
    // Set log file (returns 0 on success, -1 on failure)
    if (logger_set_file("/path/to/logfile.log") != 0) {
        raise_exception("Failed to open log file");
        return 1;
    }
    
    // Set output mode
    logger_set_output_mode(LOG_OUTPUT_BOTH);
    
    // Your application code here
    raise_info("Application started");
    
    // Clean up on exit
    logger_free();
    
    return 0;
}

Output Modes

LOG_OUTPUT_STDERR_ONLY (Default)

• All log messages go to stderr only
• No file output even if a log file is set

LOG_OUTPUT_FILE_ONLY

• All log messages go to the log file only
• Nothing is printed to stderr (useful for daemon processes)
• ANSI color codes are automatically stripped from file output

LOG_OUTPUT_BOTH

• All log messages go to both stderr and the log file
• ANSI colors appear on stderr but are stripped from file output

File Handling Details

• Log files are opened in append mode
• The library automatically flushes after each log message to ensure logs are written immediately
• ANSI color codes are automatically stripped from file output to avoid cluttering log files with escape sequences
• If a file cannot be opened, an error message is printed to stderr

API Reference

Setting the Log File

int logger_set_file(const char *file_path);

• Parameters: file_path - Path to the log file, or NULL to disable file logging
• Returns: 0 on success, -1 on failure (e.g., unable to open file)
• Notes:
  • Automatically closes any previously opened log file
  • Opens the new file in append mode
  • If NULL is passed, disables file logging and resets output mode to stderr only

Setting the Output Mode

void logger_set_output_mode(LogOutputMode mode);

• Parameters: mode - One of LOG_OUTPUT_STDERR_ONLY, LOG_OUTPUT_FILE_ONLY, or LOG_OUTPUT_BOTH
• Notes:
  • Has no effect if file logging is not configured and mode is file-related
  • Does not check if the log file is successfully opened

Example

See examples/file_logging_example.c for a complete working example of file logging.

Best Practices

1. Always check the return value of logger_set_file():

   if (logger_set_file("/path/to/logfile.log") != 0) {
       // Handle error
   }
   

2. Use appropriate output modes:

   • For interactive CLI applications: LOG_OUTPUT_STDERR_ONLY or LOG_OUTPUT_BOTH
   • For daemon/service applications: LOG_OUTPUT_FILE_ONLY
   • For debugging sessions: LOG_OUTPUT_BOTH

3. Consider log rotation: The library doesn't handle log rotation, so for long-running applications, consider external log rotation solutions.

4. Close properly: Always call logger_free() to ensure log files are properly closed.