===============
LIBRARY RULES
===============
From library maintainers:
- Use the factory function corelog(app_name) to create logger instances
- Handlers are lazily loaded only when needed - reduces memory footprint
- Configuration uses hierarchical YAML files with environment variable overrides
- Mail handler only activates for EMERGENCY_MAIL level and above
- Use CLI commands for testing: corelog test, corelog db-test, corelog mail-test
- Remote logging uses TCP server on port 9020 with JSON message format
- Smart handler loading prevents duplicate email notifications
- Configuration is cached globally - use force_reload=True to refresh

### Utilize CoreLog Interactive Setup Wizard

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to run the CoreLog interactive setup wizard after installation. The wizard allows for a complete initial setup or granular configuration of individual components like base settings, colors, and various handlers.

```bash
# Full setup wizard (recommended for initial installation)
corelog init all

# Or configure individual components:
corelog init base      # Base settings
corelog init colors    # Color configuration
corelog init file      # File handler
corelog init sqlite    # SQLite handler
corelog init mail      # Mail handler
corelog init server    # Server configuration
corelog init docker    # Docker setup
```

--------------------------------

### Manually Start CoreLog Server

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This section provides various command-line options to start the CoreLog server directly using Python or the `corelog` CLI. It includes examples for foreground debugging and starting with a custom configuration.

```bash
# Start the server directly
python -m corelog.server

# Start the server via CLI
corelog server start

# Start the server in the foreground (for debugging)
corelog server start --foreground

# Start the server with a specific configuration
corelog server start --config custom_server_config.yaml --host 0.0.0.0 --port 9025
```

--------------------------------

### CoreLog Docker Server Quick Start

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Provides a quick guide to setting up and running the CoreLog remote logging server using Docker Compose, including commands for cloning the repository, starting the server, and checking its status and logs.

```bash
# Clone the repository
git clone https://github.com/your-username/corelog.git
cd corelog

# Start the server with Docker
docker-compose up -d --build

# Check status
docker-compose ps
docker-compose logs -f
```

--------------------------------

### Comprehensive CoreLog Debugging Setup

Source: https://github.com/el-peppo/corelog/blob/main/README.md

A complete setup for enabling full debugging across CoreLog, including global and internal debug levels, timing, and forced color output, followed by an example execution.

```bash
# Full debug setup
export corelog_LEVEL=DEBUG
export corelog_INTERNAL_LEVEL=DEBUG
export corelog_TIMING=true
export FORCE_COLOR=1

# Execute with full debugging
python my_script.py
```

--------------------------------

### Run CoreLog Server with Docker Compose

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Instructions for cloning the CoreLog repository and deploying the server using Docker Compose. This method is recommended for ease of setup and includes commands to start, view logs, and stop the service.

```bash
git clone https://github.com/your-username/corelog.git
cd corelog

# Starts the server in the background and builds the image on the first run
docker-compose up -d --build

# View server logs
docker-compose logs -f

# Stop the server
docker-compose down
```

--------------------------------

### Set Up CoreLog Development Environment

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Instructions for cloning the CoreLog repository, creating and activating a Python virtual environment, installing development dependencies, and setting up pre-commit hooks.

```bash
# Clone the repository
git clone https://github.com/your-username/corelog.git
cd corelog

# Create a virtual environment
python -m venv .venv

# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install
```

--------------------------------

### CoreLog Dockerfile for Containerization

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This Dockerfile defines the build process for the CoreLog application, starting from a Python 3.11 slim image. It sets up the working directory, installs dependencies from `requirements.txt`, copies the application code, and specifies the command to run the CoreLog server upon container startup, facilitating reproducible deployments.

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "-m", "corelog.server"]
```

--------------------------------

### Install CoreLog as a Python Package

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to install CoreLog as a Python package from the local repository. This covers both standard installation for usage and editable installation for development purposes.

```bash
# In the main directory of the cloned CoreLog project
pip install .

# Or for development:
pip install -e .
```

--------------------------------

### Examples of Structured Context Data Logging in CoreLog (Python)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Provides practical examples of how to log diverse structured context data using CoreLog's `info`, `error`, and `debug` methods. It demonstrates attaching key-value pairs for user activity, database connection issues, and API performance metrics, enabling rich, searchable log entries.

```python
log = corelog("WebService")

# User-related logs
log.info(
    "User logged in",
    user_id=12345,
    ip_address="192.168.1.100",
    browser="Chrome/91.0",
    login_duration_ms=234,
    session_id="sess_abc123",
    geographic_location="DE-BY"
)

# Error logs with comprehensive context
log.error(
    "Database connection failed",
    database="customers",
    connection_string="postgresql://localhost:5432/customers",
    timeout_seconds=30,
    retry_count=3,
    error_code="CONN_TIMEOUT",
    last_successful_connection="2024-01-15T14:30:00Z",
    resource_usage={
        "cpu_percent": 85.2,
        "memory_mb": 512,
        "open_connections": 47
    }
)

# Performance monitoring
log.debug(
    "API request processed",
    endpoint="/api/v1/users",
    method="GET",
    response_time_ms=142,
    status_code=200,
    request_size_bytes=1024,
    response_size_bytes=4096,
    cache_hit=True
)
```

--------------------------------

### CoreLog Handler Lifecycle Examples

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Illustrates the lifecycle of CoreLog handlers, including lazy initialization upon the first log message, smart loading for specific handlers, and proper shutdown procedures.

```python
# 1. Logger creation (without handlers)
logger = corelog("MyApp")

