Skip to content
Merged
55 changes: 45 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,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 +289,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 @@ -326,12 +334,13 @@ warnings[1]: 1 render-blocking resource(s) detected.

# Drill-down commands:
# - 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 +355,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 +378,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 +389,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 +399,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 +450,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 +478,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 +509,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 +536,18 @@ 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
```

---

## Output Formats

### TOON (Default)
Expand Down
Loading