Skip to content
Merged
91 changes: 78 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,9 @@ npx trace-engine-cli /path/to/trace.json.gz
### How Agents Discover Capabilities

1. **Default overview + built-in drill-down hints (`trace-engine-cli <file>`)**:
Calling `trace-engine-cli <file>` with no subcommand runs `overview` and appends a `# Drill-down commands:` reference footer to the output. That first call gives the agent the trace bounds, Core Web Vitals, main-thread category breakdown, and the exact syntax for every follow-up subcommand.
Calling `trace-engine-cli <file>` with no subcommand runs `overview` and appends a `# Drill-down commands:` reference footer to the output. That first call gives the agent the trace bounds, Core Web Vitals, main-thread category breakdown, and syntax for follow-up commands.
2. **Top-level command discovery (`trace-engine-cli` or `trace-engine-cli --help`)**:
Running `trace-engine-cli` with no arguments or passing `--help` prints all 13 subcommands (`overview`, `insights`, `tasks`, `find`, `profile`, `diff`, `scheduling`, `network`, `interactions`, `shifts`, `events`, `navigations`, `scan`) and global options.
Running `trace-engine-cli` with no arguments or passing `--help` prints the available commands and global options.
3. **Subcommand flag discovery (`trace-engine-cli <subcommand> --help`)**:
Running `--help` on any subcommand (for example, `trace-engine-cli insights --help` or `trace-engine-cli events --help`) prints the flags, choices, and defaults for that command.