# 2. First log message triggers handler initialization
logger.info("First message")  # Handlers are now created

# 3. Smart Loading for MailHandler
logger.emergency_mail("Critical!")  # MailHandler is created
logger.info("Normal info")           # MailHandler is NOT created

# 4. Shutdown closes only created handlers
logger.shutdown()  # Only handlers that were actually created are closed
```

--------------------------------

### Validate CoreLog Development Environment Setup

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to set debug levels and validate all components of a CoreLog development environment, including base initialization, tests, database, mail, and remote connectivity.

```bash
export corelog_LEVEL=DEBUG
export corelog_INTERNAL_LEVEL=DEBUG
export corelog_TIMING=true

# Test all components
corelog init base --validate
corelog test --app DevTest
corelog db-test --all
corelog mail-test --simulate --all-levels
corelog remote-test --connection --send --performance
```

--------------------------------

### Python Typer CLI Command Template

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This example illustrates how to develop a new command-line interface (CLI) command using the Typer library. It demonstrates defining command options with type annotations and help text, loading application configuration, utilizing `rich.console` for formatted output, and implementing robust error handling with `typer.Exit`.

```python
import typer
from typing_extensions import Annotated
from rich.console import Console

from ..config import load_core_config
from .cli_utils import load_cli_colors, get_style

console_custom = Console()

def custom_command_func(
    option1: Annotated[str, typer.Option("--option1", "-o", help="Description")] = "default",
    flag: Annotated[bool, typer.Option("--flag", "-f", help="Boolean Flag")] = False,
):
    """Description of the new command."""
    
    cli_colors = load_cli_colors()
    
    try:
        config = load_core_config()
        
        # Command logic here
        console_custom.print(f"Executing custom command with {option1}", 
                            style=get_style('info', cli_colors))
        
        if flag:
            console_custom.print("Flag is enabled", style=get_style('success', cli_colors))
            
    except Exception as e:
        console_custom.print(f"❌ Error: {str(e)}", style=get_style('error', cli_colors))
        raise typer.Exit(1)
```

--------------------------------

### Manage CoreLog Docker Container via CLI

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Illustrates how to manage the CoreLog Docker container directly using the `corelog docker` CLI commands, covering operations like starting, checking status, viewing logs, stopping, and rebuilding the container.

```bash
# Start the server container
corelog docker start

# Status of the container
corelog docker status

# Show live logs
corelog docker logs -f

# Stop the container
corelog docker stop

# Rebuild the image and restart the container
corelog docker rebuild
```

--------------------------------

### Email Template Dynamic Color Generation Example

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Demonstrates how the email template system automatically generates CSS styles based on a `colors.yaml` configuration. This Python dictionary example shows the resulting styles for a 'CRITICAL' log level, including background color, text color, border, and accent color, which are then injected into the HTML template.

```python
# Auto-generated styles for CRITICAL level:
{
    "level_header_style": "background-color: #FF0000; color: #FFFFFF; font-weight: bold;",
    "level_badge_style": "background-color: #FFFFFF; color: #FF0000; border: 2px solid #FF0000;",
    "level_accent_color": "#FF0000"
}
```

--------------------------------

### CoreLog Threading Models - MailHandler

Source: https://github.com/el-peppo/corelog/blob/main/README.md

An incomplete code snippet showing the start of a threading model for the MailHandler, typically involving `threading` and `queue` modules.

```python
import threading
from queue import Queue
```

--------------------------------

### Python CoreLog Integration Test with SQLite

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This snippet demonstrates a full integration test for the CoreLog library, including temporary database setup, logger configuration, message logging, and verification of the logged data in an SQLite database. It showcases how to use `corelog` with a `sqlite` handler and assert the correctness of stored logs.

```python
import tempfile
import sqlite3
from pathlib import Path
from corelog import corelog

class TestIntegration:
    def test_full_logging_pipeline(self):
        # Temporary database for the test
        with tempfile.TemporaryDirectory() as temp_dir:
            db_path = Path(temp_dir) / "test.db"
            
            # Test configuration
            test_config = {
                "logger": {
                    "level": "DEBUG",
                    "handlers": {"console": True, "sqlite": True}
                },
                "sqlite": {"db_path": str(db_path)},
                "colors": {}
            }
            
            # Create and test the logger
            logger = corelog("IntegrationTest", config_override=test_config)
            logger.info("Integration test message", test_id=12345)
            logger.shutdown()
            
            # Verification in the database
            conn = sqlite3.connect(str(db_path))
            cursor = conn.cursor()
            cursor.execute("SELECT app, level, message, context FROM logs")
            rows = cursor.fetchall()
            
            assert len(rows) == 1
            assert rows[0][0] == "IntegrationTest"
            assert rows[0][1] == "INFO"
            assert "Integration test message" in rows[0][2]
            assert "test_id" in rows[0][3]
```

--------------------------------

### Python Pytest Unit Tests for Corelog Logger

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This snippet provides unit test examples for the `corelog` logger using Pytest and `unittest.mock`. It covers testing logger instantiation, verifying lazy loading of handlers, and asserting that handlers are called correctly with appropriate `LogRecord` objects using mock objects.

```python
# tests/test_logger.py
import pytest
from unittest.mock import Mock, patch
from corelog import corelog
from corelog.logger import LogRecord

