Initial public upload from Projekte/Sidecar-Workspace (part 4)

e6b2bd6 verified about 1 month ago

16.8 kB

Prior Art: Tool-Call Log Viewers & Trace Viewers

Research date: 2026-03-04 Researcher: logs-researcher (panel-research team) Purpose: Redesigning GTK3 Logs Tab for Claude Code sessions — from zero-value to proper trace/activity viewer

1. Tools Surveyed

Langfuse (Open Source LLM Engineering Platform)

Hierarchical trace model: Trace → Observations (nested spans)
Observation types: generations, toolcalls, RAG retrieval steps
Sessions layer groups traces by user/conversation
Filter by: environment, tags, user, session, metadata key-value pairs
Batches traces locally and sends async to avoid blocking
Launched a beta timeline view (Gantt-style) after user demand
Source: https://langfuse.com/docs/observability/data-model

LangSmith (LangChain's Observability Platform)

Traces display as tree of sub-steps: agent thought process + each tool call
Filter types: metadata, input, output, tool_call names via Output Key search
AI Query feature: natural language → filter DSL (LLM-powered)
Grouping: by metadata attributes in Monitoring tab for A/B stats
Same filter UI available in trace view AND the main runs table
Source: https://docs.langchain.com/langsmith/filter-traces-in-application

Helicone (Open Source LLM Observability)

Sessions: high-level grouping with average latency, total cost, time filters
Unified filter component — persistent across pages
Cost per request shown inline (derived from provider pricing)
Session-level metrics: cost, latency, request count per session
Multi-step workflow visualization for agent traces
Source: https://docs.helicone.ai/features/sessions

Braintrust (AI Observability)

Visual timeline replay: when each op started, duration, return value
Nested spans: parent-child in multi-step agent runs (10+ tool calls)
Token granularity: prompt/cached/completion/reasoning tokens separately
Error categorization: LLM errors, tool errors, timeouts
Connects failures to root cause spans directly
Source: https://www.braintrust.dev/articles/best-llm-tracing-tools-2026

AgentPrism (Open Source React Component Library)

4 view modes: Tree, Timeline (Gantt), Details Panel, Sequence Diagram
Tree view: red highlighting for problematic patterns, collapse repetitive sequences
Timeline: Gantt-style with color-coded status (green/red/yellow) + real-time cost
Details Panel: compressed input/output + metrics in single view
Sequence Diagram: step-by-step replay for decision chains, play/pause
Progressive disclosure to keep deep structures navigable
Source: https://evilmartians.com/chronicles/debug-ai-fast-agent-prism-open-source-library-visualize-agent-traces

Grafana Tempo Trace Viewer (Standard OTel/Distributed Tracing UI)

3-panel layout: Header (name + trace ID + search) | Minimap | Span Timeline
Minimap: draggable zoom for dense traces
Span rows: service name + operation name + visual duration bar (waterfall)
Click span → detail side panel with: attributes, resource attrs, events, links
Filters: service name, span name, duration (with unit selector), tags
"Show matches only" toggle + "Show critical path only"
Source: https://grafana.com/docs/grafana/latest/visualizations/explore/trace-integration/

Datadog APM / General OTel UI Pattern

Span list as master, detail as side panel (master-detail layout)
Minimap for zooming into dense timelines
Critical path highlighting in darker color (CRISP algorithm)
Source: https://docs.datadoghq.com/tracing/trace_explorer/trace_view/

Claude Code Session JSONL (Our Data Source)

Key fields available per tool call:

timestamp: ISO-8601
sessionId, uuid, parentUuid
message.content[].type: text | tool_use | tool_result
message.content[].name: tool name (Bash, Read, Edit, Glob, Grep...)
message.content[].input: full tool arguments
message.usage: input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens
message.model: claude model used
toolUseResult: full tool output
Source: https://liambx.com/blog/claude-code-log-analysis-with-duckdb

2. UI Patterns Found

A. Hierarchical Timeline / Waterfall (Most Common for Traces)

What it is: Horizontal bar chart where each call gets a row, bars show duration, indentation shows parent-child nesting. Pros:

Immediately shows parallelism vs. sequential calls
Duration at a glance — long bars catch the eye
Nesting reveals call structure without extra clicks
Standard pattern — users who know Chrome DevTools/Jaeger already know it Cons:
Requires timing data (we have timestamps, can derive duration if needed)
Becomes dense with 50+ spans — minimap needed
Poor for text-heavy output (truncation required) When to use: Primary view when timing and structure matter most.

B. Tree List / Expandable List

What it is: Indented list with expand/collapse toggles, no time axis. Pros:

Works without timing data
Better for deep hierarchies than waterfall
Easier to read tool inputs/outputs inline
GTK3 TreeView widget directly supports this pattern Cons:
No timing information visible without extra column
Harder to spot slow calls without duration bars When to use: Best for our GTK3 context — maps naturally to GtkTreeView.

C. Flat Table / Log List (Reverse Chronological)

What it is: Scrolling list of events, newest on top (or bottom), tabular columns. Pros:

Simplest to implement
Easy to scan text
Works well with search/filter
Activity Log pattern standard (reverse-chron with entity filter) Cons:
Loses parent-child structure
Can't see call hierarchy When to use: Secondary view or for the raw sidecar log format.

D. Session Group View

What it is: Sessions as cards or collapsible groups, with aggregate metrics per session. Pros:

Quick session comparison (cost, call count, errors)
Click to drill into session detail
Good for multi-session overview Cons:
Extra navigation layer before seeing individual calls When to use: Top-level navigation before drilling into a session's calls.

E. Sequence Diagram / Replay

What it is: Step-by-step replay of call sequence with play/pause, like a debugger. Pros:

Great for understanding complex decision chains
Can show agent "reasoning" per step Cons:
Complex to implement, high effort
Overkill for a GTK3 desktop panel When to use: Skip for now — too complex, diminishing returns vs. list/tree.

3. Filtering Best Practices

Filters that actually matter (ranked by utility):

By tool name — "Show only Bash calls" or "hide Read calls" is the most frequent need
By session — single most important grouping; usually implicit (viewing one session at a time)
By time range — "last 30 min", "today", custom range
By error status — "show only failed calls" (non-zero exit, exception messages)
By text/search — free-text search across tool inputs/outputs
By cost threshold — "calls over $0.01" (less useful for individual calls, better for sessions)

Implementation patterns:

Filter bar at top with chips/tags that are toggleable — most common pattern
Persistent filters across tab switches (Helicone's design insight)
Quick toggles for common filters (errors only, tool type buttons)
"Show matches only" toggle vs. "show all with matches highlighted" — both useful
Filter by text in input/output — powerful for debugging specific tool behavior
Sidebar filter panel (LangSmith/Datadog style) works for complex multi-dimensional filtering but adds UI complexity — probably overkill for our tab

What NOT to do:

Don't require users to type raw query DSLs
Don't hide filters behind a hamburger menu (discoverability drops to zero)
Don't reset filters on every navigation

4. Grouping Strategies

By Session (Primary)

Most natural grouping for Claude Code — each session is a distinct task
Show aggregate per session: total cost, call count, error count, duration
Session ID from sessionId field in JSONL
Sidecar state gives us: files_touched, total_calls, concerns, score

By Tool Type

Group Bash calls, Read calls, Edit calls, etc.
Useful for "how many files did I read?" type analysis
Second-level grouping within a session

By Request Chain (Parent-Child)

parentUuid links messages; tool_use_id links tool calls to results
Can reconstruct the call tree within a session
Useful for seeing "which assistant turn triggered which tools"

By Error Status

Surface sessions/calls with errors separately
Failed Bash commands (non-zero exit) are the most actionable errors
Sidecar concerns field already categorizes some of this

By Time Period

Today / Yesterday / This week groupings for session list
Within a session, time is usually sequential so this matters less

5. Key Metrics

Per Tool Call

Metric	Source	Value
Tool name	`message.content[].name`	High — what happened
Duration	derived from timestamps	High — how long
Input summary	`message.content[].input` truncated	High — what args
Success/fail	exit code, error in output	High — did it work
Output size	len(toolUseResult)	Medium — how much data
Session ID	`sessionId`	Context only

Per Assistant Turn (LLM Call)

Metric	Source	Value
Input tokens	`message.usage.input_tokens`	High
Output tokens	`message.usage.output_tokens`	High
Cache hit tokens	`cache_read_input_tokens`	Medium — cost savings
Model	`message.model`	Medium
Cost (derived)	tokens × model pricing	High
Tool calls made	count of tool_use blocks	High

Per Session (Aggregates)

Metric	Source	Value
Total cost	sum of per-turn costs	High
Total calls	sidecar `total_calls` or count	High
Files touched	sidecar `files_touched`	High
Error count	count of failed calls	High
Duration	last_ts - first_ts	Medium
Score	sidecar score (0-100)	Medium
Concerns	sidecar `concerns` list	Medium

Aggregate Dashboard (All Sessions)

Cost per day (bar chart)
Most used tools (horizontal bar)
Error rate over time
Average session cost

6. View Modes: When Is Each Appropriate

Timeline / Waterfall

Best for: Debugging performance, understanding parallel calls, timing analysis
Our case: Useful for seeing "did Claude do things in sequence or parallel?"
GTK3: Custom cairo drawing required — significant effort
Verdict: Nice-to-have, defer to v2

Tree List (Expandable)

Best for: Understanding call hierarchy, reading input/output per call
Our case: Perfect fit — GtkTreeView is built for this
GTK3: GtkTreeView + GtkTreeStore, easy to implement
Verdict: PRIMARY view mode — implement first

Flat List / Log Scroll

Best for: Raw log tailing, quick scan, search results
Our case: Current sidecar log format is already flat — map directly
GTK3: GtkListBox or GtkTextView (for raw log)
Verdict: SECONDARY view — implement as "raw log" sub-tab or toggle

Session Cards / Summary View

Best for: Choosing which session to inspect
Our case: Session selector in sidebar or top dropdown
GTK3: GtkListBox with custom cells
Verdict: NAVIGATION component, not a view mode itself

7. Recommendations for Our Logs Tab

Current State

The current tab "offers zero value" — presumably just raw log text or nothing useful.

Recommended Architecture: Two-Panel Layout

+--[Filter Bar: Tool | Session | Time | Errors Only | Search]--+
|                                                               |
| LEFT: Session + Call Tree          RIGHT: Detail Panel        |
| +----------------------------------+ +---------------------+  |
| | [Session: abc123] $0.12 42calls | | Tool: Bash          |  |
| |   [+] Turn 1 (3 tools)          | | Input: git status   |  |
| |       Bash  [OK]  0.3s          | | Output: On branch.. |  |
| |       Read  [OK]  0.1s          | |                     |  |
| |       Edit  [OK]  0.2s          | | Duration: 0.3s      |  |
| |   [+] Turn 2 (1 tool)           | | Exit code: 0        |  |
| |       Bash  [ERR] 1.2s          | | Turn: 2             |  |
| +----------------------------------+ +---------------------+  |
+---------------------------------------------------------------+
| [Status bar: Session abc123 | 42 calls | $0.12 | 3 errors]   |
+---------------------------------------------------------------+

Concrete Implementation Steps

Data source priority:
- Start with sidecar log (/tmp/claude-sidecar.log) — simplest, already structured
- Add usage JSONL for richer data
- Add session JSONL for full tool I/O
Session list: GtkListBox at top (or left sidebar) showing sessions with aggregate cost + call count + error badge
Call tree: GtkTreeView with 4 columns:
- Icon (tool type color-coded)
- Tool name + truncated input
- Duration (if derivable from timestamps)
- Status (green checkmark / red X)
Detail panel: Right-side GtkStack with:
- Full tool input (GtkTextView, monospace)
- Full tool output (GtkTextView, monospace, scrollable)
- Metrics row: duration, tokens, cost (if available)
Filter bar: Top bar with:
- Tool type buttons (toggle: All | Bash | Read/Write | Search | Other)
- "Errors only" toggle
- Search field (filters tree in real-time)
- Session selector (GtkComboBox or tabs)
Status bar: Bottom bar showing session totals (derived from sidecar state JSON)
Live updates: Watch sidecar log file with GLib.io_add_watch for file changes — append to tree in real-time

What Makes It Good (Lessons from Research)

Color code tool types: Bash=orange, Read=blue, Edit=green, Search=purple, API=yellow
Error calls always visible in red even when not filtering errors
Expandable groups (by turn/assistant message) so 42 calls don't overwhelm
Detail panel on click — click any row to see full input/output
Never reset filters on refresh — persist across live updates
Show cost prominently — users care most about "$0.12 this session"
Progressive disclosure — collapsed by default, expand to see sub-calls

What to Skip (Not Worth the GTK3 Effort)

Gantt/waterfall timeline: requires custom cairo rendering, high effort, moderate value
Sequence diagram / replay: overkill for a desktop sidecar panel
AI-powered query (LangSmith's NL filtering): fun but not needed at this stage
Cross-session comparison charts: belongs in a separate analytics view