feat: v0.17.0 — multi-session dashboard with trend charts (#33)

Siddhant-K-code · Ona · ona-agent · web-flow · commit d8b0ba791f39 · 2026-04-11T23:06:23.000+05:30
* feat: multi-session dashboard with trend charts Adds dashboard.py with build_dashboard() that aggregates cost, duration, tool calls, errors, and success rate across sessions. Outputs a terminal table with a sparkline cost trend, or a self-contained HTML page with stat cards and an SVG trend line. CLI: agent-strace dashboard [--limit N] [--agent filter] [--output file.html] Closes #23 Co-authored-by: Ona <no-reply@ona.com> * fix: avoid ZeroDivisionError in HTML sparkline when all costs are zero max_c used 'if costs else 1.0' which still divides by zero when all costs are 0.0. Use 'or 1.0' instead. Also remove unused EventType import. Co-authored-by: Ona <no-reply@ona.com> --------- Co-authored-by: Ona <ona@gitpod.io> Co-authored-by: Ona <no-reply@ona.com>
diff --git a/src/agent_trace/dashboard.py b/src/agent_trace/dashboard.py
@@ -0,0 +1,286 @@
+"""Multi-session dashboard: aggregate view across sessions with trend data.
+
+Produces a terminal table and an optional self-contained HTML dashboard
+showing cost, duration, tool calls, errors, and trend lines across all
+(or a filtered set of) sessions.
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import TextIO
+
+from .models import SessionMeta
+from .store import TraceStore
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SessionSummary:
+    session_id: str
+    started_at: float
+    duration_s: float
+    tool_calls: int
+    llm_requests: int
+    errors: int
+    total_tokens: int
+    estimated_cost: float
+    agent_name: str
+    succeeded: bool   # True if no errors recorded
+
+
+@dataclass
+class DashboardReport:
+    summaries: list[SessionSummary]
+    total_cost: float
+    total_tokens: int
+    total_tool_calls: int
+    total_errors: int
+    avg_duration_s: float
+    success_rate: float   # 0.0–1.0
+
+
+# ---------------------------------------------------------------------------
+# Aggregation
+# ---------------------------------------------------------------------------
+
+def build_dashboard(
+    store: TraceStore,
+    limit: int = 50,
+    agent_filter: str = "",
+) -> DashboardReport:
+    """Build a DashboardReport from the most recent *limit* sessions."""
+    all_meta = store.list_sessions()
+
+    if agent_filter:
+        all_meta = [m for m in all_meta if agent_filter.lower() in m.agent_name.lower()]
+
+    sessions = all_meta[:limit]
+
+    summaries: list[SessionSummary] = []
+    for meta in sessions:
+        duration_s = meta.total_duration_ms / 1000 if meta.total_duration_ms else 0.0
+        # Estimate cost cheaply from token count stored in meta
+        cost = meta.total_tokens / 1_000_000 * 3.0  # rough sonnet input price
+
+        summaries.append(SessionSummary(
+            session_id=meta.session_id,
+            started_at=meta.started_at,
+            duration_s=duration_s,
+            tool_calls=meta.tool_calls,
+            llm_requests=meta.llm_requests,
+            errors=meta.errors,
+            total_tokens=meta.total_tokens,
+            estimated_cost=cost,
+            agent_name=meta.agent_name or "unknown",
+            succeeded=meta.errors == 0,
+        ))
+
+    total_cost = sum(s.estimated_cost for s in summaries)
+    total_tokens = sum(s.total_tokens for s in summaries)
+    total_tools = sum(s.tool_calls for s in summaries)
+    total_errors = sum(s.errors for s in summaries)
+    avg_dur = (
+        sum(s.duration_s for s in summaries) / len(summaries)
+        if summaries else 0.0
+    )
+    success_rate = (
+        sum(1 for s in summaries if s.succeeded) / len(summaries)
+        if summaries else 0.0
+    )
+
+    return DashboardReport(
+        summaries=summaries,
+        total_cost=total_cost,
+        total_tokens=total_tokens,
+        total_tool_calls=total_tools,
+        total_errors=total_errors,
+        avg_duration_s=avg_dur,
+        success_rate=success_rate,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Terminal formatting
+# ---------------------------------------------------------------------------
+
+def _fmt_dur(s: float) -> str:
+    if s < 60:
+        return f"{s:.0f}s"
+    return f"{int(s)//60}m{int(s)%60:02d}s"
+
+
+def _fmt_ts(ts: float) -> str:
+    try:
+        dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+        return dt.strftime("%m-%d %H:%M")
+    except Exception:
+        return "?"
+
+
+def format_dashboard(report: DashboardReport, out: TextIO = sys.stdout) -> None:
+    w = out.write
+    n = len(report.summaries)
+
+    w(f"\nDashboard — {n} session{'s' if n != 1 else ''}\n\n")
+
+    # Summary row
+    w(f"  Total cost:    ~${report.total_cost:.4f}\n")
+    w(f"  Total tokens:  {report.total_tokens:,}\n")
+    w(f"  Tool calls:    {report.total_tool_calls:,}\n")
+    w(f"  Errors:        {report.total_errors}\n")
+    w(f"  Avg duration:  {_fmt_dur(report.avg_duration_s)}\n")
+    w(f"  Success rate:  {report.success_rate*100:.0f}%\n\n")
+
+    if not report.summaries:
+        return
+
+    # Table header
+    w(f"  {'ID':<14}  {'Started':<12}  {'Dur':>7}  {'Tools':>5}  "
+      f"{'LLM':>4}  {'Err':>3}  {'Tokens':>8}  {'Cost':>8}  Status\n")
+    w("  " + "-" * 80 + "\n")
+
+    for s in report.summaries:
+        status = "✓" if s.succeeded else "✗"
+        w(
+            f"  {s.session_id[:12]:<14}  {_fmt_ts(s.started_at):<12}  "
+            f"{_fmt_dur(s.duration_s):>7}  {s.tool_calls:>5}  "
+            f"{s.llm_requests:>4}  {s.errors:>3}  "
+            f"{s.total_tokens:>8,}  ${s.estimated_cost:>7.4f}  {status}\n"
+        )
+
+    w("\n")
+
+    # Trend: last 10 sessions cost
+    if len(report.summaries) >= 3:
+        recent = list(reversed(report.summaries[:10]))
+        costs = [s.estimated_cost for s in recent]
+        max_cost = max(costs) or 1.0
+        w("  Cost trend (oldest → newest):\n  ")
+        bars = "▁▂▃▄▅▆▇█"
+        for c in costs:
+            idx = min(int(c / max_cost * (len(bars) - 1)), len(bars) - 1)
+            w(bars[idx])
+        w("\n\n")
+
+
+# ---------------------------------------------------------------------------
+# HTML dashboard
+# ---------------------------------------------------------------------------
+
+def render_html_dashboard(report: DashboardReport) -> str:
+    """Produce a self-contained HTML dashboard page."""
+    rows_html = ""
+    for s in report.summaries:
+        status_cls = "ok" if s.succeeded else "err"
+        status_sym = "✓" if s.succeeded else "✗"
+        rows_html += (
+            f"<tr class='{status_cls}'>"
+            f"<td>{html.escape(s.session_id[:12])}</td>"
+            f"<td>{html.escape(_fmt_ts(s.started_at))}</td>"
+            f"<td>{html.escape(_fmt_dur(s.duration_s))}</td>"
+            f"<td>{s.tool_calls}</td>"
+            f"<td>{s.llm_requests}</td>"
+            f"<td>{s.errors}</td>"
+            f"<td>{s.total_tokens:,}</td>"
+            f"<td>${s.estimated_cost:.4f}</td>"
+            f"<td>{status_sym}</td>"
+            f"</tr>\n"
+        )
+
+    # Sparkline data for Chart.js-free inline SVG
+    costs = [s.estimated_cost for s in reversed(report.summaries[:20])]
+    max_c = max(costs) or 1.0
+    spark_points = ""
+    if costs:
+        w = 200
+        h = 40
+        pts = []
+        for i, c in enumerate(costs):
+            x = int(i / max(len(costs) - 1, 1) * w)
+            y = int(h - (c / max_c) * h)
+            pts.append(f"{x},{y}")
+        spark_points = " ".join(pts)
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>agent-strace dashboard</title>
+<style>
+body{{font-family:monospace;background:#0d1117;color:#c9d1d9;margin:0;padding:20px}}
+h1{{color:#58a6ff;font-size:1.2em;margin-bottom:16px}}
+.stats{{display:flex;gap:24px;margin-bottom:20px;flex-wrap:wrap}}
+.stat{{background:#161b22;border:1px solid #30363d;border-radius:6px;padding:12px 20px}}
+.stat .label{{font-size:.75em;color:#8b949e}}
+.stat .value{{font-size:1.4em;color:#e6edf3;margin-top:4px}}
+table{{width:100%;border-collapse:collapse;font-size:.85em}}
+th{{background:#161b22;color:#8b949e;padding:6px 10px;text-align:left;border-bottom:1px solid #30363d}}
+td{{padding:5px 10px;border-bottom:1px solid #21262d}}
+tr.ok td:last-child{{color:#3fb950}}
+tr.err td:last-child{{color:#f85149}}
+tr:hover{{background:#161b22}}
+.spark{{margin-bottom:20px}}
+polyline{{fill:none;stroke:#58a6ff;stroke-width:1.5}}
+</style>
+</head>
+<body>
+<h1>agent-strace dashboard</h1>
+<div class="stats">
+  <div class="stat"><div class="label">Sessions</div><div class="value">{len(report.summaries)}</div></div>
+  <div class="stat"><div class="label">Est. cost</div><div class="value">${report.total_cost:.4f}</div></div>
+  <div class="stat"><div class="label">Total tokens</div><div class="value">{report.total_tokens:,}</div></div>
+  <div class="stat"><div class="label">Tool calls</div><div class="value">{report.total_tool_calls:,}</div></div>
+  <div class="stat"><div class="label">Errors</div><div class="value">{report.total_errors}</div></div>
+  <div class="stat"><div class="label">Success rate</div><div class="value">{report.success_rate*100:.0f}%</div></div>
+  <div class="stat"><div class="label">Avg duration</div><div class="value">{_fmt_dur(report.avg_duration_s)}</div></div>
+</div>
+<div class="spark">
+  <svg width="200" height="40" viewBox="0 0 200 40">
+    <polyline points="{spark_points}"/>
+  </svg>
+  <span style="font-size:.75em;color:#8b949e"> cost trend</span>
+</div>
+<table>
+<thead><tr>
+  <th>Session</th><th>Started</th><th>Duration</th>
+  <th>Tools</th><th>LLM</th><th>Errors</th>
+  <th>Tokens</th><th>Cost</th><th>Status</th>
+</tr></thead>
+<tbody>
+{rows_html}
+</tbody>
+</table>
+</body>
+</html>"""
+
+
+# ---------------------------------------------------------------------------
+# CLI handler
+# ---------------------------------------------------------------------------
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    store = TraceStore(args.trace_dir)
+    limit = getattr(args, "limit", 50) or 50
+    agent_filter = getattr(args, "agent", "") or ""
+
+    report = build_dashboard(store, limit=limit, agent_filter=agent_filter)
+
+    output_path = getattr(args, "output", None)
+    if output_path:
+        from pathlib import Path
+        html_content = render_html_dashboard(report)
+        Path(output_path).write_text(html_content)
+        sys.stdout.write(f"Dashboard written to {output_path}\n")
+        return 0
+
+    format_dashboard(report)
+    return 0
diff --git a/tests/test_dashboard.py b/tests/test_dashboard.py
@@ -0,0 +1,112 @@
+"""Tests for multi-session dashboard (issue #23)."""
+
+import io
+import os
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from agent_trace.dashboard import (
+    DashboardReport,
+    SessionSummary,
+    build_dashboard,
+    format_dashboard,
+    render_html_dashboard,
+)
+from agent_trace.models import SessionMeta
+from agent_trace.store import TraceStore
+
+
+def _make_store_with_sessions(n: int) -> TraceStore:
+    tmpdir = tempfile.mkdtemp()
+    store = TraceStore(tmpdir)
+    for i in range(n):
+        meta = SessionMeta(
+            agent_name="test-agent",
+            tool_calls=i * 3,
+            llm_requests=i + 1,
+            errors=1 if i % 3 == 0 else 0,
+            total_tokens=i * 1000,
+            total_duration_ms=i * 5000,
+        )
+        store.create_session(meta)
+    return store
+
+
+class TestBuildDashboard(unittest.TestCase):
+    def test_empty_store(self):
+        tmpdir = tempfile.mkdtemp()
+        store = TraceStore(tmpdir)
+        report = build_dashboard(store)
+        self.assertEqual(len(report.summaries), 0)
+        self.assertEqual(report.total_cost, 0.0)
+
+    def test_builds_from_sessions(self):
+        store = _make_store_with_sessions(5)
+        report = build_dashboard(store)
+        self.assertEqual(len(report.summaries), 5)
+        self.assertGreaterEqual(report.total_tool_calls, 0)
+
+    def test_limit_respected(self):
+        store = _make_store_with_sessions(10)
+        report = build_dashboard(store, limit=3)
+        self.assertLessEqual(len(report.summaries), 3)
+
+    def test_agent_filter(self):
+        store = _make_store_with_sessions(5)
+        report = build_dashboard(store, agent_filter="test-agent")
+        self.assertEqual(len(report.summaries), 5)
+
+    def test_agent_filter_no_match(self):
+        store = _make_store_with_sessions(5)
+        report = build_dashboard(store, agent_filter="nonexistent")
+        self.assertEqual(len(report.summaries), 0)
+
+    def test_success_rate(self):
+        store = _make_store_with_sessions(3)
+        report = build_dashboard(store)
+        self.assertGreaterEqual(report.success_rate, 0.0)
+        self.assertLessEqual(report.success_rate, 1.0)
+
+
+class TestFormatDashboard(unittest.TestCase):
+    def test_format_no_crash(self):
+        store = _make_store_with_sessions(3)
+        report = build_dashboard(store)
+        buf = io.StringIO()
+        format_dashboard(report, out=buf)
+        output = buf.getvalue()
+        self.assertIn("Dashboard", output)
+        self.assertIn("sessions", output)
+
+    def test_format_empty(self):
+        report = DashboardReport(
+            summaries=[], total_cost=0, total_tokens=0,
+            total_tool_calls=0, total_errors=0,
+            avg_duration_s=0, success_rate=0,
+        )
+        buf = io.StringIO()
+        format_dashboard(report, out=buf)
+        self.assertIn("0 session", buf.getvalue())
+
+
+class TestRenderHtmlDashboard(unittest.TestCase):
+    def test_renders_html(self):
+        store = _make_store_with_sessions(3)
+        report = build_dashboard(store)
+        html = render_html_dashboard(report)
+        self.assertIn("<!DOCTYPE html>", html)
+        self.assertIn("dashboard", html)
+        self.assertIn("Sessions", html)
+
+    def test_html_contains_session_rows(self):
+        store = _make_store_with_sessions(2)
+        report = build_dashboard(store)
+        html = render_html_dashboard(report)
+        self.assertIn("<tr", html)
+
+
+if __name__ == "__main__":
+    unittest.main()