class TestCoreLogger:
    def test_logger_creation(self):
        logger = corelog("TestApp")
        assert logger.app_name == "TestApp"
        
    def test_lazy_loading(self):
        logger = corelog("TestApp")
        # Handlers should not be created yet
        assert len(logger._active_handlers) == 0
        
        # After the first log, handlers should be created
        logger.info("Test message")
        assert len(logger._active_handlers) > 0
        
    @patch('corelog.handlers.console_handler.ConsoleHandler.handle')
    def test_console_handler_called(self, mock_handle):
        logger = corelog("TestApp")
        logger.info("Test message", test_param="value")
        
        # Verify handler was called with the correct LogRecord
        mock_handle.assert_called_once()
        record = mock_handle.call_args[0][0]
        assert isinstance(record, LogRecord)
        assert record.msg == "Test message"
        assert record.ctx["test_param"] == "value"
```

--------------------------------

### Bash Conventional Commit Message Examples

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This snippet provides examples of conventional commit messages, outlining the `type(scope): description` format. It illustrates common commit types like `feat`, `fix`, `docs`, `test`, and `refactor`, along with their typical usage for different aspects of a project.

```bash
# Format: type(scope): description

feat(handlers): Add webhook handler for HTTP endpoints
fix(mail): Resolve SMTP authentication issue with OAuth2
docs(readme): Update installation instructions for Docker
test(integration): Add comprehensive SQLite handler tests
refactor(cli): Improve error handling in backup commands
```

--------------------------------

### CoreLog Handler Development Template

Source: https://github.com/el-peppo/corelog/blob/main/README.md

An empty Python code block serving as a placeholder or starting point for developing custom CoreLog handlers, implying a Python context for extending the CoreLog system.

```python

```

--------------------------------

### Resolve CoreLog Terminal Color Display Issues

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to diagnose and force color output in the console for CoreLog, including checking terminal type and Windows Terminal setup.

```bash
# Diagnosis
corelog colors --test

# Solutions
# 1. Force colors:
export FORCE_COLOR=1

# 2. Check terminal type:
echo $TERM
echo $COLORTERM

# 3. Windows Terminal setup:
export WT_SESSION=1

# 4. Reset color system:
corelog colors --reset
```

--------------------------------

### Troubleshoot CoreLog Docker Container Startup

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to diagnose and resolve common Docker container startup problems for CoreLog, such as port conflicts, volume permissions, and image build issues.

```bash
# Diagnosis
docker-compose logs corelog-server

# Common causes and solutions
# 1. Port already in use:
netstat -tulpn | grep 9020
# Change port in docker-compose.yml

# 2. Volume permissions:
sudo chown -R $USER:$USER ./corelog_server_data

# 3. Image build problems:
docker-compose build --no-cache
docker-compose up -d

# 4. Configuration validation:
docker-compose config
```

--------------------------------

### CoreLog Live Log Monitoring Commands

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands for real-time log monitoring using CoreLog's `show --follow` feature. This allows users to stream live log entries, with options to filter by log level, application name, and time, providing immediate insights into system activity.

```bash
# Live log monitoring with filters
corelog show --follow --level ERROR
corelog show --follow --app WebService --lines 20

# Combined filters with live updates
corelog show --follow --level CRITICAL --since 1h
```

--------------------------------

### CoreLog Performance Timing System Activation

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to enable detailed performance measurements within CoreLog by setting specific environment variables. This allows for logging the execution times of individual handlers, which is crucial for identifying and optimizing performance bottlenecks.

```bash
# Enable detailed performance measurements
export corelog_LEVEL=DEBUG
export corelog_TIMING=true

# Show execution times for each handler
python my_script.py
```

--------------------------------

### Analyze CoreLog Performance and Optimize Handlers

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to enable detailed timing and debug logging for CoreLog, along with optimization suggestions for various handlers like FileHandler, SQLiteHandler, MailHandler, and RemoteHandler.

```bash
# Performance analysis
export corelog_TIMING=true
export corelog_LEVEL=DEBUG
```

--------------------------------

### Run CoreLog Code Quality Checks

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands for formatting, linting, type-checking, and running tests for the CoreLog project, including a command to execute all pre-commit checks.

```bash
# Code formatting
black corelog/
isort corelog/

# Linting
flake8 corelog/

# Type-checking
mypy corelog/

# Run tests
pytest
pytest --cov=corelog --cov-report=html

