rich-utf8-logger 0.0.1
A high-performance, thread-safe logging library with Rich console output and UTF-8 support
License: MIT
Requires Python: >=3.8
Keywords: logging, rich, console, utf8, unicode, thread-safe, file-rotation, windows

# Rich UTF-8 Logger

A high-performance, thread-safe logging library built with Python's logging module and enhanced with the Rich library for beautiful console output with full UTF-8 support.

## Features

- **Rich Console Output**: Beautiful, colored logging with the Rich library
- **Thread-Safe Queue Logging**: Asynchronous, non-blocking log processing
- **File Rotation**: Automatic log file rotation with custom naming (e.g., `app_1.log`, `app_2.log`)
- **UTF-8 Support**: Full Unicode and emoji support in log files
- **Configuration Management**: Flexible configuration via `app_config.ini`
- **Windows Optimized**: Special handling for Windows file access issues
- **Multiple Logger Types**: Console-only, file-only, and combined loggers

## Installation

```bash
pip install rich_utf8_logger
```

## Quick Start

```python
from rich_utf8_logger import get_logger

# Create a basic logger
logger = get_logger("my_app")

# Log messages
logger.info("Application started")
logger.warning("This is a warning")
logger.error("An error occurred")
```

## Logger Types

### Basic Logger
```python
from rich_logger import get_logger

logger = get_logger("app_name")
```

### File Logger with Rotation
```python
from rich_utf8_logger import get_logger_with_file_handler

logger = get_logger_with_file_handler("app_name")
```

### Queue Logger (Thread-Safe)
```python
from rich_utf8_logger import get_logger_with_queue

logger = get_logger_with_queue("app_name")
```

### Queue Logger with File Output
```python
from rich_utf8_logger import get_logger_with_queue_and_file

logger = get_logger_with_queue_and_file("app_name")
```

## Configuration

Create `app_config.ini` in your project root:

```ini
[app]
name = my_app

[logging]
level = INFO
format = %%(levelname)s %%(name)s - %%(message)s
console_format = %%(levelname)s %%(message)s
logs_dir = logs
max_bytes = 10485760
backup_count = 5
queue_enabled = true
queue_size = 100
flush_interval = 0.1
```

### Configuration Options

| Option | Description | Default |
|--------|-------------|---------|
| `level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
| `format` | Log message format for files | `%(levelname)s %(name)s - %(message)s` |
| `console_format` | Log message format for console | `%(levelname)s %(message)s` |
| `logs_dir` | Directory for log files | `logs` |
| `max_bytes` | Maximum log file size before rotation | 1MB (1048576) |
| `backup_count` | Number of backup files to keep | 5 |
| `queue_enabled` | Enable thread-safe queue logging | true |
| `queue_size` | Maximum queue size for log records | 100 |
| `flush_interval` | Queue flush interval in seconds | 0.1 |

## Log Rotation

Log files automatically rotate when they reach the configured size limit. Backup files use sequential naming:

- `app.log` (current log file)
- `app_1.log` (first backup)
- `app_2.log` (second backup)
- `app_3.log` (third backup)

## Thread Safety

The queue-based loggers provide thread-safe logging by:

- Buffering log records in a thread-safe queue
- Processing logs in a dedicated worker thread
- Non-blocking log emission
- Configurable queue size and flush intervals

## Usage Examples

### Basic Application Logging
```python
from rich_utf8_logger import get_logger

logger = get_logger("my_application")

def main():
    logger.info("Starting application")
    
    try:
        # Your application logic here
        logger.info("Application running successfully")
    except Exception as e:
        logger.error(f"Application error: {e}")
    
    logger.info("Application finished")

if __name__ == "__main__":
    main()
```

### Web Application with File Logging
```python
from rich_utf8_logger import get_logger_with_file_handler
import time

logger = get_logger_with_file_handler("web_app")

def handle_request(request_id):
    logger.info(f"Processing request {request_id}")
    time.sleep(0.1)  # Simulate work
    logger.info(f"Request {request_id} completed")

# Simulate multiple requests
for i in range(100):
    handle_request(i)
```

### High-Performance Logging
```python
from rich_utf8_logger import get_logger_with_queue_and_file
import threading
import time

logger = get_logger_with_queue_and_file("high_perf_app")

def worker(worker_id):
    for i in range(1000):
        logger.info(f"Worker {worker_id}: Message {i}")
        time.sleep(0.001)  # Very fast logging

# Start multiple worker threads
threads = []
for i in range(5):
    t = threading.Thread(target=worker, args=(i,))
    t.start()
    threads.append(t)

# Wait for completion
for t in threads:
    t.join()

# Clean up
from rich_utf8_logger import cleanup_loggers
cleanup_loggers()
```

## Performance Considerations

- **Queue Size**: Smaller queue sizes (100-1000) provide better real-time logging
- **Flush Interval**: Lower intervals (0.1-0.5s) reduce latency but increase CPU usage
- **File Rotation**: Frequent rotation can impact performance on slower storage
- **Thread Count**: More worker threads increase throughput but also resource usage

## Troubleshooting

### Console Colors Not Working
Ensure your terminal supports ANSI color codes. For Windows, use Windows Terminal or enable ANSI support.

### Log Files Not Rotating
Check that:
- File size exceeds `max_bytes` setting
- `backup_count` is greater than 0
- Application has write permissions to the logs directory

### Queue Full Warnings
Increase `queue_size` or reduce logging frequency if you see "queue is full" warnings.

### File Access Errors on Windows
The library includes special handling for Windows file access issues. If problems persist, ensure no other processes are accessing the log files.

## API Reference

### Functions

- `get_logger(name, level, config_file)` - Basic Rich logger
- `get_logger_with_file_handler(name, level, log_file, config_file)` - Logger with file output
- `get_logger_with_queue(name, level, config_file)` - Thread-safe queue logger
- `get_logger_with_queue_and_file(name, level, log_file, config_file)` - Complete solution
- `cleanup_loggers()` - Clean up all loggers and handlers

### Classes

- `WindowsSafeRotatingFileHandler` - Windows-optimized file rotation
- `ThreadSafeQueueHandler` - Asynchronous log processing

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.