Better logger

LOGGING.md

@@ -0,0 +1,118 @@
+# Logging Configuration
+
+The AlpineBits Python server uses a centralized logging system that can be configured via the `config.yaml` file.
+
+## Configuration
+
+Add the following section to your `config/config.yaml`:
+
+```yaml
+logger:
+  level: "INFO" # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
+  file: "logs/alpinebits.log" # Optional: path to log file (omit or set to null for console-only)
+```
+
+### Log Levels
+
+- **DEBUG**: Detailed diagnostic information (very verbose)
+- **INFO**: General informational messages about application progress
+- **WARNING**: Warning messages about potential issues
+- **ERROR**: Error messages when something goes wrong
+- **CRITICAL**: Critical errors that may cause application failure
+
+### Log Output
+
+- **Console**: Logs are always written to console (stdout)
+- **File**: Optionally write logs to a file by specifying the `file` parameter
+  - File logs include the same timestamp and formatting as console logs
+  - Log directory will be created automatically if it doesn't exist
+
+## Usage in Code
+
+To use logging in any module:
+
+```python
+from alpine_bits_python.logging_config import get_logger
+
+_LOGGER = get_logger(__name__)
+
+# Then use the logger
+_LOGGER.info("Application started")
+_LOGGER.debug("Detailed debug information: %s", some_variable)
+_LOGGER.warning("Something unusual happened")
+_LOGGER.error("An error occurred: %s", error_message)
+_LOGGER.exception("Critical error with stack trace")
+```
+
+## Log Format
+
+All log entries include:
+
+- Timestamp (YYYY-MM-DD HH:MM:SS)
+- Module name (logger name)
+- Log level
+- Message
+
+Example:
+
+```
+2025-10-09 14:23:45 - alpine_bits_python.api - INFO - Application startup initiated
+2025-10-09 14:23:45 - alpine_bits_python.api - INFO - Logging configured at INFO level
+2025-10-09 14:23:46 - alpine_bits_python.api - INFO - Database tables checked/created at startup.
+```
+
+## Best Practices
+
+1. **Use structured logging**: Pass variables as arguments, not f-strings
+
+   ```python
+   # Good
+   _LOGGER.info("Processing reservation %s for hotel %s", reservation_id, hotel_code)
+
+   # Avoid (performance overhead, linting warnings)
+   _LOGGER.info(f"Processing reservation {reservation_id} for hotel {hotel_code}")
+   ```
+
+2. **Use appropriate log levels**:
+
+   - `DEBUG`: Detailed tracing for development
+   - `INFO`: Normal application flow events
+   - `WARNING`: Unexpected but handled situations
+   - `ERROR`: Errors that need attention
+   - `CRITICAL`: Severe errors requiring immediate action
+
+3. **Use `exception()` for error handling**:
+
+   ```python
+   try:
+       risky_operation()
+   except Exception:
+       _LOGGER.exception("Operation failed")  # Automatically includes stack trace
+   ```
+
+4. **Don't log sensitive data**: Avoid logging passwords, tokens, or personal data
+
+## Examples
+
+### Console-only logging (development)
+
+```yaml
+logger:
+  level: "DEBUG"
+```
+
+### File logging (production)
+
+```yaml
+logger:
+  level: "INFO"
+  file: "/var/log/alpinebits/app.log"
+```
+
+### Minimal logging
+
+```yaml
+logger:
+  level: "WARNING"
+  file: "logs/warnings.log"
+```