# Run all checks at once
pre-commit run --all-files
```

--------------------------------

### CoreLog Project Directory Structure Overview

Source: https://github.com/el-peppo/corelog/blob/main/README.md

An overview of the CoreLog project's file and directory organization, detailing the purpose of key modules, CLI commands, handlers, and configuration files.

```plaintext
corelog/
├── __init__.py                    # Main API, factory function, internal logger
├── assets/
│   └── corelog-logo.png          # Logo for mail templates
├── cli_commands/                  # Modules for individual CLI commands
│   ├── __init__.py
│   ├── backups_cmd.py            # Backup management
│   ├── cli_utils.py              # Helper functions for CLI
│   ├── colors_cmd.py             # Color management
│   ├── config_cmd.py             # Configuration display
│   ├── db_cmd.py                 # Database management
│   ├── db_test_cmd.py            # Database tests
│   ├── docker_cmd.py             # Docker management
│   ├── log_cmd.py                # Log creation
│   ├── mail_cmd.py               # Direct email dispatch
│   ├── mail_test_cmd.py          # Mail system tests
│   ├── query_cmd.py              # Structured log search
│   ├── remote_test_cmd.py        # Remote logging tests
│   ├── server_cmd.py             # Server management
│   ├── show_cmd.py               # Advanced log display
│   ├── stats_cmd.py              # Log statistics
│   ├── tail_cmd.py               # Log display (tail-like)
│   ├── test_cmd.py               # General tests
│   ├── version_cmd.py            # Version information
│   └── init/                     # Interactive setup wizards
│       ├── __init__.py
│       ├── all_cmd.py            # Complete setup wizard
│       ├── base_cmd.py           # Base configuration
│       ├── colors_cmd.py         # Color setup
│       ├── docker_cmd.py         # Docker setup
│       ├── file_cmd.py           # File handler setup
│       ├── init_utils.py         # Helper functions for setup
│       ├── mail_cmd.py           # Mail handler setup
│       ├── server_cmd.py         # Server setup
│       └── sqlite_cmd.py         # SQLite handler setup
├── cli.py                        # Main CLI application (Typer)
├── config.py                     # Loading and managing YAML configuration
├── constants.py                  # Log level constants
├── handlers/                     # Log handler implementations
│   ├── __init__.py
│   ├── base_handler.py          # Base handler class
│   ├── console_handler.py       # Console output
│   ├── file_handler.py          # File logging
│   ├── mail_handler.py          # Email notifications
│   ├── remote_handler.py        # Remote logging
│   └── sqlite_handler.py        # SQLite database
├── logger.py                     # CoreLogger class and LogRecord
├── server.py                     # TCP server for remote logging
├── configs/                      # Default configuration files
│   ├── main.yaml                 # Main configuration for clients
│   ├── server_main.yaml          # Main configuration for the server
│   ├── colors.yaml               # Color definitions
│   ├── mail_template.html        # HTML template for email notifications
│   └── handlers/
│       ├── file.yaml             # FileHandler configuration
│       ├── mail.yaml             # MailHandler configuration
│       └── sqlite.yaml           # SQLiteHandler configuration
├── Dockerfile                    # Docker image for the server
├── docker-compose.yml            # Docker Compose for easy deployment
└── requirements.txt              # Python dependencies
```

--------------------------------

### CoreLog Command-Line Interface (CLI) Commands

Source: https://github.com/el-peppo/corelog/blob/main/README.md

A comprehensive list of CoreLog CLI commands, categorized by their functionality, providing an overview of log management, database operations, testing, and system administration capabilities.

```APIDOC
CoreLog CLI Commands:
  General Usage:
    python -m corelog.cli [COMMAND] [OPTIONS]
    corelog [COMMAND] [OPTIONS]
    corelog --help
    corelog [COMMAND] --help

  Command Categories:
    Log Creation & Display:
      log: Sends a log message to the CoreLog system.
      tail: Displays the latest log entries from the SQLite database.
      show: Advanced log display with filtering by time, app, level, and live monitoring.
      query: Searches logs with a structured query syntax.
      stats: Shows logging statistics from the database.
    Direct Dispatch & Communication:
      mail: Sends emails directly through the CoreLog mail system.
    Database & Backups:
      db: Manages the CoreLog SQLite database (info, vacuum, delete).
      db-test: Performs tests and validations for the database.
      backup: Manages backups of the CoreLog database.
    System & Handler Tests:
      test: Sends test logs for all configured levels.
      mail-test: Tests the mail template system and email dispatch.
      remote-test: Tests remote logging and the TCP server.
    Server Management:
      server: Sub-app for managing the CoreLog server (start, stop, status, logs).
    Docker Management:
      docker: Sub-app for Docker container management (start, stop, status, logs, rebuild).
    Configuration & Setup:
      config: Displays the currently loaded configuration.
      colors: Manages and tests the CLI color configuration.
      init: Interactive setup wizards for initial configuration.
      version: Shows CoreLog version and feature overview.
```

--------------------------------

### Python Lazy Loading vs. Eager Initialization for Log Handlers

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Compares traditional eager initialization of log handlers with an optimized lazy loading approach. The CoreLog method initializes handlers only when they are actually needed, significantly reducing startup overhead and memory footprint, especially for handlers that are not always active.

```python
# Traditional approach (bad)
class Logger:
    def __init__(self):
        self.console_handler = ConsoleHandler()  # Always created
        self.file_handler = FileHandler()        # Even if not used
        self.mail_handler = MailHandler()        # Even for DEBUG logs

# CoreLog approach (optimized)
class CoreLogger:
    def __init__(self):
        self.handler_factory = HandlerFactory()
        self._active_handlers = {}  # Empty until needed
        
    def _get_active_handlers(self, current_level_name=None):
        # Create handlers only when needed
        for handler_name, enabled in self.enabled_handlers.items():
            if handler_name == "mail" and current_level_name not in trigger_levels:
                continue  # Do not create MailHandler
            # Only create if not already created
            if handler_name not in self._active_handlers:
                handler = self.handler_factory.get_handler(handler_name)
                if handler:
                    self._active_handlers[handler_name] = handler
```

--------------------------------

### Execute Full CoreLog System Diagnosis Script

Source: https://github.com/el-peppo/corelog/blob/main/README.md

A comprehensive shell script to perform a full system diagnosis for CoreLog, checking versions, configuration, handlers, database, backup, mail, server, and Docker status.

```bash
#!/bin/bash
# system_diagnosis.sh

