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:
@@ -418,6 +418,65 @@ Then set it in your `.env` file or environment variables.
|
||||
|
||||
---
|
||||
|
||||
## Enabling Debug Logs for Third-Party Libraries
|
||||
|
||||
BanGUI suppresses verbose DEBUG logs from APScheduler and aiosqlite by default (see `Docs/Observability.md`). When troubleshooting scheduler or database issues, you can temporarily re-enable these logs.
|
||||
|
||||
### Quick method (environment variable)
|
||||
|
||||
Set `BANGUI_SUPPRESS_THIRD_PARTY_LOGS=false` and ensure `BANGUI_LOG_LEVEL=debug`:
|
||||
|
||||
```bash
|
||||
BANGUI_SUPPRESS_THIRD_PARTY_LOGS=false \
|
||||
BANGUI_LOG_LEVEL=debug \
|
||||
python -m uvicorn app.main:create_app
|
||||
```
|
||||
|
||||
This allows APScheduler and aiosqlite to inherit the application log level without editing code.
|
||||
|
||||
### Code method (for permanent changes)
|
||||
|
||||
If you need to change the level for a specific library only, edit `backend/app/main.py` inside `_configure_logging()`:
|
||||
|
||||
```python
|
||||
logging.getLogger("apscheduler").setLevel(logging.DEBUG)
|
||||
```
|
||||
|
||||
Restart the application. You will see scheduler polling messages such as:
|
||||
- `Looking for jobs to run`
|
||||
- `Next wakeup is due at ...`
|
||||
- `Running job ...`
|
||||
|
||||
### Reverting
|
||||
|
||||
Remove the environment variable or code change and restart. When suppression is re-enabled, the loggers return to `WARNING` level.
|
||||
|
||||
---
|
||||
|
||||
## Plain Text Logs Still Appearing
|
||||
|
||||
If `bangui.log` contains plain text lines that are not JSON, a library is bypassing structlog's `ProcessorFormatter`.
|
||||
|
||||
**Diagnosis:**
|
||||
|
||||
1. Identify the logger name in the plain text line (usually at the start of the line).
|
||||
2. Check whether the logger is listed in `backend/app/main.py::_configure_logging()` under the third-party overrides.
|
||||
3. Verify that `structlog.stdlib.ProcessorFormatter` is attached to all handlers:
|
||||
```python
|
||||
for handler in handlers:
|
||||
handler.setFormatter(formatter)
|
||||
```
|
||||
|
||||
**Common causes:**
|
||||
|
||||
| Cause | Fix |
|
||||
|-------|-----|
|
||||
| Library initializes its own handler after startup | Add `logging.getLogger("library_name").setLevel(logging.WARNING)` in `_configure_logging()`. |
|
||||
| Custom handler added outside `_configure_logging()` | Ensure all handlers use `structlog.stdlib.ProcessorFormatter`. |
|
||||
| Log emitted before `_configure_logging()` is called | Move logging configuration earlier in the lifespan or app factory. |
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist after following this guide:
|
||||
|
||||
Reference in New Issue
Block a user