Add BookStack analytics dashboard with user and page title tracking

- Add GCS-backed activity logger (BookstackActivityLogger) that records
  per-query traces and a unified activity log to GCS
- Add analytics page at /aieng-bot/analytics with metrics cards, query
  velocity chart, tool usage chart, and recent queries table
- Log authenticated user email per query (injected by Next.js proxy)
- Enrich get_page tool call traces with resolved page title from
  tool_resolve events so the trace viewer shows titles instead of IDs
- Add User column to recent queries table (visible on lg+ screens)
- Stack velocity and tool usage charts vertically at full width

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: amrit110

bookstack_agent/api/main.py

@@ -179,6 +179,7 @@ async def _log_query_bg(
     answer: str,
     duration_seconds: float,
     status: str,
+    user_email: str | None,
 ) -> None:
     """Run analytics logging in a thread pool (non-blocking)."""
     try:
@@ -190,6 +191,7 @@ async def _log_query_bg(
             answer,
             duration_seconds,
             status,
+            user_email,
         )
     except Exception as exc:  # noqa: BLE001
         api_logger.warning("Analytics logging failed (non-fatal): %s", exc)
@@ -209,6 +211,11 @@ class AskRequest(BaseModel):
         description="Opaque session token returned by a previous response. "
         "Omit to start a new conversation.",
     )
+    user_email: str | None = Field(
+        default=None,
+        description="Email of the authenticated user. Injected by the Next.js "
+        "proxy from the server-side session; ignored if sent directly.",
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -261,10 +268,28 @@ async def event_stream() -> AsyncGenerator[str, None]:
 
                 if event_type == "tool_use":
                     query_tool_calls.append(
-                        {"tool": event.get("tool", ""), "input": event.get("input", {})}
+                        {
+                            "tool": event.get("tool", ""),
+                            "input": dict(event.get("input", {})),
+                        }
                     )
                     yield f"data: {json.dumps(event)}\n\n"
 
+                elif event_type == "tool_resolve":
+                    # Enrich the matching get_page tool call with the resolved title
+                    page_id = event.get("page_id")
+                    page_title = event.get("page_title")
+                    if page_id is not None and page_title:
+                        for tc in reversed(query_tool_calls):
+                            if (
+                                tc["tool"] == "get_page"
+                                and tc["input"].get("page_id") == page_id
+                                and "page_title" not in tc["input"]
+                            ):
+                                tc["input"]["page_title"] = page_title
+                                break
+                    yield f"data: {json.dumps(event)}\n\n"
+
                 elif event_type == "answer":
                     updated_history = event.pop("history", history)
                     final_answer = event.get("text", "")
@@ -292,6 +317,7 @@ async def event_stream() -> AsyncGenerator[str, None]:
                 answer=final_answer,
                 duration_seconds=duration,
                 status=final_status,
+                user_email=request.user_email,
             )
         )
 

bookstack_agent/ui/app/analytics/components/recent-queries-table.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import { useState } from 'react'
-import { Search, ChevronDown, ChevronUp, Clock, CheckCircle, XCircle, Wrench } from 'lucide-react'
+import { Search, ChevronDown, ChevronUp, Clock, CheckCircle, XCircle, Wrench, User } from 'lucide-react'
 import type { BookstackActivity, BookstackTrace } from '@/lib/bookstack-types'
 
 const TOOL_COLORS: Record<string, string> = {
@@ -64,9 +64,16 @@ function TraceModal({
                     <div className="flex items-center gap-2 mb-1.5">
                       <span className="text-xs text-slate-500">#{tc.seq}</span>
                       <ToolBadge tool={tc.tool} />
+                      {tc.tool === 'get_page' && tc.input.page_title && (
+                        <span className="text-xs text-slate-300 font-medium truncate">
+                          {String(tc.input.page_title)}
+                        </span>
+                      )}
                     </div>
-                    <pre className="text-xs text-slate-300 whitespace-pre-wrap break-words font-mono leading-relaxed">
-                      {JSON.stringify(tc.input, null, 2)}
+                    <pre className="text-xs text-slate-500 whitespace-pre-wrap break-words font-mono leading-relaxed">
+                      {tc.tool === 'get_page'
+                        ? `page_id: ${tc.input.page_id}`
+                        : JSON.stringify(tc.input, null, 2)}
                     </pre>
                   </div>
                 ))}
