Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: restructure trace queries around performance questions (#1884)
Maximilian Roos627990552597
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.mdindex 6199bc3e5..d53196912 100644--- a/benches/CLAUDE.md+++ b/benches/CLAUDE.md@@ -102,16 +102,23 @@ Install [trace_processor](https://perfetto.dev/docs/analysis/trace-processor) focurl -LO https://get.perfetto.dev/trace_processor && chmod +x trace_processor```-Useful queries:+### Performance questions++Three questions drive `wt list` performance work:++1. **Where does time go?** Which subprocess types consume the most total time? The category with the highest `total_ms` is where optimization effort has the most impact.++2. **How parallel are we?** Total subprocess time divided by wall time gives a parallelism factor. A factor of 4.0 means 4 commands running concurrently on average. Close to 1.0 means mostly serial execution with headroom to parallelize.++3. **What's on the critical path?** The critical path passes through serial phases (setup, finalization) plus the slowest work item in the parallel phase. We don't have good queries for this yet — the trace format doesn't capture task dependencies, and rayon's work-stealing means thread IDs don't map to worktrees. The queries below are a starting point (phase boundaries from milestones, per-worktree time from args) but don't give a real critical path answer. Visualizing the trace in Perfetto is more useful here.++### Queries```bash-# Top 10 slowest commands+# 1. Where does time go? — slowest individual commandsecho "SELECT name, ts/1e6 as start_ms, dur/1e6 as dur_ms FROM slice WHERE dur > 0 ORDER BY dur DESC LIMIT 10;" | trace_processor trace.json-# Milestone events (skeleton render, worker spawn, completion)-echo "SELECT name, ts/1e6 as ms FROM slice WHERE dur = 0 ORDER BY ts;" | trace_processor trace.json--# Task type breakdown+# 1. Where does time go? — total time by command typecat > /tmp/q.sql << 'EOF'SELECTCASE WHEN name LIKE '%patch-id%' THEN 'patch_id'@@ -144,21 +151,40 @@ GROUP BY task_type ORDER BY total_ms DESC;EOFtrace_processor trace.json -q /tmp/q.sql-# Check parallel execution overlap between task types+# 2. How parallel are we? — subprocess time vs subprocess span+# parallelism ≈ 1.0 → serial; higher → concurrent execution is helping+# (span = first subprocess start to last subprocess end; excludes wt's non-subprocess overhead)cat > /tmp/q.sql << 'EOF'-WITH status_times AS (- SELECT MIN(ts) as start_us, MAX(ts + dur) as end_us- FROM slice WHERE name LIKE '%status%'-),-trees_times AS (- SELECT MIN(ts) as start_us, MAX(ts + dur) as end_us- FROM slice WHERE name LIKE '%rev-parse%{tree}%'-)SELECT- s.start_us/1e6 as status_start_ms, s.end_us/1e6 as status_end_ms,- t.start_us/1e6 as trees_start_ms, t.end_us/1e6 as trees_end_ms,- CASE WHEN s.end_us > t.start_us AND t.end_us > s.start_us THEN 'OVERLAP' ELSE 'SEQUENTIAL' END as parallel-FROM status_times s, trees_times t;+ ROUND(SUM(dur)/1e6, 1) as total_subprocess_ms,+ ROUND((MAX(ts + dur) - MIN(ts))/1e6, 1) as span_ms,+ ROUND(CAST(SUM(dur) AS FLOAT) / (MAX(ts + dur) - MIN(ts)), 1) as parallelism+FROM slice WHERE dur > 0;+EOF+trace_processor trace.json -q /tmp/q.sql++# 3. What's on the critical path? — phase durations+# Shows time between milestones: serial setup, parallel work, finalization+# Key milestones: "Skeleton rendered", "Parallel execution started", "All results drained"+cat > /tmp/q.sql << 'EOF'+SELECT+ name,+ ROUND(ts/1e6, 1) as ms,+ ROUND((ts - LAG(ts) OVER (ORDER BY ts))/1e6, 1) as phase_ms+FROM slice WHERE dur = 0+ORDER BY ts;+EOF+trace_processor trace.json -q /tmp/q.sql++# 3. What's on the critical path? — parallel bottleneck (per-worktree)+# The worktree with the highest total_ms is the likely parallel bottleneck+cat > /tmp/q.sql << 'EOF'+SELECT+ EXTRACT_ARG(arg_set_id, 'args.context') as worktree,+ COUNT(*) as commands,+ ROUND(SUM(dur)/1e6, 1) as total_ms+FROM slice WHERE dur > 0+GROUP BY worktree ORDER BY total_ms DESC;EOFtrace_processor trace.json -q /tmp/q.sql```