Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(perf): require --progressive in wt-perf trace pipeline and trim duplication (#2258)

Maximilian Roosd2d38dd458d9
diff --git a/benches/CLAUDE.md b/benches/CLAUDE.md
index 3923a031a..dc8616e94 100644
--- a/benches/CLAUDE.md
+++ b/benches/CLAUDE.md
@@ -87,8 +87,10 @@ cargo run -p wt-perf -- invalidate /tmp/wt-perf-typical-8/main
### Generating traces
```bash
-# Generate trace.json for Perfetto/Chrome
-RUST_LOG=debug wt list --branches 2>&1 \
+# Generate trace.json for Perfetto/Chrome. `--progressive` forces TTY-gated
+# events (Skeleton rendered, First result received) to fire even when stdout
+# is piped.
+RUST_LOG=debug wt list --progressive --branches 2>&1 \
| cargo run -p wt-perf -- trace > trace.json
# Open in https://ui.perfetto.dev or chrome://tracing
@@ -196,7 +198,7 @@ trace_processor trace.json -q /tmp/q.sql
```bash
# Trace on rust-lang/rust (must run benchmark first to clone)
-RUST_LOG=debug cargo run --release -q -- -C target/bench-repos/rust list --branches 2>&1 \
+RUST_LOG=debug cargo run --release -q -- -C target/bench-repos/rust list --progressive --branches 2>&1 \
| cargo run -p wt-perf -- trace > rust-trace.json
```
diff --git a/src/trace/chrome.rs b/src/trace/chrome.rs
index 872faab45..ba4423175 100644
--- a/src/trace/chrome.rs
+++ b/src/trace/chrome.rs
@@ -8,12 +8,7 @@
//! - **Complete events** (`ph: "X"`): Command executions with duration
//! - **Instant events** (`ph: "I"`): Milestones without duration (e.g., "Showed skeleton")
//!
-//! # Usage
-//!
-//! ```bash
-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace > trace.json
-//! # Then open trace.json in chrome://tracing or https://ui.perfetto.dev
-//! ```
+//! See [`crate::trace`] for the capture pipeline and SQL query examples.
//!
//! # Format Reference
//!
diff --git a/src/trace/mod.rs b/src/trace/mod.rs
index 4c4dde977..50bf26389 100644
--- a/src/trace/mod.rs
+++ b/src/trace/mod.rs
@@ -12,8 +12,9 @@
//! # Usage
//!
//! ```bash
-//! # Generate Chrome Trace Format
-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace > trace.json
+//! # Generate Chrome Trace Format (--progressive forces TTY-gated events
+//! # like `Skeleton rendered` to fire even when stdout is piped)
+//! RUST_LOG=debug wt list --progressive 2>&1 | cargo run -p wt-perf -- trace > trace.json
//!
//! # Visualize: open trace.json in chrome://tracing or https://ui.perfetto.dev
//!
diff --git a/tests/helpers/wt-perf/src/lib.rs b/tests/helpers/wt-perf/src/lib.rs
index 9adedc294..655588443 100644
--- a/tests/helpers/wt-perf/src/lib.rs
+++ b/tests/helpers/wt-perf/src/lib.rs
@@ -19,18 +19,7 @@
//! invalidate_caches_auto(&repo_path);
//! ```
//!
-//! # CLI Usage
-//!
-//! ```bash
-//! # Set up a benchmark repo
-//! cargo run -p wt-perf -- setup typical-8
-//!
-//! # Invalidate caches
-//! cargo run -p wt-perf -- invalidate /path/to/repo
-//!
-//! # Parse trace logs
-//! RUST_LOG=debug wt list 2>&1 | cargo run -p wt-perf -- trace
-//! ```
+//! See `wt-perf --help` for CLI usage.
use std::path::{Path, PathBuf};
use std::sync::OnceLock;
diff --git a/tests/helpers/wt-perf/src/main.rs b/tests/helpers/wt-perf/src/main.rs
index dd8b87681..c375e8766 100644
--- a/tests/helpers/wt-perf/src/main.rs
+++ b/tests/helpers/wt-perf/src/main.rs
@@ -1,20 +1,6 @@
//! CLI for worktrunk performance testing and tracing.
//!
-//! # Usage
-//!
-//! ```bash
-//! # Set up a benchmark repo
-//! wt-perf setup typical-8 --path /tmp/bench
-//!
-//! # Invalidate caches for cold run
-//! wt-perf invalidate /tmp/bench/main
-//!
-//! # Parse trace logs (pipe from wt command)
-//! RUST_LOG=debug wt list 2>&1 | wt-perf trace > trace.json
-//!
-//! # Set up picker test environment
-//! wt-perf setup picker-test
-//! ```
+//! Run `wt-perf --help` (and `wt-perf <subcommand> --help`) for usage.
use std::io::{IsTerminal, Read, Write};
use std::path::PathBuf;
@@ -55,7 +41,9 @@ enum Commands {
/// Parse trace logs and output Chrome Trace Format JSON
#[command(after_long_help = r#"EXAMPLES:
# Generate trace from wt command
- RUST_LOG=debug wt list 2>&1 | wt-perf trace > trace.json
+ # --progressive is required — without it, TTY-gated events (Skeleton
+ # rendered, First result received) don't fire when stdout is a pipe.
+ RUST_LOG=debug wt list --progressive 2>&1 | wt-perf trace > trace.json
# Then either:
# - Open trace.json in chrome://tracing or https://ui.perfetto.dev
@@ -75,15 +63,10 @@ enum Commands {
/// Analyze trace logs for duplicate commands (cache effectiveness)
#[command(after_long_help = r#"EXAMPLES:
# Check cache effectiveness for wt list
- RUST_LOG=debug wt list 2>&1 | wt-perf cache-check
+ RUST_LOG=debug wt list --progressive 2>&1 | wt-perf cache-check
# From a file
wt-perf cache-check trace.log
-
- # With a benchmark repo
- cargo run -p wt-perf -- setup typical-8 --persist
- RUST_LOG=debug wt -C /tmp/wt-perf-typical-8 list 2>&1 \
- | cargo run -p wt-perf -- cache-check
"#)]
CacheCheck {
/// Path to trace log file (reads from stdin if omitted)
@@ -139,7 +122,7 @@ fn main() {
eprintln!("Created: {}", parts.join(", "));
eprintln!();
eprintln!(
- " RUST_LOG=debug wt -C {} list 2>&1 | wt-perf trace > trace.json",
+ " RUST_LOG=debug wt -C {} list --progressive 2>&1 | wt-perf trace > trace.json",
base_path.display()
);
eprintln!(" wt-perf invalidate {}", base_path.display());
@@ -199,10 +182,8 @@ fn read_trace_entries(file: Option<&std::path::Path>) -> Vec<worktrunk::trace::T
_ => {
if std::io::stdin().is_terminal() {
eprintln!(
- "\
-Reading from stdin... (pipe trace data or use Ctrl+D to end)
-
-Hint: RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"
+ "Reading from stdin... (pipe trace data or use Ctrl+D to end)\n\
+ See `wt-perf <subcommand> --help` for the capture pipeline."
);
}
@@ -219,15 +200,9 @@ Hint: RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"
if entries.is_empty() {
eprintln!(
- "\
-No trace entries found in input.
-
-Trace lines should look like:
- [wt-trace] ts=1234567890 tid=3 cmd=\"git status\" dur_us=12300 ok=true
- [wt-trace] ts=1234567890 tid=3 event=\"Showed skeleton\"
-
-To capture traces, run with RUST_LOG=debug:
- RUST_LOG=debug wt list 2>&1 | wt-perf <subcommand>"
+ "No [wt-trace] entries found in input.\n\
+ Run the target command with RUST_LOG=debug to emit trace records.\n\
+ See `wt-perf <subcommand> --help` for the capture pipeline."
);
std::process::exit(1);
}
diff --git a/tests/integration_tests/analyze_trace.rs b/tests/integration_tests/analyze_trace.rs
index 2bbfb30b3..ea242f372 100644
--- a/tests/integration_tests/analyze_trace.rs
+++ b/tests/integration_tests/analyze_trace.rs
@@ -108,7 +108,7 @@ fn test_wt_perf_trace_empty_input() {
let stderr = String::from_utf8_lossy(&output.stderr);
assert!(
- stderr.contains("No trace entries found"),
+ stderr.contains("No [wt-trace] entries found"),
"Should indicate no trace entries"
);
}