@@ -179,6 +186,7 @@ export default function RecentQueriesTable({ activities }: RecentQueriesTablePro
                 <tr className="border-b border-white/10">
                   <th className="pb-3 text-left text-xs font-semibold text-slate-400 uppercase tracking-wider">Question</th>
                   <th className="pb-3 text-left text-xs font-semibold text-slate-400 uppercase tracking-wider hidden md:table-cell">Tools</th>
+                  <th className="pb-3 text-left text-xs font-semibold text-slate-400 uppercase tracking-wider hidden lg:table-cell">User</th>
                   <th className="pb-3 text-right text-xs font-semibold text-slate-400 uppercase tracking-wider hidden sm:table-cell">Duration</th>
                   <th className="pb-3 text-center text-xs font-semibold text-slate-400 uppercase tracking-wider">Status</th>
                   <th className="pb-3 text-right text-xs font-semibold text-slate-400 uppercase tracking-wider">Timestamp</th>
@@ -209,6 +217,16 @@ export default function RecentQueriesTable({ activities }: RecentQueriesTablePro
                         )}
                       </div>
                     </td>
+                    <td className="py-3 pr-4 hidden lg:table-cell">
+                      {activity.user_email ? (
+                        <span className="flex items-center gap-1 text-xs text-slate-400">
+                          <User className="w-3 h-3 shrink-0" />
+                          <span className="truncate max-w-[140px]">{activity.user_email}</span>
+                        </span>
+                      ) : (
+                        <span className="text-xs text-slate-600">—</span>
+                      )}
+                    </td>
                     <td className="py-3 pr-4 text-right hidden sm:table-cell">
                       <span className="flex items-center justify-end gap-1 text-slate-400 text-xs">
                         <Clock className="w-3 h-3" />

bookstack_agent/ui/app/analytics/components/tool-usage-chart.tsx

