# Quickstart: Configurable Belief State Logging

## 1. Configuration

The logging system is configured via the `GlobalSettings` in `config.json` or through the Settings UI.

### 1.1. Default Configuration

```json
{
  "environments": [],
  "settings": {
    "backup_path": "backups",
    "logging": {
      "level": "INFO",
      "file_path": "logs/app.log",
      "max_bytes": 10485760,
      "backup_count": 5,
      "enable_belief_state": true
    }
  }
}
```

### 1.2. Changing Log Level

To change the log level to `DEBUG`, update the `logging.level` field in `config.json` or use the API:

```bash
curl -X PATCH http://localhost:8000/api/settings/global \
  -H "Content-Type: application/json" \
  -d '{
    "backup_path": "backups",
    "logging": {
      "level": "DEBUG",
      "file_path": "logs/app.log",
      "max_bytes": 10485760,
      "backup_count": 5,
      "enable_belief_state": true
    }
  }'
```

## 2. Using Belief State Logging

### 2.1. Basic Usage

Use the `belief_scope` context manager to automatically log Entry, Exit, and Coherence states.

```python
from backend.src.core.logger import logger, belief_scope

def my_function():
    with belief_scope("MyFunction"):
        # Logs: [MyFunction][Entry]
        
        logger.info("Doing something important")
        # Logs: [MyFunction][Action] Doing something important
        
        # ... logic ...
        
        # Logs: [MyFunction][Coherence:OK]
        # Logs: [MyFunction][Exit]
```

### 2.2. Error Handling

If an exception occurs within the scope, it is caught, logged as a failure, and re-raised.

```python
def failing_function():
    with belief_scope("FailingFunc"):
        raise ValueError("Something went wrong")
        
    # Logs: [FailingFunc][Entry]
    # Logs: [FailingFunc][Coherence:Failed] Something went wrong
    # Re-raises ValueError
```

### 2.3. Custom Messages

You can provide an optional message to `belief_scope`.

```python
with belief_scope("DataProcessor", "Processing batch #1"):
    # Logs: [DataProcessor][Entry] Processing batch #1
    pass
```

## 3. Log Output Format

### 3.1. Standard Log

```text
[2025-12-26 10:00:00,000][INFO][superset_tools_app] System initialized
```

### 3.2. Belief State Log

```text
[2025-12-26 10:00:01,000][INFO][superset_tools_app] [MyFunction][Entry]
[2025-12-26 10:00:01,050][INFO][superset_tools_app] [MyFunction][Action] Processing data
[2025-12-26 10:00:01,100][INFO][superset_tools_app] [MyFunction][Coherence:OK]
[2025-12-26 10:00:01,100][INFO][superset_tools_app] [MyFunction][Exit]