Expand All @@ -57,7 +57,8 @@ Add this snippet to your project instruction file (`AGENTS.md`, `CLAUDE.md`, or
## Performance Trace Analysis (`.json`, `.json.gz`)

- Never parse or search trace files manually with `jq`, `python`, `node -e`, `zcat`, or shell loops. Use `trace-engine-cli`, which handles gzip decompression, DevTools Trace Engine parsing, and token-compact TOON formatting.
- Start any single-trace investigation by running `trace-engine-cli <file>`. Read the overview and the `# Drill-down commands:` footer appended to the output to choose follow-up commands.
- Start an open-ended trace investigation with `trace-engine-cli <file>`. Use its drill-down suggestions to choose follow-up commands.
- When you already know which analyses you need for one trace, run `trace-engine-cli report <file> --sections <list>` to parse it once.
- To search across multiple trace files or directories, run `trace-engine-cli scan <dir-or-glob> [options]`.
- Run `trace-engine-cli --help` or `trace-engine-cli <subcommand> --help` to inspect available subcommands and flags.
```
Expand Down Expand Up @@ -105,6 +106,15 @@ High-level trace metadata, duration, Core Web Vitals (LCP, INP, CLS), and main-t
trace-engine-cli trace.json.gz
```

### `trace-engine-cli report <file>`
When you know which analyses a question needs, select them with `--sections`
so they share one trace parse. Run `trace-engine-cli report --help` to see the
available sections.

```bash
trace-engine-cli report trace.json.gz --sections overview,shifts,network
```

### `trace-engine-cli insights <file>`
Diagnostic insight cards for Core Web Vitals and performance bottlenecks.
```bash
Expand Down Expand Up @@ -227,6 +237,10 @@ trace-engine-cli scan fixtures/traces/ --cat devtools.timeline --phase X
3. Inspect relevant subsystem: `trace-engine-cli shifts <fixture> --events`, `trace-engine-cli network <fixture>`, or `trace-engine-cli insights <fixture> --category <category>`
4. Inspect raw event payloads: `trace-engine-cli events <fixture> --name <EventName> --fields <fieldPaths>`

### Recipe D: Analyzing CPU Activity in a Subframe
1. Run `trace-engine-cli threads <file>` and find the renderer thread by frame URL.
2. Pass its `PID:TID` as `--thread` to a CPU command, for example `trace-engine-cli tasks <file> --thread 123:1`. Frames that share a renderer thread share its CPU results.

---

## 5. Capture Caveats
Expand Down Expand Up @@ -285,6 +299,10 @@ All time-range inputs (`--time-range`, `--window-a`, `--window-b`, `--bucket`) s
### 1. `overview` (default)
High-level trace metadata, Core Web Vitals (FCP, LCP, CLS, INP), non-overlapping main-thread category breakdown (Scripting, Layout, Rendering, GC, System, Idle), and diagnostic warnings.

The breakdown uses the same instrumented timeline events with and without CPU
samples. With `--thread PID:TID`, the breakdown describes that
renderer thread and Web Vitals still describe the page.

```bash
# Default invocation (includes the drill-down commands footer)
trace-engine-cli trace.json.gz
Expand Down Expand Up @@ -325,13 +343,15 @@ mainThreadBreakdown:
warnings[1]: 1 render-blocking resource(s) detected.

# Drill-down commands:
# - trace-engine-cli report <file> [--sections <list>]
# - trace-engine-cli insights <file> [--category <lcp|inp|cls|render-blocking|third-parties>] [--navigation <id>]
# - trace-engine-cli tasks <file> [--min-duration <ms>] [--tree <bottom-up|top-down>] [--top <n>]
# - trace-engine-cli find <file> --function <name> [--time-range <start,end>]
# - trace-engine-cli tasks <file> [--min-duration <ms>] [--tree <bottom-up|top-down>] [--url-only] [--top <n>]
# - trace-engine-cli find <file> [--function <name>] [--url <pattern>] [--time-range <start,end>]
# - trace-engine-cli threads <file>
# - trace-engine-cli profile <file> [--time-range <start,end>] [--bucket <ms>]
# - trace-engine-cli diff <file> --window-a <start,end> --window-b <start,end>
# - trace-engine-cli scheduling <file> [--time-range <start,end>]
# - trace-engine-cli network <file> [--render-blocking] [--slowest <n>] [--initiator-chain <url>]
# - trace-engine-cli network <file> [--render-blocking] [--slowest <n>] [--initiator-chain <url>] [--strip-query]
# - trace-engine-cli interactions <file>
# - trace-engine-cli shifts <file> [--events]
# - trace-engine-cli events <file> [--name <names>] [--cat <category>] [--fields <fields>]
Expand All @@ -346,6 +366,10 @@ warnings[1]: 1 render-blocking resource(s) detected.
### 2. `insights`
Extracts actionable diagnostic insight cards generated by Chrome DevTools Insight models.

The default is a main-frame navigation with a measured LCP when available.
Use `--navigation` to select a trace navigation ID or InsightSet ID.
With `--time-range`, insights select from navigation windows that overlap the range.

```bash
# All insights
trace-engine-cli insights trace.json.gz
Expand All @@ -365,7 +389,9 @@ trace-engine-cli insights trace.json.gz --navigation 9E74B39B7C378297071F6E3618C
---

### 3. `tasks`
Main thread task execution, long tasks, and aggregated call trees.
Long tasks and aggregated call trees for a renderer thread. Aggregated rows
show their first event timestamp. Top-down rows include the call path, and
`--url-only` limits output to rows with source URLs.

```bash
# List long tasks above 50ms (default)
Expand All @@ -374,8 +400,8 @@ trace-engine-cli tasks trace.json.gz
# Custom duration threshold and limit within relative window
trace-engine-cli tasks trace.json.gz --min-duration 20 --time-range "1s,4s" --top 10

# Bottom-up call tree (aggregated and sorted by self-time)
trace-engine-cli tasks trace.json.gz --tree bottom-up --top 20
# Bottom-up call tree with source URLs, sorted by self-time
trace-engine-cli tasks trace.json.gz --tree bottom-up --url-only --top 20

# Top-down call tree (aggregated and sorted by total duration)
trace-engine-cli tasks trace.json.gz --tree top-down --top 20
Expand All @@ -384,14 +410,15 @@ trace-engine-cli tasks trace.json.gz --tree top-down --top 20
---

### 4. `find`
Search for executions of a specific function name or pattern to verify call frequency, duration, or confirm starvation (0 calls in window).
Search executions by function name or script URL substring to inspect call
frequency and duration. Pass both `--function` and `--url` to require both matches.

```bash
# Search for invocations of a function across the whole trace
trace-engine-cli find trace.json.gz --function "drawEventTiles"

# Query within a specific relative time window
trace-engine-cli find trace.json.gz --function "drawEventTiles" --time-range "3.5s,4.2s"
# Search calls in one script within a relative time window
trace-engine-cli find trace.json.gz --url "/app.js" --time-range "3.5s,4.2s"
```

---
Expand Down Expand Up @@ -434,6 +461,9 @@ trace-engine-cli scheduling trace.json.gz --time-range "3.5s,4.1s"
### 8. `network`
Network request waterfall, priority, timings (Queueing, DNS, SSL, TTFB, Download), and request initiator chains.

Use `--strip-query` to remove query strings from request and initiator URLs in
output. Initiator-chain matching still uses the original URLs.

```bash
# Top 20 slowest requests
trace-engine-cli network trace.json.gz --slowest 20
Expand All @@ -459,6 +489,10 @@ trace-engine-cli interactions trace.json.gz
### 10. `shifts`
Cumulative Layout Shift (CLS) session window clusters, cumulative scores, and culprit DOM elements causing visual instability. Pass `--events` to include individual shift event payloads, navigation IDs, and impacted DOM nodes.

For shifted nodes, the CLI reports recorded backend node IDs, renderer process and
frame, and bounding rectangles. It also shows any DOM names and selectors
present in the recording.

```bash
# Cluster summary
trace-engine-cli shifts trace.json.gz
Expand Down Expand Up @@ -486,7 +520,7 @@ trace-engine-cli events trace.json.gz --cat devtools.timeline --phase X --top 20
---

### 12. `navigations` (alias: `navs`)
Inspect all navigations in the trace, their primary main frame status, and their mapped Chrome DevTools Trace Engine `InsightSet` IDs:
Inspect navigations, their primary main frame status, and their mapped Chrome DevTools Trace Engine `InsightSet` IDs. Pass `--time-range` to list starts within a window.

```bash
trace-engine-cli navigations trace.json.gz
Expand All @@ -513,6 +547,37 @@ trace-engine-cli scan fixtures/ --name TracingStartedInBrowser --fields args.dat

---

### 14. `threads`

List renderer threads, their frame URLs, and CPU sample availability. Use
`--thread PID:TID` with `overview`, `tasks`, `profile`, `find`, or `diff` to
select a renderer, including one for an out-of-process iframe.

```bash
trace-engine-cli threads trace.json.gz
```

---

### 15. `report`

Run selected analyses from one trace parse. Each section uses its standalone
command's defaults.

| Option | Description |
| --- | --- |
| `--sections <list>` | Comma-separated section names. Defaults to `overview,tasks,shifts,network`. Use `report --help` to list the available sections. |
| `--time-range <range>` | Shared time window. Each section interprets it as its standalone command does. |
| `--thread <PID:TID>` | Renderer thread for `overview`, `tasks`, and `profile`. |
| `--strip-query` | Remove query strings from URLs in the `network` section. |

```bash
trace-engine-cli report trace.json.gz
trace-engine-cli report trace.json.gz --sections overview,insights,tasks --format md
```

---

## Output Formats

### TOON (Default)
Expand Down
Loading