echo "=== CoreLog System Diagnosis ==="

# 1. Version and Basic Info
corelog version

# 2. Configuration
echo "--- Configuration ---"
corelog config --section logger

# 3. Handler Tests
echo "--- Handler Tests ---"
corelog test --app DiagnosisTest

# 4. Database Status
echo "--- Database Status ---"
corelog db --info
corelog db-test --connection --schema

# 5. Backup Status
echo "--- Backup Status ---"
corelog backup --info

# 6. Mail System (if configured)
echo "--- Mail System ---"
corelog mail-test --check-config

# 7. Server Status (if running)
echo "--- Server Status ---"
corelog server status 2>/dev/null || echo "Server not running"

# 8. Docker Status (if used)
echo "--- Docker Status ---"
corelog docker status 2>/dev/null || echo "Docker not used"

echo "=== Diagnosis Complete ==="
```

--------------------------------

### Configure CoreLog Server Settings

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Define environment variables to specify the server configuration file, host, and port for the CoreLog server component.

```bash
# Server configuration file
export CORELOG_SERVER_CONFIG=custom_server.yaml

# Override server host/port
export CORELOG_SERVER_HOST=0.0.0.0
export CORELOG_SERVER_PORT=9025
```

--------------------------------

### CoreLog Configuration Loading Hierarchy

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Describes the hierarchical order in which CoreLog loads its configuration, from standard defaults to environment variable overrides.

```APIDOC
1. Standard Defaults (get_default_config)
    ↓
2. main.yaml/server_main.yaml
    ↓