@@ -42,18 +42,19 @@ export default function ToolUsageChart({ metrics }: { metrics: BookstackMetrics
 
   return (
     <div className="rounded-xl border border-white/10 bg-slate-800/60 p-6">
-      <div className="mb-5">
+      <div className="mb-6">
         <h2 className="text-xl font-bold text-white">Tool Usage</h2>
         <p className="text-sm text-slate-400 mt-0.5">
           {total.toLocaleString()} total calls across all queries
         </p>
       </div>
 
-      <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+      {/* Full-width horizontal layout: bar chart left, breakdown cards right */}
+      <div className="grid grid-cols-1 md:grid-cols-2 gap-8 items-center">
         {/* Bar chart */}
-        <div className="h-56">
+        <div className="h-48">
           <ResponsiveContainer width="100%" height="100%">
-            <BarChart data={data} margin={{ top: 5, right: 10, left: 0, bottom: 5 }}>
+            <BarChart data={data} margin={{ top: 4, right: 16, left: 0, bottom: 4 }}>
               <CartesianGrid strokeDasharray="3 3" stroke="#334155" opacity={0.4} />
               <XAxis
                 dataKey="label"
@@ -75,6 +76,7 @@ export default function ToolUsageChart({ metrics }: { metrics: BookstackMetrics
                   color: '#fff',
                 }}
                 labelStyle={{ color: '#94a3b8' }}
+                cursor={{ fill: 'rgba(255,255,255,0.05)' }}
               />
               <Bar dataKey="count" name="Calls" radius={[4, 4, 0, 0]}>
                 {data.map((entry) => (
@@ -85,31 +87,33 @@ export default function ToolUsageChart({ metrics }: { metrics: BookstackMetrics
           </ResponsiveContainer>
         </div>
 
-        {/* Tool breakdown list */}
-        <div className="flex flex-col justify-center gap-3">
+        {/* Breakdown cards */}
+        <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
           {data.map((entry) => {
             const pct = total > 0 ? Math.round((entry.count / total) * 100) : 0
             return (
-              <div key={entry.tool}>
-                <div className="flex items-center justify-between mb-1">
-                  <div className="flex items-center gap-2">
-                    <span
-                      className="inline-block w-2.5 h-2.5 rounded-full"
-                      style={{ backgroundColor: entry.color }}
-                    />
-                    <span className="text-sm font-medium text-slate-200">{entry.label}</span>
-                  </div>
-                  <span className="text-sm text-slate-400">
-                    {entry.count.toLocaleString()} ({pct}%)
+              <div
+                key={entry.tool}
+                className="rounded-lg border border-white/10 bg-slate-700/40 p-4"
+              >
+                <div className="flex items-center gap-2 mb-2">
+                  <span
+                    className="inline-block w-2.5 h-2.5 rounded-full shrink-0"
+                    style={{ backgroundColor: entry.color }}
+                  />
+                  <span className="text-sm font-semibold text-slate-200 truncate">
+                    {entry.label}
                   </span>
                 </div>
-                <div className="h-1.5 rounded-full bg-slate-700 overflow-hidden">
+                <p className="text-2xl font-bold text-white">{entry.count.toLocaleString()}</p>
+                <p className="text-xs text-slate-400 mt-0.5">{pct}% of calls</p>
+                <div className="mt-2 h-1 rounded-full bg-slate-600 overflow-hidden">
                   <div
                     className="h-full rounded-full transition-all duration-500"
                     style={{ width: `${pct}%`, backgroundColor: entry.color }}
                   />
                 </div>
-                <p className="text-xs text-slate-500 mt-1">{TOOL_DESC[entry.tool]}</p>
+                <p className="text-xs text-slate-500 mt-2 leading-snug">{TOOL_DESC[entry.tool]}</p>
               </div>
             )
           })}

bookstack_agent/ui/app/analytics/page.tsx

@@ -95,15 +95,11 @@ export default async function BookstackAnalyticsPage() {
         {/* Metrics row */}
         <QueryMetrics metrics={metrics} />
 
-        {/* Velocity + Tool usage side by side on large screens */}
-        <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
-          <div className="lg:col-span-2">
-            <QueryVelocityChart data={velocityData} />
-          </div>
-          <div>
-            <ToolUsageChart metrics={metrics} />
-          </div>
-        </div>
+        {/* Velocity chart — full width */}
+        <QueryVelocityChart data={velocityData} />
+
+        {/* Tool usage — full width below velocity */}
+        <ToolUsageChart metrics={metrics} />
 
         {/* Recent queries */}
         <RecentQueriesTable activities={recentActivities} />

bookstack_agent/ui/app/api/ask/route.ts

@@ -5,11 +5,19 @@
  * Using a server-side proxy keeps BOOKSTACK_API_URL out of the browser and
  * avoids CORS issues between the UI and the Python backend.
  */
+import { getCurrentUser } from '@/lib/session'
+
 export const dynamic = 'force-dynamic'
 
 export async function POST(req: Request): Promise<Response> {
   const body = await req.json()
 
+  // Inject the authenticated user's email so the backend can log it.
+  const user = await getCurrentUser()
+  if (user?.email) {
+    body.user_email = user.email
+  }
+
   const backendUrl = process.env.BOOKSTACK_API_URL ?? 'http://localhost:8000'
 
   let upstream: Response

bookstack_agent/ui/lib/bookstack-types.ts

@@ -8,6 +8,8 @@ export interface BookstackActivity {
   timestamp: string
   /** Question text, truncated to 300 chars in the log. */
   question: string
+  /** Email of the authenticated user who asked the question, if available. */
+  user_email?: string | null
   /** Unique tool names used during this query (e.g. ["search_bookstack", "get_page"]). */
   tools_used: string[]
   /** Total number of individual tool invocations. */

src/aieng_bot/bookstack/activity_logger.py

@@ -166,6 +166,7 @@ def log_query(
         answer: str,
         duration_seconds: float,
         status: str,
+        user_email: str | None = None,
     ) -> bool:
         """Record a completed BookStack QA query to GCS.
 
@@ -193,6 +194,8 @@ def log_query(
             Wall-clock time from question receipt to answer emission.
         status : str
             ``"success"`` or ``"error"``.
+        user_email : str or None
+            Email of the authenticated user who asked the question, if available.
 
         Returns
         -------
@@ -244,6 +247,7 @@ def log_query(
             "session_id": session_id,
             "timestamp": timestamp,
             "question": question[:300],  # keep activity log compact
+            "user_email": user_email,
             "tools_used": tools_used,
             "tool_call_counts": tool_call_counts,
             "num_tool_calls": len(tool_calls),