Monitoring Dashboard

Relevant source files

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

• ui/main.py
• ui/README.md
• ui/test_events.py
• bubus-ts/src/base_event.ts
• TODO_python.md
• TODO_ts.md

The Monitoring Dashboard is a minimal FastAPI-based web application designed for live observation of the bubus event bus activity. It provides administrators and developers with real-time insights into dispatched events and their corresponding handler results by reading from history tables populated by the SQLiteHistoryMirrorMiddleware.

Sources: ui/README.md:1-6, ui/main.py:27-27

Architecture and Data Flow

The dashboard operates as a consumer of historical event data stored in a SQLite database. It leverages FastAPI for the backend and a single-page HTML interface for the frontend. The system relies on the SQLiteHistoryMirrorMiddleware to mirror event lifecycles into events_log and event_results_log tables.

Sources: ui/README.md:3-6, ui/main.py:295-300

The following diagram illustrates the flow of data from an active EventBus to the Monitoring Dashboard:

Components

Component	Description
FastAPI Backend	Exposes REST and WebSocket endpoints for data retrieval and real-time updates.
SQLite DB	Persistent storage containing events_log and event_results_log.
Frontend UI	A dark-themed, single-page application built with HTML, CSS, and Vanilla JS.
WebSocket Stream	A persistent connection that pushes new event/result rows to the UI every 1.0s.

Sources: ui/main.py:27-30, ui/main.py:108-111, ui/main.py:414-432

Backend Implementation

The backend is implemented in ui/main.py and utilizes FastAPI to manage asynchronous data fetching from the database. It handles formatting timestamps from SQLite strings to ISO 8601 and serves the primary UI assets.

Sources: ui/main.py:32-41, ui/main.py:80-80

API Endpoints

The dashboard provides several endpoints for monitoring and metadata inspection:

Endpoint	Method	Purpose
/	GET	Returns the main HTML dashboard interface.
/events	GET	Fetches the latest events with an optional limit (default 20, max 200).
/results	GET	Fetches the latest handler results with an optional limit (default 20, max 200).
/meta	GET	Returns DB path, existence status, and table readiness flags.
/ws/events	WS	WebSocket endpoint for streaming updates using since_event_id.

Sources: ui/main.py:80-82, ui/main.py:387-400, ui/main.py:414-416

Real-time Streaming Logic

The WebSocket handler utilizes db.stream_new_rows to poll for updates. It tracks the last processed event_id and result_id to ensure only new data is transmitted to the client.

Frontend and Visualization

The frontend is a reactive interface that organizes events into a hierarchical tree view. This structure reflects the parent-child relationships established by the event_parent_id field.

Sources: ui/main.py:202-212, bubus-ts/src/base_event.ts:133-133

Event Lifecycle Monitoring

The dashboard visualizes the event_status and individual EventResult statuses. Statuses are mapped to color-coded pills:

• Completed: Green (#34d399)
• Started: Yellow (#facc15)
• Pending: Blue (#60a5fa)
• Error: Red (#f87171)

Sources: ui/main.py:126-129, TODO_ts.md:20-20, TODO_python.md:16-16

Data Hierarchy

The dashboard groups results by their handler names and allows users to inspect individual execution attempts, including logs, results, and error representations.

Configuration and Testing

The dashboard resolves the database path via resolve_db_path. For development and demonstration, ui/test_events.py can be used to generate a stream of random events across multiple categories (e.g., 'alpha', 'beta', 'gamma').

Sources: ui/main.py:404-404, ui/test_events.py:53-53, ui/test_events.py:71-77

Test Generator Features

• Flaky Handlers: Configurable error rate to test dashboard error visualization.
• Nested Events: Generates follow-up events to test tree depth (max-depth default is 2).
• Concurrency: Supports multiple producer tasks (default 3) to simulate high-traffic environments.

Sources: ui/test_events.py:44-53, ui/test_events.py:113-125

Conclusion

The Monitoring Dashboard serves as the central observability tool for the bubus project. By mirroring the internal state of the event bus into a SQLite database and exposing it via a real-time web interface, it enables comprehensive debugging of complex, asynchronous event workflows, including parent-child tracking and handler performance monitoring.

Sources: ui/README.md:1-10, ui/main.py:317-323