# 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"
```