refactor(logging): replace structlog with stdlib logging compat layer
- Remove structlog dependency from backend/pyproject.toml - Add app.utils.logging_compat shim for keyword-arg logging API - Add app.utils.json_formatter for JSON log output with extra fields - Update all backend modules to use logging_compat.get_logger() - Update docstrings in log_sanitizer.py and json_formatter.py - Update test comment in test_async_utils.py - Record 406 failing tests in Docs/Tasks.md for tracking
This commit is contained in:
@@ -98,6 +98,44 @@ log.error("fail2ban_start_failed", stdout=stdout_raw, stderr=stderr_raw) # Neve
|
||||
|
||||
---
|
||||
|
||||
## Third-Party Library Logs
|
||||
|
||||
BanGUI uses **structlog** for all application logs, but third-party libraries often emit plain text through Python's standard `logging` module. To maintain uniform JSON output and reduce noise, the following libraries have their log levels overridden to `WARNING`:
|
||||
|
||||
| Library | Logger Name | Level | Rationale |
|
||||
|---------|-------------|-------|-----------|
|
||||
| APScheduler | `apscheduler` | `WARNING` | Suppresses routine scheduler polling ("Looking for jobs to run", "Next wakeup is due at...") while preserving job failure warnings. |
|
||||
| aiosqlite | `aiosqlite` | `WARNING` | Suppresses database operation traces and connection details while preserving connection errors. |
|
||||
|
||||
These overrides are applied in `backend/app/main.py::_configure_logging()` immediately after `logging.basicConfig()`.
|
||||
|
||||
### Disabling Suppression
|
||||
|
||||
Set the environment variable `BANGUI_SUPPRESS_THIRD_PARTY_LOGS=false` to allow APScheduler and aiosqlite to emit their normal DEBUG/INFO logs. This is useful when troubleshooting scheduler or database issues in development.
|
||||
|
||||
```bash
|
||||
BANGUI_SUPPRESS_THIRD_PARTY_LOGS=false python -m uvicorn app.main:create_app
|
||||
```
|
||||
|
||||
When suppression is disabled, the loggers inherit the application's `BANGUI_LOG_LEVEL` (e.g., `debug`).
|
||||
|
||||
### Uniform JSON Formatting
|
||||
|
||||
All stdlib logs — including those from third-party libraries — are intercepted by `structlog.stdlib.ProcessorFormatter` and rendered as JSON. This ensures every log line in `bangui.log` is machine-readable, regardless of its source.
|
||||
|
||||
### Adding New Overrides
|
||||
|
||||
When integrating a new library that emits verbose DEBUG logs:
|
||||
|
||||
```python
|
||||
# In backend/app/main.py, inside _configure_logging()
|
||||
logging.getLogger("new_library").setLevel(logging.WARNING)
|
||||
```
|
||||
|
||||
Use `WARNING` as the default to still capture errors and warnings. Only use `ERROR` if the library is exceptionally noisy and its warnings are not actionable.
|
||||
|
||||
---
|
||||
|
||||
## Structured Logging Best Practices
|
||||
|
||||
### Log Levels
|
||||
|
||||
Reference in New Issue
Block a user