3. Included Files
   ├── colors.yaml
   └── handlers/*.yaml
    ↓
4. Environment Variable Overrides
    ↓
5. Final Configuration
```

--------------------------------

### List CoreLog Development Dependencies

Source: https://github.com/el-peppo/corelog/blob/main/README.md

A list of Python packages and their minimum versions required for CoreLog development, including testing, formatting, linting, and type-checking tools.

```text
# requirements-dev.txt
pytest>=7.0.0
pytest-cov>=4.0.0
pytest-asyncio>=0.21.0
black>=23.0.0
flake8>=6.0.0
isort>=5.12.0
mypy>=1.5.0
pre-commit>=3.0.0
```

--------------------------------

### CoreLog Server Debugging Commands

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands for debugging the CoreLog server, including running it with maximum verbosity and viewing Docker container logs.

```bash
# Server with maximum verbosity
export corelog_INTERNAL_LEVEL=DEBUG
export corelog_LEVEL=DEBUG
python -m corelog.server

# Docker container debugging
corelog docker logs -f
docker-compose logs -f corelog-server
```

--------------------------------

### CoreLog Architecture Overview

Source: https://github.com/el-peppo/corelog/blob/main/README.md

An overview of the CoreLog's main components and their relationships, including the CoreLogger and various handler types.

```APIDOC
CoreLogger
├── HandlerFactory (Lazy Loading)
├── LogRecord (Data structure)
└── Handler Instances
    ├── ConsoleHandler (ANSI colors)
    ├── FileHandler (Thread-safe IO)
    ├── SQLiteHandler (WAL-Mode)
    ├── MailHandler (Async Worker)
    └── RemoteHandler (TCP Client)
```

--------------------------------

### CoreLog Basic Python Logging Usage

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This Python snippet demonstrates how to initialize and use the CoreLog logger within a Python application. It shows importing the `corelog` function and predefined log levels, then creating an application-specific logger instance to emit informational and warning messages, illustrating the simplicity of integrating CoreLog.

```python
from corelog import corelog, DEBUG, INFO, WARNING, ERROR, CRITICAL, EMERGENCY_MAIL

# Create a logger instance for a specific application
app_logger = corelog("MyBackupScript")

# Simple log messages
app_logger.info("Backup process started.")
app_logger.warning("Warning: Low disk space.")
```

--------------------------------

### Implement Contextual Logging in Python Backup Service

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Demonstrates how to integrate CoreLog into a Python class for contextual logging. It shows logging information, critical errors with custom attributes, and proper shutdown procedures, including dynamic attributes like backup_id, database, and error details.

```python
import time

class BackupService:
    def __init__(self):
        self.log = corelog("BackupService")
    
    def backup_database(self, database_name):
        backup_id = f"backup_{int(time.time())}"
        start_time = time.time()
        
        self.log.info(
            "Backup started",
            backup_id=backup_id,
            database=database_name,
            backup_type="full"
        )
        
        try:
            # Backup logic here
            backup_size = self._perform_backup(database_name)
            
            self.log.info(
                "Backup completed successfully",
                backup_id=backup_id,
                database=database_name,
                backup_size_mb=backup_size / (1024*1024),
                duration_seconds=time.time() - start_time
            )
            
        except Exception as e:
            self.log.critical(
                "Backup failed",
                backup_id=backup_id,
                database=database_name,
                error_type=type(e).__name__,
                error_message=str(e),
                custom_text="Critical backup error! Immediate intervention required."
            )
            raise
        
        finally:
            self.log.shutdown()

    def _perform_backup(self, db_name):
        # Dummy implementation
        print(f"Performing backup for {db_name}...")
        time.sleep(2)
        return 500 * 1024 * 1024 # 500MB
```

--------------------------------

### Perform CoreLog General System Checks

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Provides common commands for checking logger status, database connections, cleaning up WAL files, and setting file permissions for CoreLog data.

```bash
logger.shutdown()
lsof | grep corelog_main.db
rm corelog_data/corelog_main.db-wal
rm corelog_data/corelog_main.db-shm
chmod 664 corelog_data/corelog_main.db
chmod 755 corelog_data/
```

--------------------------------

### Debug CoreLog DatabaseHandler Issues

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Steps to diagnose and troubleshoot problems with the CoreLog DatabaseHandler, including checking connection, schema, permissions, and database integrity.

```bash
# 1. Check connection and schema
corelog db-test --connection --schema

# 2. Check permissions
ls -la corelog_data/
corelog db --info

# 3. Check integrity
corelog backup --verify
```

--------------------------------

### CoreLog SQLite Backup Restoration Workflow

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands outlining the process for restoring a CoreLog SQLite database from a backup. Steps include listing available backups, creating a safety backup before restoration, performing the restoration with prompts, and verifying database integrity post-restoration.

```bash
# 1. List current backups
corelog backup --list

# 2. Safety backup before restoration
corelog backup --create

# 3. Restore backup (with safety prompts)
corelog backup --restore corelog_main_backup_20240115_143022.db

# 4. Check integrity after restoration
corelog db-test --connection --schema
```

--------------------------------

### CoreLog BaseHandler API Reference

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Reference for the abstract `BaseHandler` class, the foundation for all CoreLog handlers. It defines the constructor and the abstract `handle` method that concrete handlers must implement.

```APIDOC
BaseHandler(ABC):
  __init__(self, config: dict)
    config: Configuration dictionary for the handler.
  handle(self, record: LogRecord)
    record: The LogRecord object to be processed. (abstract method)
  close(self)
    Closes the handler, releasing resources. (optional)
```

```python
from abc import ABC, abstractmethod
from ..logger import LogRecord

class BaseHandler(ABC):
    def __init__(self, config: dict):
        self.config = config

    @abstractmethod
    def handle(self, record: LogRecord):
        pass

    def close(self):
        pass
```

--------------------------------

### CoreLog Email Template Testing Commands

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands to simulate and test CoreLog email template rendering without actual email dispatch. Options include previewing the generated HTML, saving the output to a file, and testing the color system across different log levels.

```bash
# Test template rendering without sending an email
corelog mail-test --simulate --preview --level CRITICAL --with-context

# Save HTML output to a file
corelog mail-test --simulate --save-preview output.html --level EMERGENCY_MAIL

# Test the color system
corelog mail-test --color-test
```

--------------------------------

### CoreLog Main Application Configuration

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This YAML snippet defines the global logging settings for CoreLog, including log level, handler activation, remote logging parameters, and a mechanism for including other configuration files. It serves as the primary configuration entry point for the CoreLog application.

```yaml
logger:
  level: INFO  # Global log level
  handlers:    # Enable/disable handlers
    console: true
    file: true
    sqlite: true
    remote: false  # Set to true for remote logging
    mail: false

  remote:  # Configuration for RemoteHandler
    host: "10.1.1.5"
    port: 9020
    timeout_connect: 3.0
    timeout_send: 3.0

  includes: # List of configuration files to include
    - "colors.yaml"
    - "handlers/*.yaml"
```

--------------------------------

### Python Multi-threaded Server Connection Handling

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Demonstrates how a server can handle multiple client connections concurrently using Python's `threading` module. Each incoming connection is assigned to a new thread, allowing the server to remain responsive while processing client requests.

```python
import threading

# Multi-threaded server
class CoreLogServer:
    def _listen_for_connections(self):
        while self.running:
            client_socket, client_address = self.server_socket.accept()
            client_thread = threading.Thread(target=self._handle_client, args=(client_socket, client_address))
            client_thread.start()
```

--------------------------------

### Memory Footprint Comparison of Logger Architectures

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Illustrates the memory usage differences between a traditional logger that eagerly initializes all handlers and the CoreLog approach that employs lazy loading. This comparison highlights the significant memory savings achieved by creating handlers only on demand.

```plaintext
Traditional Logger:
├── ConsoleHandler: ~50KB
├── FileHandler: ~200KB (open file handles)
├── SQLiteHandler: ~500KB (connection pool)
├── MailHandler: ~1MB (worker thread, templates)
└── Total: ~1.75MB per logger instance

CoreLog Lazy Loading:
├── Logger Shell: ~10KB
├── Handler Factory: ~20KB
├── Active Handlers: Only when needed
└── Total: ~30KB until handlers are needed
```

--------------------------------

### Configure CoreLog FileHandler Advanced Options

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This YAML configuration snippet shows advanced settings for the CoreLog FileHandler. It covers defining the base path, file naming patterns with placeholders, rotation limits, retention policies, compression, and encoding for log files.

```yaml
file:
  base_path: "~/logs"                    # Supports ~ expansion
  pattern: "{app}/{year}/{month}/{client_ip}_{app}.{date}.log"
  max_size_mb: 10                        # Rotation limit
  keep_days: 30                          # Retention time
  compression: "gzip"                    # "gzip" or "none"
  encoding: "utf-8"                      # File encoding
```

--------------------------------

### corelog Configuration Validation and Repair (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Bash commands for validating corelog configuration, setting up missing configurations using a wizard, and repairing existing configurations. These commands help ensure the integrity and completeness of the application's settings.

```bash
# Validate configuration
corelog config --validate

# Setup wizard for missing configuration
corelog init base --check-existing

# Repair configuration
corelog init all --repair-mode
```

--------------------------------

### corelog Database Schema Migration (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Bash commands for managing corelog database schema. Includes checking the current schema version, creating a backup before migration, and commands for future schema upgrades and post-migration integrity checks.

```bash
# Check current schema version
corelog db-test --schema

# Backup before migration
corelog backup --create

# Schema migration (in the future)
# corelog db --migrate --to-version 2.0

# Check integrity after migration
corelog db-test --all
```

--------------------------------

### Correct RemoteHandler Configuration (YAML)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Illustrates the correct YAML structure for configuring corelog's RemoteHandler, emphasizing that the `remote` section must be nested directly under `logger` to avoid issues like 'Using host localhost'.

```yaml
# Correct configuration structure
logger:
  handlers:
    remote: true
  remote:          # Must be under logger!
    host: "10.1.1.5"
    port: 9020
```

--------------------------------

### corelog Log Rotation and Cleanup (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands and configuration snippets for managing log rotation and cleanup in corelog. Shows how to manually delete old database logs and references FileHandler configuration for automatic filesystem cleanup.

```bash
# Manual log cleanup
corelog db --delete --older-than 90   # Logs older than 90 days

# Filesystem cleanup (automatic via FileHandler)
# Configuration in configs/handlers/file.yaml:
# keep_days: 30
```

--------------------------------

### CoreLog's Lazy and Smart Handler Loading Mechanisms in Python

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Explains CoreLog's optimized handler management, including lazy loading where handlers are instantiated only when the first message is logged, and smart handler loading, which creates specific handlers (e.g., MailHandler) only when a log level that requires them is triggered.

```python
# Lazy Loading: Handlers are created only when needed
log = corelog("MyApp")  # No handlers initialized yet
log.info("First message")  # Now, required handlers are created

# Smart Handler Loading: MailHandler is only created if the level would trigger an email
log.emergency_mail("Critical error!")  # MailHandler is created and used
log.info("Normal info")  # MailHandler is NOT created (not a trigger level)

# Handler-specific optimizations
log.debug("Debug info")  # If the global level is higher than DEBUG, nothing is processed
```

--------------------------------

### Debug CoreLog MailHandler Issues

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Steps to diagnose and troubleshoot problems with the CoreLog MailHandler, including checking configuration, SMTP connection, template rendering, and rate limits.

```bash
# 1. Check configuration and trigger levels
corelog mail-test --check-config

# 2. Test SMTP connection
corelog mail-test --test-smtp

# 3. Test template rendering
corelog mail-test --simulate --preview

# 4. Check rate limits
ls -la .corelog_rate_limits/
```

--------------------------------

### corelog Configuration Migration (YAML)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Illustrates the configuration changes required when migrating corelog from version 0.6 to 0.7. It shows the old and new YAML structures for remote logger settings, including the addition of `handlers.remote` and timeout parameters.

```yaml
# Old configuration (v0.6)
logger:
  remote:
    host: "server"
    port: 9020

# New configuration (v0.7)
logger:
  handlers:
    remote: true
  remote:
    host: "server"
    port: 9020
    timeout_connect: 3.0
    timeout_send: 3.0
```

--------------------------------

### Diagnose RemoteHandler Connection Problems (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Bash commands for diagnosing and resolving 'Connection refused' errors with corelog's RemoteHandler. Includes steps to check server status, network connectivity, firewall rules, and validate configuration.

```bash
# Diagnosis
corelog remote-test --status --host SERVER_IP --port 9020

# Solutions
1. Check server status:
   corelog server status
   # or with Docker:
   corelog docker status

2. Test network connectivity:
   ping SERVER_IP
   telnet SERVER_IP 9020

3. Check firewall rules:
   # Open port 9020
   sudo ufw allow 9020

4. Validate configuration:
   corelog config --section logger
```

--------------------------------

### Configure CoreLog Server Environment Variables

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This snippet shows how to set environment variables to configure the CoreLog server's path, host, port, and various debugging levels. These variables control server behavior and logging verbosity.

```bash
# Server configuration
export CORELOG_SERVER_CONFIG=/path/to/custom_server.yaml
export CORELOG_SERVER_HOST=192.168.1.100
export CORELOG_SERVER_PORT=9025

# Debugging
export corelog_INTERNAL_LEVEL=DEBUG  # For server debugging
export corelog_LEVEL=DEBUG           # For general debugging
export corelog_TIMING=true           # For performance measurements
```

--------------------------------

### CoreLog Automated SQLite Backup Strategies

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Commands for managing automated SQLite database backups. This includes creating backups with retention policies (e.g., keeping 10 backups for 30 days), verifying backup integrity, and performing database maintenance operations like deleting old records and vacuuming after successful verification.

```bash
# Daily backups with retention
corelog backup --create --clean --days 30 --keep 10

# Backup integrity before important operations
corelog backup --verify
corelog db --delete --older-than 90  # Only after successful verification

# Backup before database maintenance
corelog backup --create
corelog db --vacuum
```

--------------------------------

### Runtime Configuration Override for CoreLog in Python

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Demonstrates how to dynamically override CoreLog's default configuration at runtime by passing a `config_override` dictionary during logger initialization. This allows for granular control over log levels, handler enablement (console, file, sqlite, remote), specific handler settings, and even custom color definitions for different log levels.

```python
from corelog import corelog

# Special configuration for a logger
custom_config = {
    "logger": {
        "level": "DEBUG",
        "handlers": {
            "console": True,
            "file": False,
            "sqlite": True,
            "remote": True
        },
        "remote": {
            "host": "debug-server.local",
            "port": 9021
        }
    },
    "colors": {
        "DEBUG": {"hex": "#00FFFF", "bold": True}
    }
}

log = corelog("DebugApp", config_override=custom_config)
```

--------------------------------

### CoreLog Supported Log Levels and Their Use Cases

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Documents the various log levels supported by CoreLog, outlining their numerical values and intended use cases. This includes standard levels like DEBUG, INFO, WARNING, ERROR, CRITICAL, as well as specialized levels like EMERGENCY_NOMAIL, EMERGENCY_MAIL, and FATAL.

```APIDOC
DEBUG (10): Detailed diagnostic information for development and troubleshooting.
INFO (20): General information about the normal program flow.
WARNING (30): Warnings about potential issues.
ERROR (40): Errors that can be handled.
CRITICAL (50): Critical errors that affect the program.
EMERGENCY_NOMAIL (52): Like CRITICAL, but explicitly does not trigger an email.
EMERGENCY_MAIL (55): Typically triggers an email notification.
FATAL (60): The most severe errors that lead to program termination.
```

--------------------------------

### Debug CoreLog RemoteHandler Issues

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Steps to diagnose and troubleshoot problems with the CoreLog RemoteHandler, including checking configuration, server reachability, and connection status.

```bash
# 1. Check configuration
corelog config --section logger

# 2. Test server reachability
corelog remote-test --status --host SERVER_IP --port 9020

# 3. Test connection
export corelog_INTERNAL_LEVEL=DEBUG
corelog remote-test --connection --send
```

--------------------------------

### Typical Performance Benchmarks for CoreLog Handlers

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Provides typical latency values for various CoreLog handlers, indicating the time taken for each to process a log event. This data helps in understanding performance bottlenecks and optimizing logging configurations based on expected throughput.

```plaintext
ConsoleHandler:    0.1-0.5ms   (ANSI color processing)
FileHandler:       1-5ms       (File system I/O)
SQLiteHandler:     2-8ms       (Database insert)
RemoteHandler:     10-50ms     (Network latency)
MailHandler:       0.1ms       (Queue), ~200ms (actual dispatch)
```

--------------------------------

### Automated corelog Daily Backup Script (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

A Bash script for automating daily backups of the corelog database. It creates a backup, cleans up old backups (keeping a minimum number), verifies backup integrity, and logs the completion status.

```bash
#!/bin/bash
# backup_script.sh
export corelog_LEVEL=INFO
cd /path/to/corelog

# Create backup
corelog backup --create

# Clean up old backups (30 days, keep at least 10)
corelog backup --clean --days 30 --keep 10

# Verify integrity
corelog backup --verify

# Log status
echo "$(date): Backup completed" >> /var/log/corelog_backup.log
```

--------------------------------

### CoreLog Docker Compose Configuration

Source: https://github.com/el-peppo/corelog/blob/main/README.md

This Docker Compose file defines a service for the CoreLog server, building from the local Dockerfile. It maps container port 9020 to the host, mounts a volume for persistent server data, and configures the container to restart unless explicitly stopped, facilitating easy deployment and management of the CoreLog server.

```yaml
version: '3.8'
services:
  corelog-server:
    build: .
    container_name: corelog_server
    ports:
      - "9020:9020"
    volumes:
      - "./corelog_server_data:/app/corelog_server_data"
    restart: unless-stopped
```

--------------------------------

### Configure CoreLog Client for Remote Logging

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Shows the YAML configuration snippet required in `configs/main.yaml` to enable and configure remote logging for a CoreLog client, specifying the remote host IP, port, and connection timeouts.

```yaml
logger:
  handlers:
    remote: true
  remote:
    host: "192.168.1.100"  # IP of the Docker host or server
    port: 9020
    timeout_connect: 3.0
    timeout_send: 3.0
```

--------------------------------

### corelog Regular Maintenance Tasks (Bash)

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Bash commands for performing routine maintenance on corelog. Includes weekly tasks like database optimization and backup cleanup, monthly tasks for full system tests, and commands for troubleshooting when issues arise.

```bash
# Weekly maintenance
corelog db --vacuum                    # Optimize database
corelog backup --clean --days 60       # Clean up old backups
corelog colors --test                  # Test color system

# Monthly maintenance
corelog db-test --all                  # Full DB tests
corelog mail-test --all-levels         # Test mail system
corelog remote-test --all              # Test remote system

# When issues arise
corelog test --app MaintenanceCheck   # Full system test
```

--------------------------------

### Logging Errors with Structured Context in Python

Source: https://github.com/el-peppo/corelog/blob/main/README.md

Demonstrates how to log errors using CoreLog's `error` method, attaching comprehensive structured context data such as exception type, error message, current processing step, and a stack trace. This allows for more detailed and searchable error analysis.

```python
try:
    # ... potentially faulty code ...
    raise ValueError("Something went wrong")
except ValueError as e:
    app_logger.error(
        "Error during data processing.",
        exception_type=type(e).__name__,
        error_message=str(e),
        current_step="Database-Query",
        stack_trace=True
    )
```