Swarm Dashboard

Swarm Dashboard

The Swarm Dashboard is a Streamlit web application for monitoring and analyzing Nebulus Swarm activity. It provides real-time status, work history, queue visibility, and aggregate metrics.

Launch

streamlit run nebulus_swarm/dashboard/app.py

Opens at http://localhost:8501.

Configuration

Variable	Default	Description
OVERLORD_URL	http://localhost:8080	Overlord API URL
STATE_DB_PATH	/var/lib/overlord/state.db	Path to SQLite state database

Pages

Live Status

Real-time view of the swarm:

• Health indicators: Overlord reachable, Docker available, minion slot usage
• Active minions table: ID, repo, issue, status, time running, last heartbeat
• Stale heartbeat warnings: Highlights minions with no heartbeat in 2+ minutes
• Pending questions: Shows unanswered questions from minions

Auto-refreshes every 10 seconds (configurable toggle in sidebar).

Work History

Filterable log of completed work:

• Filters: Repository dropdown, status dropdown (completed/failed/timeout), result limit slider
• Summary metrics: Total records, completion rate, average duration
• History table: Status (with emoji), repo, issue #, PR #, duration, completion time, error message

Data comes from the SQLite state database for fast queries.

Queue

Pending GitHub issues waiting for assignment:

• Queue summary: Pending issue count, available minion slots, queue processing state (active/paused)
• Issues table: Priority (high/normal), repository, issue #, title

Data comes from the Overlord's cached queue scan results.

Metrics

Aggregate analytics over configurable time ranges (24h, 7d, 30d, all time):

• Success rate: Completion rate gauge, completed/failed/timeout counts, breakdown bar chart
• Duration trends: Average duration per day (bar chart), avg/median/fastest/slowest stats
• Throughput: Tasks per day line chart (completed vs failed)
• Failure analysis: Error types table sorted by frequency with last error message

Data Sources

The dashboard uses a hybrid data approach:

Data	Source	Method
Live status	Overlord API	GET /status
Active minions	Overlord API	GET /status
Queue	Overlord API	GET /queue
Pending questions	Overlord API	GET /status
Work history	SQLite	Direct DB query
Metrics	SQLite	Aggregation queries

SwarmDataClient

The SwarmDataClient class manages all data fetching:

• API responses are cached for 5 seconds to reduce polling load
• Connection errors return None (dashboard shows "unreachable" state)
• State DB queries use the OverlordState class directly

Metrics Computation

The get_metrics() method computes:

Metric	Calculation
completion_rate	completed / total
avg_duration	mean of duration_seconds
median_duration	median of duration_seconds
daily_stats	grouped by date with per-day counts
error_types	grouped by error prefix (e.g., "git_error")

Architecture

nebulus_swarm/dashboard/
├── __init__.py
├── app.py          # Entry point, sidebar, page routing
├── data.py         # SwarmDataClient (API + SQLite)
└── pages/
    ├── __init__.py
    ├── live.py     # Live Status page
    ├── history.py  # Work History page
    ├── queue.py    # Queue page
    └── metrics.py  # Metrics page

Related Pages

• Nebulus Swarm - System overview
• Swarm Overlord - API endpoints the dashboard reads
• Configuration - Dashboard environment variables