# 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):

1. **By tool name** — "Show only Bash calls" or "hide Read calls" is the most frequent need
2. **By session** — single most important grouping; usually implicit (viewing one session at a time)
3. **By time range** — "last 30 min", "today", custom range
4. **By error status** — "show only failed calls" (non-zero exit, exception messages)
5. **By text/search** — free-text search across tool inputs/outputs
6. **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

1. **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

2. **Session list:** GtkListBox at top (or left sidebar) showing sessions with
   aggregate cost + call count + error badge

3. **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)

4. **Detail panel:** Right-side GtkStack with:
   - Full tool input (GtkTextView, monospace)
   - Full tool output (GtkTextView, monospace, scrollable)
   - Metrics row: duration, tokens, cost (if available)

5. **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)

6. **Status bar:** Bottom bar showing session totals
   (derived from sidecar state JSON)

7. **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

---

## Sources

- [Langfuse Data Model](https://langfuse.com/docs/observability/data-model)
- [Langfuse LLM Observability Overview](https://langfuse.com/docs/observability/overview)
- [LangSmith Filter Traces](https://docs.langchain.com/langsmith/filter-traces-in-application)
- [LangSmith Visibility with Tracing](https://victorleungtw.wordpress.com/2025/04/26/langsmith-visibility-while-building-with-tracing/)
- [Helicone Sessions](https://docs.helicone.ai/features/sessions)
- [Helicone Smarter Sessions Design](https://www.helicone.ai/changelog/20250506-smarter-sessions-insights)
- [Braintrust: Best LLM Tracing Tools 2026](https://www.braintrust.dev/articles/best-llm-tracing-tools-2026)
- [Braintrust: Best AI Observability Tools 2026](https://www.braintrust.dev/articles/best-ai-observability-tools-2026)
- [AgentPrism: Debug AI Fast (Evil Martians)](https://evilmartians.com/chronicles/debug-ai-fast-agent-prism-open-source-library-visualize-agent-traces)
- [Grafana Trace Integration](https://grafana.com/docs/grafana/latest/visualizations/explore/trace-integration/)
- [Grafana Span Filters](https://grafana.com/docs/grafana/latest/datasources/tempo/span-filters/)
- [Datadog Trace View](https://docs.datadoghq.com/tracing/trace_explorer/trace_view/)
- [Maxim: Agent Tracing for Debugging Multi-Agent AI Systems](https://www.getmaxim.ai/articles/agent-tracing-for-debugging-multi-agent-ai-systems/)
- [Claude Code Log Analysis with DuckDB](https://liambx.com/blog/claude-code-log-analysis-with-duckdb)
- [Inside Claude Code: The Session File Format](https://databunny.medium.com/inside-claude-code-the-session-file-format-and-how-to-inspect-it-b9998e66d56b)
- [Activity Log Pattern (alguidelines.dev)](https://alguidelines.dev/docs/navpatterns/patterns/activity-log/)
- [SigNoz: Jaeger vs Zipkin](https://signoz.io/blog/jaeger-vs-zipkin/)