104 lines
3.7 KiB
Markdown
104 lines
3.7 KiB
Markdown
# Technical Plan: Task Logging System (Separated Per-Task Logs)
|
|
|
|
**Feature Branch**: `018-task-logging-v2`
|
|
**Specification**: [`specs/018-task-logging-v2/spec.md`](specs/018-task-logging-v2/spec.md)
|
|
**Created**: 2026-02-07
|
|
**Status**: Draft
|
|
|
|
## 1. Architecture Overview
|
|
|
|
The system will transition from in-memory JSON logging to a persistent, source-attributed logging architecture.
|
|
|
|
### 1.1. Component Diagram
|
|
|
|
```mermaid
|
|
graph TD
|
|
subgraph Backend
|
|
P[Plugin] -->|uses| TC[TaskContext]
|
|
TC -->|delegates| TL[TaskLogger]
|
|
TL -->|calls| TM[TaskManager]
|
|
TM -->|buffers| LB[LogBuffer]
|
|
LB -->|periodic flush| LPS[LogPersistenceService]
|
|
LPS -->|SQL| DB[(SQLite: task_logs)]
|
|
TM -->|broadcast| WS[WebSocket Server]
|
|
end
|
|
subgraph Frontend
|
|
WS -->|stream| TLP[TaskLogPanel]
|
|
API[REST API] -->|fetch history| TLP
|
|
TLP -->|render| UI[Log UI]
|
|
end
|
|
```
|
|
|
|
## 2. Database Schema
|
|
|
|
A new table `task_logs` will be added to the primary database.
|
|
|
|
| Column | Type | Constraints |
|
|
|--------|------|-------------|
|
|
| `id` | Integer | Primary Key, Autoincrement |
|
|
| `task_id` | String | Foreign Key (tasks.id), Indexed |
|
|
| `timestamp` | DateTime | Not Null, Indexed |
|
|
| `level` | String(16) | Not Null (INFO, WARNING, ERROR, DEBUG) |
|
|
| `source` | String(64) | Not Null, Default: 'system' |
|
|
| `message` | Text | Not Null |
|
|
| `metadata_json` | Text | Nullable (JSON string) |
|
|
|
|
## 3. Backend Implementation Details
|
|
|
|
### 3.1. `TaskLogger` & `TaskContext`
|
|
- `TaskLogger`: A wrapper around `TaskManager._add_log` that carries `task_id` and `source`.
|
|
- `TaskContext`: A container passed to `plugin.execute()` providing the logger and other task-specific utilities.
|
|
|
|
### 3.2. `TaskManager` Enhancements
|
|
- **Log Buffer**: A dictionary mapping `task_id` to a list of pending `LogEntry` objects.
|
|
- **Flusher Thread**: A background daemon thread that flushes the buffer to the database every 2 seconds.
|
|
- **Backward Compatibility**: Use `inspect.signature` to detect if a plugin's `execute` method accepts the new `context` parameter.
|
|
|
|
### 3.3. API Endpoints
|
|
- `GET /api/tasks/{task_id}/logs`: Supports `level`, `source`, `search`, `offset`, and `limit`.
|
|
- `GET /api/tasks/{task_id}/logs/stats`: Returns counts by level and source.
|
|
- `GET /api/tasks/{task_id}/logs/sources`: Returns unique sources for the task.
|
|
|
|
## 4. Frontend Implementation Details
|
|
|
|
### 4.1. Components
|
|
- `TaskLogPanel`: Main container managing state and data fetching.
|
|
- `LogFilterBar`: UI for selecting filters.
|
|
- `LogEntryRow`: Optimized row rendering with color coding and progress bar support.
|
|
|
|
### 4.2. Data Fetching
|
|
- **Live Tasks**: Connect via WebSocket with filter parameters in the query string.
|
|
- **Completed Tasks**: Fetch via REST API with pagination.
|
|
|
|
## 5. Implementation Phases
|
|
|
|
### Phase 1: Foundation
|
|
- Database migration (new table).
|
|
- `LogPersistenceService` implementation.
|
|
- `TaskLogger` and `TaskContext` classes.
|
|
|
|
### Phase 2: Core Integration
|
|
- `TaskManager` buffer and flusher logic.
|
|
- API endpoint updates.
|
|
- WebSocket server-side filtering.
|
|
|
|
### Phase 3: Plugin Migration
|
|
- Update core plugins (Backup, Migration, Git) to use the new logger.
|
|
- Verify backward compatibility with un-migrated plugins.
|
|
|
|
### Phase 4: Frontend
|
|
- Implement new Svelte components.
|
|
- Integrate with updated API and WebSocket.
|
|
|
|
## 6. Verification Plan
|
|
|
|
- **Unit Tests**:
|
|
- `TaskLogger` correctly routes to `TaskManager`.
|
|
- `LogPersistenceService` handles batch inserts and complex filters.
|
|
- `TaskManager` flushes logs on task completion.
|
|
- **Integration Tests**:
|
|
- End-to-end flow from plugin log to frontend display.
|
|
- Verification of log persistence after server restart.
|
|
- **Performance Tests**:
|
|
- Measure overhead of batch logging under high load (1000+ logs/sec).
|