System Logging Infrastructure

As the dLANDiscord assistant evolved to handle numerous asynchronous background tasks, traditional console logging (log.Printf) became insufficient. The system_logs.go implementation provides a dedicated, structured logging framework.

Evolution and Context

Introduced in Git commit db8662ff, the System Logging framework was built to isolate the logs of background execution systems (Playbooks, Wakeup events, Scheduler tasks) from the conversational session logs.

Core Features

1. Per-Execution Log Files

Every time a background task runs, it generates a unique executionID (e.g., playbook_1712234567890). A dedicated .log file is created specifically for that run.

logs/playbooks/playbook_{id}.log
logs/wakeup/wakeup_{id}.log
logs/scheduler/scheduler_{id}.log

This makes debugging trivial, as the entire lifecycle of a single task is isolated in one file.

2. JSONL Structured Formatting

Logs are written in JSON Lines (JSONL) format. Each entry contains:

timestamp: ISO8601 time.
type: Event type (e.g., info, error, execution_start, execution_end).
system: The subsystem name.
content: Human-readable message.
metadata: Contextual key-value pairs (e.g., user role, task name).

3. Lifecycle Management

The SystemLogger struct ensures that:

An execution_start event is automatically injected when created.
LogExecutionEnd() calculates the total duration (DurationMs), records success/failure, and safely closes the file descriptor using sync.RWMutex to prevent the file already closed panics seen in earlier versions.

Component Diagram

graph TD
    S[Scheduler / Wakeup] --> GSL[GetSystemLogger]
    GSL --> ID[Generate Execution ID]
    ID --> SL[SystemLogger Instance]
    
    SL --> Event1[LogEvent: Start]
    SL --> Event2[LogEvent: Processing]
    SL --> End[LogExecutionEnd]
    
    End --> FS[(logs/system_id.log)]
    Event1 -.-> FS
    Event2 -.-> FS

Guidance for AI Agents

Debugging Background Tasks: If a scheduled task or a "Welcome Home" routine fails, do not guess. Immediately read the corresponding .log file in the appropriate logs/ subdirectory.
Structured Fields: When adding new logging statements via the SystemLogger interface, use the Field{"key", value} pattern to enrich the metadata object rather than cramming everything into the message string.