Feature/ai observability dashboard (#79)

* feat: add AI request details feature with latency tracking

Add comprehensive request history and debugging capability to the Usage dashboard:

**Storage Layer** (usageDb.js):
- Add saveRequestDetail() for storing full request/response details
- Implement FIFO queue with 1000-record limit in request-details.json
- Auto-sanitize sensitive headers (authorization, api-key, cookie, token)
- Add getRequestDetails() with pagination and filtering support
- Add getRequestDetailById() for single record lookup

**Pipeline Integration** (chatCore.js):
- Track request start time and calculate total latency
- Record TTFT (Time To First Token) and total latency for all requests
- Capture full request details (messages, model, parameters)
- Save response content for non-streaming, mark streaming responses
- Handle error cases with detailed error information
- Async non-blocking saves to avoid impacting request performance

**API Layer** (/api/usage/request-details):
- GET endpoint with pagination (page, pageSize: 1-100)
- Filter by provider, model, connectionId, status, date range
- Returns { details: [...], pagination: {...} } format

**UI Components**:
- Drawer.js: Right slide-out panel with backdrop blur and ESC close
- Pagination.js: Full pagination with page size selector (10/20/50)
- RequestDetailsTab.js: Complete table view with filters and detail drawer

**Dashboard Integration**:
- Add "Details" tab to Usage page (4th tab after Overview/Logger/Limits)
- Table columns: Timestamp, Model, Provider, Input Tokens, Output Tokens, Latency (TTFT/Total), Action
- Provider filter dropdown (9 providers supported)
- Date range filters (start/end datetime)
- Click "Detail" button to view full request/response JSON in slide-out drawer

**Features**:
- Real-time latency monitoring (TTFT & Total)
- Complete request/response inspection for debugging
- Filterable and searchable request history
- Responsive design with mobile-friendly filters
- Data security with automatic header sanitization
- Performance: async saves don't block request pipeline

**Files Created/Modified**:
- src/lib/usageDb.js (modified)
- open-sse/handlers/chatCore.js (modified)
- src/app/api/usage/request-details/route.js (new)
- src/shared/components/Drawer.js (new)
- src/shared/components/Pagination.js (new)
- src/app/(dashboard)/dashboard/usage/components/RequestDetailsTab.js (new)
- src/app/(dashboard)/dashboard/usage/page.js (modified)

Closes: AI Observability Dashboard feature

* feat: enhance request details with full config and streaming content capture

Improve Request Details feature to capture comprehensive request parameters
and actual streaming response content:

**Request Configuration Enhancement** (chatCore.js):
- Add extractRequestConfig() helper function to capture all request parameters
- Include temperature controls: temperature, top_p, top_k
- Include token limits: max_tokens, max_completion_tokens
- Include thinking/reasoning modes: thinking, reasoning, enable_thinking
- Include OpenAI parameters: presence_penalty, frequency_penalty, seed, stop,
  tools, tool_choice, response_format, n, logprobs, top_logprobs, logit_bias,
  user, parallel_tool_calls, prediction, store, metadata
- Apply to all request types: non-streaming, streaming, and error cases

**Streaming Content Capture** (chatCore.js & stream.js):
- Add onStreamComplete callback mechanism to stream processors
- Accumulate content from all formats: OpenAI, Claude, Gemini
- Track content from delta.content, delta.reasoning_content, delta.text,
  delta.thinking, and Gemini content.parts
- Save initial record with "[Streaming in progress...]" marker
- Update record with actual content when stream completes
- Include usage tokens when available from stream

**Files Modified**:
- open-sse/handlers/chatCore.js - extractRequestConfig() + streaming capture
- open-sse/utils/stream.js - onStreamComplete callback + content accumulation

**Benefits**:
- View complete request configuration in Request Details (thinking mode, etc.)
- See actual streaming response content instead of placeholder
- Better debugging and observability for AI requests

Refs: #request-details-enhancement

* feat: separate thinking/reasoning content from response content

Improve Request Details to display thinking process separately from final response:

**Backend Changes**:
- stream.js: Capture content and thinking separately in streaming mode
  - Add accumulatedThinking variable alongside accumulatedContent
  - Route delta.content to content, delta.reasoning_content to thinking
  - Support OpenAI (reasoning_content), Claude (thinking), Gemini (part.thought)
  - Update onStreamComplete callback to return { content, thinking } object

- chatCore.js: Update response structure to include thinking field
  - Non-streaming: Extract thinking from reasoning_content field
  - Streaming: Receive { content, thinking } from stream callback
  - Error responses: Include thinking: null
  - Initial streaming save: Include thinking: null

**Frontend Changes**:
- RequestDetailsTab.js: Display thinking and content in separate sections
  - Add amber/yellow themed "Thinking Process" section with psychology icon
  - Show "Final Response" label when thinking is present
  - Use distinct visual styling for thinking (amber bg) vs content (gray bg)
  - Only show thinking section when thinking content exists

**Benefits**:
- Users can clearly see model's reasoning process vs final answer
- Better debugging for models with thinking capabilities (Claude, o1, etc.)
- Visual distinction makes it easy to identify thinking vs response

Refs: #thinking-content-separation

* fix: map Claude thinking to reasoning_content field

Fix Claude thinking content to be properly captured as reasoning_content
instead of regular content, enabling separate display in Request Details:

**Changes**:
- claude-to-openai.js: Use reasoning_content field for thinking blocks
  - thinking start: send { reasoning_content: "" } instead of { content: "```\n```" }
  - thinking delta: map to reasoning_content instead of content
  - thinking stop: send { reasoning_content: "" } instead of { content: "```\n```" }

**Why This Matters**:
- Previously Claude thinking was sent as `content` field, mixed with actual response
- Now thinking uses `reasoning_content` field, matching OpenAI's o1 format
- stream.js can now properly route thinking to accumulatedThinking variable
- Request Details UI will show Claude thinking in separate "Thinking Process" section

**Supported Thinking Formats**:
- OpenAI: delta.reasoning_content → thinking
- Claude: delta.thinking → reasoning_content (now fixed)
- Gemini: part.thought === true → thinking

Refs: #claude-thinking-fix

* feat(observability): capture and display full 4-layer request chain

Capture complete request/response chain in AI Request Details:
- Add providerRequest field (translated request sent to provider)
- Add providerResponse field (raw provider response, streaming indicator)
- Update chatCore.js at all 5 saveRequestDetail() call sites
- Reorganize UI into 4 collapsible sections with Material icons
- Preserve backward compatibility for old records
- Add distinct styling for streaming indicator

* fix(observability): resolve React duplicate key warning in request details table

- Use composite key (detail.id + index) to ensure unique keys
- Prevents React warnings when database contains duplicate IDs from old ID generation

* fix(observability): display actual content in streaming request details

Change providerResponse field for streaming requests from placeholder
"[Streaming - raw response not captured]" to actual final content.

This improves debugging experience by showing the real AI response
in the "Provider Response (Raw)" section instead of a confusing
placeholder message.

Files changed:
- open-sse/handlers/chatCore.js: Save contentObj.content to providerResponse
- src/app/.../RequestDetailsTab.js: Remove special handling for placeholder

* refactor(observability): migrate request details to SQLite for improved concurrency

- Replace LowDB JSON storage with better-sqlite3
- Enable WAL mode for true concurrent read/write support
- Add 5 indexes to accelerate queries (timestamp, provider, model, connection_id, status)
- Perform pagination at the database level to reduce memory footprint
- Maintain 1000 record limit with automatic cleanup of old data
- Ensure API compatibility via re-exports, requiring no caller changes

Performance improvements:
- Concurrent Writes: Lock-free WAL mode prevents data contention
- Query Efficiency: Index-based searches replace full dataset loading
- Data Integrity: Atomic operations prevent file corruption

* fix(observability): resolve pagination statistics display issues

- Fix issue where totalItems=0 showed 'Showing 1 to 0 of 0 results'
- Hide pagination controls when totalItems=0 or totalPages<=1
- Standardize API response fields: pagination.total -> pagination.totalItems

Before: Incorrect stats shown for empty data, and pager visible even for single-page results
After: Stats hidden for empty data, pager hidden when navigation is unnecessary

* feat(observability): display friendly provider names in request details

- Add /api/usage/providers endpoint to dynamically fetch provider list with names
- Replace hardcoded provider options with dynamic loading from database
- Display friendly provider names instead of IDs in both table and detail drawer
- Support custom provider nodes (e.g., OpenAI-compatible) with user-defined names
- Add provider name caching to optimize performance

* fix(observability): use INSERT OR REPLACE for request details to handle streaming updates

* fix(observability): resolve zero-token display issue by ensuring streaming usage capture and fixing key mismatch

* fix(observability): separate TTFT and total latency calculation for streaming requests

* feat(observability): implement SQLite write queue and JSON size limits

- Added in-memory buffer and batch writing for SQLite to prevent lock contention
- Implemented  with configurable 1MB limit to prevent DB bloat
- Added dashboard UI for observability performance and data management settings
- Integrated graceful shutdown handlers to prevent data loss

* fix(observability): resolve ReferenceError by declaring dbInstance
This commit is contained in:
Blade
2026-02-09 10:30:42 +07:00
committed by GitHub
parent 388389c972
commit 85b7a0b136
14 changed files with 1647 additions and 40 deletions
@@ -0,0 +1,425 @@
"use client";
import { useState, useEffect, useCallback } from "react";
import Card from "@/shared/components/Card";
import Button from "@/shared/components/Button";
import Drawer from "@/shared/components/Drawer";
import Pagination from "@/shared/components/Pagination";
import { cn } from "@/shared/utils/cn";
import { AI_PROVIDERS, getProviderByAlias } from "@/shared/constants/providers";
let providerNameCache = null;
let providerNodesCache = null;
async function fetchProviderNames() {
if (providerNameCache && providerNodesCache) {
return { providerNameCache, providerNodesCache };
}
const nodesRes = await fetch("/api/provider-nodes");
const nodesData = await nodesRes.json();
const nodes = nodesData.nodes || [];
providerNodesCache = {};
for (const node of nodes) {
providerNodesCache[node.id] = node.name;
}
providerNameCache = {
...AI_PROVIDERS,
...providerNodesCache
};
return { providerNameCache, providerNodesCache };
}
function getProviderName(providerId, cache) {
if (!providerId) return providerId;
if (!cache) return providerId;
const cached = cache[providerId];
if (typeof cached === 'string') {
return cached;
}
if (cached?.name) {
return cached.name;
}
const providerConfig = getProviderByAlias(providerId) || AI_PROVIDERS[providerId];
return providerConfig?.name || providerId;
}
function CollapsibleSection({ title, children, defaultOpen = false, icon = null }) {
const [isOpen, setIsOpen] = useState(defaultOpen);
return (
<div className="border border-black/5 dark:border-white/5 rounded-lg overflow-hidden">
<button
type="button"
onClick={() => setIsOpen(!isOpen)}
className="w-full flex items-center justify-between p-3 bg-black/[0.02] dark:bg-white/[0.02] hover:bg-black/[0.04] dark:hover:bg-white/[0.04] transition-colors"
>
<div className="flex items-center gap-2">
{icon && <span className="material-symbols-outlined text-[18px] text-text-muted">{icon}</span>}
<span className="font-semibold text-sm text-text-main">{title}</span>
</div>
<span className={cn(
"material-symbols-outlined text-[20px] text-text-muted transition-transform duration-200",
isOpen ? "rotate-90" : ""
)}>
chevron_right
</span>
</button>
{isOpen && (
<div className="p-4 border-t border-black/5 dark:border-white/5">
{children}
</div>
)}
</div>
);
}
export default function RequestDetailsTab() {
const [details, setDetails] = useState([]);
const [pagination, setPagination] = useState({
page: 1,
pageSize: 20,
totalItems: 0,
totalPages: 0
});
const [loading, setLoading] = useState(false);
const [selectedDetail, setSelectedDetail] = useState(null);
const [isDrawerOpen, setIsDrawerOpen] = useState(false);
const [providers, setProviders] = useState([]);
const [providerNameCache, setProviderNameCache] = useState(null);
const [filters, setFilters] = useState({
provider: "",
startDate: "",
endDate: ""
});
const fetchProviders = useCallback(async () => {
try {
const res = await fetch("/api/usage/providers");
const data = await res.json();
setProviders(data.providers || []);
const cache = await fetchProviderNames();
setProviderNameCache(cache.providerNameCache);
} catch (error) {
console.error("Failed to fetch providers:", error);
}
}, []);
const fetchDetails = useCallback(async () => {
setLoading(true);
try {
const params = new URLSearchParams({
page: pagination.page.toString(),
pageSize: pagination.pageSize.toString()
});
if (filters.provider) params.append("provider", filters.provider);
if (filters.startDate) params.append("startDate", filters.startDate);
if (filters.endDate) params.append("endDate", filters.endDate);
const res = await fetch(`/api/usage/request-details?${params}`);
const data = await res.json();
setDetails(data.details || []);
setPagination(prev => ({ ...prev, ...data.pagination }));
} catch (error) {
console.error("Failed to fetch request details:", error);
} finally {
setLoading(false);
}
}, [pagination.page, pagination.pageSize, filters]);
useEffect(() => {
fetchProviders();
}, [fetchProviders]);
useEffect(() => {
fetchDetails();
}, [fetchDetails]);
const handleViewDetail = (detail) => {
setSelectedDetail(detail);
setIsDrawerOpen(true);
};
const handlePageChange = (newPage) => {
setPagination(prev => ({ ...prev, page: newPage }));
};
const handlePageSizeChange = (newPageSize) => {
setPagination(prev => ({ ...prev, pageSize: newPageSize, page: 1 }));
};
const handleClearFilters = () => {
setFilters({ provider: "", startDate: "", endDate: "" });
};
return (
<div className="flex flex-col gap-6">
<Card padding="md">
<div className="flex flex-wrap gap-4">
<div className="flex flex-col gap-2">
<label htmlFor="provider-filter" className="text-sm font-medium text-text-main">Provider</label>
<select
id="provider-filter"
value={filters.provider}
onChange={(e) => setFilters({ ...filters, provider: e.target.value })}
className={cn(
"h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
"text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20",
"cursor-pointer min-w-[150px]"
)}
>
<option value="">All Providers</option>
{providers.map((provider) => (
<option key={provider.id} value={provider.id}>
{provider.name}
</option>
))}
</select>
</div>
<div className="flex flex-col gap-2">
<label htmlFor="start-date-filter" className="text-sm font-medium text-text-main">Start Date</label>
<input
id="start-date-filter"
type="datetime-local"
value={filters.startDate}
onChange={(e) => setFilters({ ...filters, startDate: e.target.value })}
className={cn(
"h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
"text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20"
)}
/>
</div>
<div className="flex flex-col gap-2">
<label htmlFor="end-date-filter" className="text-sm font-medium text-text-main">End Date</label>
<input
id="end-date-filter"
type="datetime-local"
value={filters.endDate}
onChange={(e) => setFilters({ ...filters, endDate: e.target.value })}
className={cn(
"h-9 px-3 rounded-lg border border-black/10 dark:border-white/10 bg-surface",
"text-sm text-text-main focus:outline-none focus:ring-2 focus:ring-primary/20"
)}
/>
</div>
<div className="flex flex-col gap-2">
<span className="text-sm font-medium text-text-main opacity-0" aria-hidden="true">Clear</span>
<Button
variant="ghost"
onClick={handleClearFilters}
disabled={!filters.provider && !filters.startDate && !filters.endDate}
>
Clear Filters
</Button>
</div>
</div>
</Card>
<Card padding="none">
<div className="overflow-x-auto">
<table className="w-full">
<thead>
<tr className="border-b border-black/5 dark:border-white/5">
<th className="text-left p-4 text-sm font-semibold text-text-main">Timestamp</th>
<th className="text-left p-4 text-sm font-semibold text-text-main">Model</th>
<th className="text-left p-4 text-sm font-semibold text-text-main">Provider</th>
<th className="text-right p-4 text-sm font-semibold text-text-main">Input Tokens</th>
<th className="text-right p-4 text-sm font-semibold text-text-main">Output Tokens</th>
<th className="text-left p-4 text-sm font-semibold text-text-main">Latency</th>
<th className="text-center p-4 text-sm font-semibold text-text-main">Action</th>
</tr>
</thead>
<tbody>
{loading ? (
<tr>
<td colSpan="7" className="p-8 text-center text-text-muted">
<div className="flex items-center justify-center gap-2">
<span className="material-symbols-outlined animate-spin text-[20px]">progress_activity</span>
Loading...
</div>
</td>
</tr>
) : details.length === 0 ? (
<tr>
<td colSpan="7" className="p-8 text-center text-text-muted">
No request details found
</td>
</tr>
) : (
details.map((detail, index) => (
<tr
key={`${detail.id}-${index}`}
className="border-b border-black/5 dark:border-white/5 last:border-b-0 hover:bg-black/[0.02] dark:hover:bg-white/[0.02] transition-colors"
>
<td className="p-4 text-sm text-text-main">
{new Date(detail.timestamp).toLocaleString()}
</td>
<td className="p-4 text-sm text-text-main font-mono">
{detail.model}
</td>
<td className="p-4 text-sm text-text-main">
<span className="font-medium">
{getProviderName(detail.provider, providerNameCache)}
</span>
</td>
<td className="p-4 text-sm text-text-main text-right font-mono">
{detail.tokens?.prompt_tokens?.toLocaleString() || 0}
</td>
<td className="p-4 text-sm text-text-main text-right font-mono">
{detail.tokens?.completion_tokens?.toLocaleString() || 0}
</td>
<td className="p-4 text-sm text-text-muted">
<div className="flex flex-col gap-0.5">
<div>TTFT: <span className="font-mono">{detail.latency?.ttft || 0}ms</span></div>
<div>Total: <span className="font-mono">{detail.latency?.total || 0}ms</span></div>
</div>
</td>
<td className="p-4 text-center">
<Button
variant="outline"
size="sm"
onClick={() => handleViewDetail(detail)}
>
Detail
</Button>
</td>
</tr>
))
)}
</tbody>
</table>
</div>
{!loading && details.length > 0 && (
<div className="border-t border-black/5 dark:border-white/5">
<Pagination
currentPage={pagination.page}
pageSize={pagination.pageSize}
totalItems={pagination.totalItems}
onPageChange={handlePageChange}
onPageSizeChange={handlePageSizeChange}
/>
</div>
)}
</Card>
<Drawer
isOpen={isDrawerOpen}
onClose={() => setIsDrawerOpen(false)}
title="Request Details"
width="lg"
>
{selectedDetail && (
<div className="space-y-6">
<div className="grid grid-cols-2 gap-4 text-sm">
<div>
<span className="text-text-muted">ID:</span>{" "}
<span className="text-text-main font-mono">{selectedDetail.id}</span>
</div>
<div>
<span className="text-text-muted">Timestamp:</span>{" "}
<span className="text-text-main">{new Date(selectedDetail.timestamp).toLocaleString()}</span>
</div>
<div>
<span className="text-text-muted">Provider:</span>{" "}
<span className="text-text-main font-medium">{getProviderName(selectedDetail.provider, providerNameCache)}</span>
</div>
<div>
<span className="text-text-muted">Model:</span>{" "}
<span className="text-text-main font-mono">{selectedDetail.model}</span>
</div>
<div>
<span className="text-text-muted">Status:</span>{" "}
<span className={cn(
"font-medium",
selectedDetail.status === "success" ? "text-green-600" : "text-red-600"
)}>
{selectedDetail.status}
</span>
</div>
<div>
<span className="text-text-muted">Latency:</span>{" "}
<span className="text-text-main font-mono">
TTFT {selectedDetail.latency?.ttft || 0}ms / Total {selectedDetail.latency?.total || 0}ms
</span>
</div>
<div>
<span className="text-text-muted">Input Tokens:</span>{" "}
<span className="text-text-main font-mono">
{selectedDetail.tokens?.prompt_tokens?.toLocaleString() || 0}
</span>
</div>
<div>
<span className="text-text-muted">Output Tokens:</span>{" "}
<span className="text-text-main font-mono">
{selectedDetail.tokens?.completion_tokens?.toLocaleString() || 0}
</span>
</div>
</div>
<div className="space-y-4">
<CollapsibleSection title="1. Client Request (Input)" defaultOpen={true} icon="input">
<pre className="bg-black/5 dark:bg-white/5 p-4 rounded-lg overflow-auto max-h-[300px] text-xs font-mono text-text-main border border-black/5 dark:border-white/5">
{JSON.stringify(selectedDetail.request, null, 2)}
</pre>
</CollapsibleSection>
{selectedDetail.providerRequest && (
<CollapsibleSection title="2. Provider Request (Translated)" icon="translate">
<pre className="bg-black/5 dark:bg-white/5 p-4 rounded-lg overflow-auto max-h-[300px] text-xs font-mono text-text-main border border-black/5 dark:border-white/5">
{JSON.stringify(selectedDetail.providerRequest, null, 2)}
</pre>
</CollapsibleSection>
)}
{selectedDetail.providerResponse && (
<CollapsibleSection title="3. Provider Response (Raw)" icon="data_object">
<pre className="bg-black/5 dark:bg-white/5 p-4 rounded-lg overflow-auto max-h-[300px] text-xs font-mono text-text-main border border-black/5 dark:border-white/5">
{typeof selectedDetail.providerResponse === 'object'
? JSON.stringify(selectedDetail.providerResponse, null, 2)
: selectedDetail.providerResponse
}
</pre>
</CollapsibleSection>
)}
<CollapsibleSection title="4. Client Response (Final)" defaultOpen={true} icon="output">
{selectedDetail.response?.thinking && (
<div className="mb-4">
<h4 className="font-semibold text-text-main mb-2 flex items-center gap-2 text-xs uppercase tracking-wide opacity-70">
<span className="material-symbols-outlined text-[16px]">psychology</span>
Thinking Process
</h4>
<pre className="bg-amber-50 dark:bg-amber-950/30 p-4 rounded-lg overflow-auto max-h-[200px] text-xs font-mono text-amber-900 dark:text-amber-100 border border-amber-200 dark:border-amber-800">
{selectedDetail.response.thinking}
</pre>
</div>
)}
<h4 className="font-semibold text-text-main mb-2 text-xs uppercase tracking-wide opacity-70">
Content
</h4>
<pre className="bg-black/5 dark:bg-white/5 p-4 rounded-lg overflow-auto max-h-[300px] text-xs font-mono text-text-main border border-black/5 dark:border-white/5">
{selectedDetail.response?.content || "[No content]"}
</pre>
</CollapsibleSection>
</div>
</div>
)}
</Drawer>
</div>
);
}