History & Logging

Relevant source files

The following files were used as context for generating this wiki page:

• bubus/event_bus.py
• bubus/logging.py
• bubus/middlewares.py
• bubus-ts/src/logging.ts
• ui/main.py
• tests/test_event_history_mirroring.py

The History and Logging system in bubus provides a multi-layered approach to tracking event lifecycles, handler results, and parent-child relationships across the event bus. It encompasses in-memory history management within the EventBus, middleware for persisting logs to external storage (SQLite, JSONL), and visual tools for rendering event trees in both CLI and Web UI formats.

This system ensures that every event transition—from pending to started to completed or error—is observable. The history serves as the primary source for features like queue-jump processing, find-waiters, and debugging complex asynchronous workflows.
Sources: bubus/event_bus.py:108-111, bubus/middlewares.py:27-38, ui/README.md:5-9

In-Memory Event History

Each EventBus instance maintains an internal event_history mapping that stores BaseEvent objects keyed by their unique IDs. This history is used to track active events and their associated EventResult objects.

History Configuration and Memory Management

To prevent memory leaks, the event bus provides configuration options to bound the history size.

Option	Type	Default	Description
max_history_size	int | None	100	Maximum number of events to keep in memory. None is unlimited.
max_history_drop	bool	False	If True, oldest events are dropped when limit is reached. If False, new emits are rejected.

Sources: bubus/event_bus.py:114-122, bubus/event_bus.py:182-192

Trimming Logic

The bus implements a prioritization strategy during history cleanup:

1. Completed Events: Removed first (oldest first).
2. Started Events: Removed if more space is needed.
3. Pending Events: Removed only as a last resort.

If max_history_size is set to 0, the bus only retains in-flight events and removes them immediately upon completion.
Sources: bubus/event_bus.py:1497-1533

Lifecycle Logging via Middleware

Middleware provides hooks into the internal event lifecycle. The EventBus notifies registered middlewares of state changes for both events and handler results.

The following status transitions are monitored by middlewares.
Sources: bubus/event_bus.py:586-601, bubus/middlewares.py:38-41

Specialized Logging Middlewares

• LoggerEventBusMiddleware: Logs summary strings of completed events to stdout and optionally to a file. It uses event_log_safe_summary() to generate readable output. Sources: bubus/middlewares.py:263-286
• WALEventBusMiddleware: Implements a Write-Ahead Log by persisting completed events as JSONL lines. Sources: bubus/middlewares.py:243-260
• SQLiteHistoryMirrorMiddleware: Mirrors event and handler snapshots into a relational database. This is the primary data source for the Monitoring Dashboard. Sources: bubus/middlewares.py:289-317

SQLite Mirror Schema

The mirror middleware maintains two primary tables:

Table	Columns
events_log	event_id, event_type, event_status, eventbus_id, phase, event_json
event_results_log	event_result_id, event_id, handler_name, status, phase, result_repr, error_repr

Sources: bubus/middlewares.py:339-373

Visualizing Event Trees

Because events can emit other events, bubus provides utilities to visualize the hierarchical relationship between parents, handlers, and children.

Tree Rendering Logic

The tree is constructed by walking the parent-child chain. If an event was emitted within a specific handler, it is nested under that handler's result in the visualization.

CLI Visualization

The CLI tree (accessible via log_tree()) uses ASCII characters to show status and timing:

• ✅: Completed
• ❌: Error (with traceback/repr)
• 🏃: Started/In-progress
• ⏳: Pending
• ☠️: Exception details

Sources: bubus/logging.py:35-131, bubus-ts/src/logging.ts:74-106

Web Monitoring Dashboard

The ui.main module provides a FastAPI-based dashboard that consumes the history mirrored by SQLiteHistoryMirrorMiddleware.

Architecture

1. Backend: Queries the SQLite database for events and results.
2. WebSockets: Uses WS /ws/events to stream new rows in real-time as they are inserted into the log tables.
3. Frontend: Reconstructs the event tree client-side using a recursive rendering function.

Dashboard Endpoints

Endpoint	Method	Description
/	GET	HTML Dashboard interface
/events	GET	List latest events (supports limit)
/results	GET	List latest handler results
/ws/events	WS	Real-time update stream

Sources: ui/main.py:441-477, ui/README.md:21-25

Conclusion

The History & Logging system provides comprehensive observability into the bubus event bus. By combining in-memory tracking for runtime operations with persistent middleware for auditing and a visual UI for monitoring, it allows developers to trace complex asynchronous interactions and identify performance bottlenecks or failures within the event lifecycle.