132 lines
3.8 KiB
Markdown
Executable File
132 lines
3.8 KiB
Markdown
Executable File
# 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:
|
|
|
|
```sh
|
|
# 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:
|
|
|
|
```c
|
|
#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
|
|
|
|
```c
|
|
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
|
|
|
|
```c
|
|
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()`**:
|
|
```c
|
|
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. |