Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Chrome Trace Format output for concurrency visualization.
//!
//! Converts trace entries to Chrome Trace Event Format JSON, which can be
//! visualized in chrome://tracing or <https://ui.perfetto.dev>.
//!
//! # Event Types
//!
//! - **Complete events** (`ph: "X"`): Command executions and in-process spans, both with duration
//! - **Instant events** (`ph: "I"`): Milestones without duration (e.g., "Showed skeleton")
//!
//! See [`crate::trace`] for the capture pipeline.
//!
//! # Format Reference
//!
//! - [Trace Event Format](https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/)
//! - [Perfetto UI](https://ui.perfetto.dev)
use serde::Serialize;
use super::{TraceEntry, TraceEntryKind};
/// A Chrome Trace Event in the Trace Event Format.
///
/// Uses `#[serde(skip_serializing_if)]` to emit the correct fields for each phase:
/// - Complete events ("X"): have `dur`, no `s`
/// - Instant events ("I"): have `s` (scope), no `dur`
#[derive(Debug, Serialize)]
struct TraceEvent {
/// Event name (displayed in the UI)
name: String,
/// Phase: "X" for complete events, "I" for instant events
ph: &'static str,
/// Timestamp in microseconds since epoch
ts: u64,
/// Duration in microseconds (for "X" phase events only)
#[serde(skip_serializing_if = "Option::is_none")]
dur: Option<u64>,
/// Scope for instant events: "g" (global), "p" (process), or "t" (thread)
#[serde(skip_serializing_if = "Option::is_none")]
s: Option<&'static str>,
/// Process ID (we use 1 for all events since wt is single-process)
pid: u32,
/// Thread ID
tid: u64,
/// Category (optional, for filtering in the UI)
#[serde(skip_serializing_if = "Option::is_none")]
cat: Option<String>,
/// Custom arguments (shown when event is selected in UI)
#[serde(skip_serializing_if = "Option::is_none")]
args: Option<TraceEventArgs>,
}
/// Custom arguments attached to trace events.
#[derive(Debug, Serialize)]
struct TraceEventArgs {
/// Worktree context (if any)
#[serde(skip_serializing_if = "Option::is_none")]
context: Option<String>,
/// Whether the command succeeded (always true for instant events)
success: bool,
}
/// The top-level Chrome Trace Format structure.
#[derive(Debug, Serialize)]
struct ChromeTrace {
/// Array of trace events
#[serde(rename = "traceEvents")]
trace_events: Vec<TraceEvent>,
/// Display time unit preference
#[serde(rename = "displayTimeUnit")]
display_time_unit: &'static str,
/// Metadata: tool that generated the trace
#[serde(rename = "meta_generator")]
meta_generator: &'static str,
}
/// Convert trace entries to Chrome Trace Format JSON.
///
/// Returns pretty-printed JSON suitable for chrome://tracing or Perfetto.
/// Entries without timestamp/thread data use 0 as fallback.
///
/// # Event Types
///
/// - Command entries become Complete events (`"ph": "X"`) with duration; categorized as `git`/`network`/none.
/// - Span entries become Complete events with category `wt` so subprocess and in-process work render distinctly.
/// - Instant entries become Instant events (`"ph": "I"`) with global scope.
pub fn to_chrome_trace(entries: &[TraceEntry]) -> String {
let trace_events: Vec<TraceEvent> = entries
.iter()
.map(|entry| {
let ts = entry.start_time_us.unwrap_or(0);
let tid = entry.thread_id.unwrap_or(0);
match &entry.kind {
TraceEntryKind::Command {
command, duration, ..
} => {
// Categorize by program type. The forge CLIs worktrunk
// shells out to — `gh`/`glab` and also `az` (Azure DevOps)
// and `tea` (Gitea) — group under `network`.
let cat = if command.starts_with("git ") {
Some("git".to_string())
} else if ["gh ", "glab ", "az ", "tea "]
.iter()
.any(|prefix| command.starts_with(prefix))
{
Some("network".to_string())
} else {
None
};
TraceEvent {
name: command.clone(),
ph: "X", // Complete event (has duration)
ts,
dur: Some(duration.as_micros() as u64),
s: None,
pid: 1,
tid,
cat,
args: Some(TraceEventArgs {
context: entry.context.clone(),
success: entry.is_success(),
}),
}
}
TraceEntryKind::Instant { name } => {
TraceEvent {
name: name.clone(),
ph: "I", // Instant event (no duration)
ts,
dur: None,
s: Some("g"), // Global scope - shows across all threads
pid: 1,
tid,
cat: Some("milestone".to_string()),
args: Some(TraceEventArgs {
context: entry.context.clone(),
success: true,
}),
}
}
TraceEntryKind::Span { name, duration } => TraceEvent {
name: name.clone(),
ph: "X", // Complete event (has duration)
ts,
dur: Some(duration.as_micros() as u64),
s: None,
pid: 1,
tid,
cat: Some("wt".to_string()),
args: Some(TraceEventArgs {
context: entry.context.clone(),
success: true,
}),
},
}
})
.collect();
let chrome_trace = ChromeTrace {
trace_events,
display_time_unit: "ms",
meta_generator: "worktrunk analyze-trace",
};
serde_json::to_string_pretty(&chrome_trace).expect("Failed to serialize trace to JSON")
}
#[cfg(test)]
mod tests {
use std::time::Duration;
use super::*;
use crate::trace::TraceResult;
fn make_command_entry(
command: &str,
duration_ms: u64,
start_time_us: Option<u64>,
thread_id: Option<u64>,
) -> TraceEntry {
TraceEntry {
context: Some("feature".to_string()),
kind: TraceEntryKind::Command {
command: command.to_string(),
duration: Duration::from_millis(duration_ms),
result: TraceResult::Completed { success: true },
reads_stdin: false,
},
start_time_us,
thread_id,
}
}
fn make_instant_entry(
name: &str,
start_time_us: Option<u64>,
thread_id: Option<u64>,
) -> TraceEntry {
TraceEntry {
context: None,
kind: TraceEntryKind::Instant {
name: name.to_string(),
},
start_time_us,
thread_id,
}
}
fn make_span_entry(
name: &str,
duration_us: u64,
start_time_us: Option<u64>,
thread_id: Option<u64>,
) -> TraceEntry {
TraceEntry {
context: None,
kind: TraceEntryKind::Span {
name: name.to_string(),
duration: Duration::from_micros(duration_us),
},
start_time_us,
thread_id,
}
}
#[test]
fn test_to_chrome_trace_with_timestamps() {
let entries = vec![
make_command_entry("git status", 10, Some(1000000), Some(1)),
make_command_entry("git diff", 20, Some(1000000), Some(2)),
make_command_entry("git log", 15, Some(1010000), Some(1)),
];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
assert_eq!(parsed["displayTimeUnit"], "ms");
assert_eq!(parsed["meta_generator"], "worktrunk analyze-trace");
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events.len(), 3);
// First event
assert_eq!(events[0]["name"], "git status");
assert_eq!(events[0]["ph"], "X");
assert_eq!(events[0]["ts"], 1000000);
assert_eq!(events[0]["dur"], 10000); // 10ms = 10000µs
assert_eq!(events[0]["tid"], 1);
assert_eq!(events[0]["cat"], "git");
// Second event (parallel on thread 2)
assert_eq!(events[1]["tid"], 2);
assert_eq!(events[1]["ts"], 1000000); // Same start time = parallel
}
#[test]
fn test_to_chrome_trace_without_timestamps() {
// Old format entries without ts/tid get 0 as fallback
let entries = vec![
make_command_entry("git status", 10, None, None),
make_command_entry("git diff", 20, None, None),
];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
// Fallback: both get ts=0 and tid=0
assert_eq!(events[0]["ts"], 0);
assert_eq!(events[1]["ts"], 0);
assert_eq!(events[0]["tid"], 0);
assert_eq!(events[1]["tid"], 0);
}
#[test]
fn test_category_assignment() {
let entries = vec![
make_command_entry("git status", 10, Some(0), Some(1)),
make_command_entry("gh pr list", 100, Some(0), Some(2)),
make_command_entry("glab mr list", 100, Some(0), Some(3)),
make_command_entry("az repos pr show", 100, Some(0), Some(4)),
make_command_entry("tea api /repos/x/y", 100, Some(0), Some(5)),
make_command_entry("echo hello", 1, Some(0), Some(6)),
];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events[0]["cat"], "git");
// All forge CLIs (gh, glab, az, tea) group under `network`.
assert_eq!(events[1]["cat"], "network");
assert_eq!(events[2]["cat"], "network");
assert_eq!(events[3]["cat"], "network");
assert_eq!(events[4]["cat"], "network");
assert!(events[5]["cat"].is_null()); // No category for other commands
}
#[test]
fn test_args_include_context() {
let entries = vec![make_command_entry("git status", 10, Some(0), Some(1))];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events[0]["args"]["context"], "feature");
assert_eq!(events[0]["args"]["success"], true);
}
// ========================================================================
// Instant event tests
// ========================================================================
#[test]
fn test_instant_event() {
let entries = vec![make_instant_entry(
"Showed skeleton",
Some(1000000),
Some(1),
)];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events.len(), 1);
assert_eq!(events[0]["name"], "Showed skeleton");
assert_eq!(events[0]["ph"], "I"); // Instant event
assert_eq!(events[0]["ts"], 1000000);
assert_eq!(events[0]["s"], "g"); // Global scope
assert_eq!(events[0]["cat"], "milestone");
assert!(events[0]["dur"].is_null()); // No duration for instant events
assert_eq!(events[0]["args"]["success"], true);
}
#[test]
fn test_span_event() {
let entries = vec![make_span_entry("config_load", 8000, Some(1000000), Some(1))];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events.len(), 1);
assert_eq!(events[0]["name"], "config_load");
assert_eq!(events[0]["ph"], "X"); // Complete event
assert_eq!(events[0]["ts"], 1000000);
assert_eq!(events[0]["dur"], 8000);
assert_eq!(events[0]["cat"], "wt");
assert!(events[0]["s"].is_null());
assert_eq!(events[0]["args"]["success"], true);
}
#[test]
fn test_mixed_events() {
let entries = vec![
make_instant_entry("Started", Some(1000000), Some(1)),
make_command_entry("git status", 10, Some(1000100), Some(1)),
make_instant_entry("Showed skeleton", Some(1010000), Some(1)),
make_command_entry("git diff", 20, Some(1010100), Some(2)),
make_instant_entry("Done", Some(1030000), Some(1)),
];
let json = to_chrome_trace(&entries);
let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
let events = parsed["traceEvents"].as_array().unwrap();
assert_eq!(events.len(), 5);
// Check instant events
assert_eq!(events[0]["ph"], "I");
assert_eq!(events[0]["name"], "Started");
assert_eq!(events[2]["ph"], "I");
assert_eq!(events[2]["name"], "Showed skeleton");
assert_eq!(events[4]["ph"], "I");
assert_eq!(events[4]["name"], "Done");
// Check command events
assert_eq!(events[1]["ph"], "X");
assert_eq!(events[1]["name"], "git status");
assert_eq!(events[3]["ph"], "X");
assert_eq!(events[3]["name"], "git diff");
}
}