109 lines
4.0 KiB
Markdown
109 lines
4.0 KiB
Markdown
# Research: Configurable Belief State Logging
|
|
|
|
## 1. Introduction
|
|
|
|
This research explores the implementation of a configurable logging system that supports "Belief State" logging (Entry, Action, Coherence, Exit) and allows users to customize log levels, formats, and file persistence.
|
|
|
|
## 2. Analysis of Existing System
|
|
|
|
- **Language**: Python 3.9+ (Backend)
|
|
- **Framework**: FastAPI (inferred from context, though not explicitly seen in snippets, `uvicorn` mentioned)
|
|
- **Logging**: Standard Python `logging` module.
|
|
- **Configuration**: Pydantic models (`ConfigModels`) managed by `ConfigManager`, persisting to `config.json`.
|
|
- **Current Logger**:
|
|
- `backend/src/core/logger.py`:
|
|
- Uses `logging.getLogger("superset_tools_app")`
|
|
- Has `StreamHandler` (console) and `WebSocketLogHandler` (streaming).
|
|
- `WebSocketLogHandler` buffers logs in a `deque`.
|
|
|
|
## 3. Requirements Analysis
|
|
|
|
- **Belief State**: Need a structured way to log `[ANCHOR_ID][STATE] Message`.
|
|
- **Context Manager**: Need a `with belief_scope("ID"):` pattern.
|
|
- **Configuration**: Need to add `LoggingConfig` to `GlobalSettings`.
|
|
- **File Logging**: Need `RotatingFileHandler` with size limits.
|
|
- **Dynamic Reconfiguration**: Need to update logger handlers/levels when config changes.
|
|
|
|
## 4. Proposed Solution
|
|
|
|
### 4.1. Data Model (`LoggingConfig`)
|
|
|
|
We will add a `LoggingConfig` model to `backend/src/core/config_models.py`:
|
|
|
|
```python
|
|
class LoggingConfig(BaseModel):
|
|
level: str = "INFO" # DEBUG, INFO, WARNING, ERROR, CRITICAL
|
|
file_path: Optional[str] = "logs/app.log"
|
|
max_bytes: int = 10 * 1024 * 1024 # 10MB
|
|
backup_count: int = 5
|
|
enable_belief_state: bool = True
|
|
```
|
|
|
|
And update `GlobalSettings`:
|
|
|
|
```python
|
|
class GlobalSettings(BaseModel):
|
|
backup_path: str
|
|
default_environment_id: Optional[str] = None
|
|
logging: LoggingConfig = Field(default_factory=LoggingConfig)
|
|
```
|
|
|
|
### 4.2. Context Manager (`belief_scope`)
|
|
|
|
We will implement a context manager in `backend/src/core/logger.py`:
|
|
|
|
```python
|
|
from contextlib import contextmanager
|
|
|
|
@contextmanager
|
|
def belief_scope(anchor_id: str, message: str = ""):
|
|
# ... logic to log [Entry] ...
|
|
try:
|
|
yield
|
|
# ... logic to log [Coherence:OK] and [Exit] ...
|
|
except Exception as e:
|
|
# ... logic to log [Coherence:Failed] ...
|
|
raise
|
|
```
|
|
|
|
### 4.3. Logger Reconfiguration
|
|
|
|
We will add a `configure_logger(config: LoggingConfig)` function in `backend/src/core/logger.py` that:
|
|
1. Sets the logger level.
|
|
2. Removes old file handlers.
|
|
3. Adds a new `RotatingFileHandler` if `file_path` is set.
|
|
4. Updates a global flag for `enable_belief_state`.
|
|
|
|
`ConfigManager` will call this function whenever settings are updated.
|
|
|
|
### 4.4. Belief State Filtering
|
|
|
|
If `enable_belief_state` is False:
|
|
- `Entry`/`Exit` logs are skipped.
|
|
- `Action`/`Coherence` logs are logged as standard messages (maybe without the `[ANCHOR_ID]` prefix if desired, but retaining it is usually better for consistency).
|
|
|
|
## 5. Alternatives Considered
|
|
|
|
- **Alternative A**: Use a separate logger for Belief State.
|
|
- *Pros*: Cleaner separation.
|
|
- *Cons*: Harder to interleave with standard logs in the same stream/file.
|
|
- *Decision*: Rejected. We want a unified log stream.
|
|
|
|
- **Alternative B**: Use structlog.
|
|
- *Pros*: Powerful structured logging.
|
|
- *Cons*: Adds a new dependency.
|
|
- *Decision*: Rejected. Standard `logging` is sufficient and already used.
|
|
|
|
## 6. Implementation Steps
|
|
|
|
1. **Modify `backend/src/core/config_models.py`**: Add `LoggingConfig` and update `GlobalSettings`.
|
|
2. **Modify `backend/src/core/logger.py`**:
|
|
- Add `configure_logger` function.
|
|
- Implement `belief_scope` context manager.
|
|
- Implement `RotatingFileHandler`.
|
|
3. **Modify `backend/src/core/config_manager.py`**: Call `configure_logger` on init and update.
|
|
4. **Frontend**: Update Settings page to allow editing `LoggingConfig`.
|
|
|
|
## 7. Conclusion
|
|
|
|
The proposed solution leverages the existing Pydantic/ConfigManager architecture and standard Python logging, minimizing disruption while meeting all requirements. |