119 lines
3.0 KiB
Markdown
119 lines
3.0 KiB
Markdown
# 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"
|
|
```
|