devtools-tracing 1.2.2 → 1.4.0

package/.vscode/launch.json

@@ -0,0 +1,44 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug selector-stats",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "selector-stats", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug inp",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "inp", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug sourcemap",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "sourcemap", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    },
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug stats",
+      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+      "args": ["cli.ts", "stats", "${input:traceFile}"],
+      "console": "integratedTerminal"
+    }
+  ],
+  "inputs": [
+    {
+      "id": "traceFile",
+      "type": "promptString",
+      "description": "Path to trace file (.json or .json.gz)"
+    }
+  ]
+}

package/README.md

@@ -1,4 +1,70 @@
 # devtools-tracing
 
-Slightly trimmed down re-export of tracing related utilities from
-[devtools-frontend](https://github.com/ChromeDevTools/devtools-frontend).
+Node.js library for programmatic analysis of Chrome DevTools performance traces. Re-exports the trace processing engine from [chrome-devtools-frontend](https://www.npmjs.com/package/chrome-devtools-frontend) and provides higher-level utilities for common tasks.
+
+## Install
+
+```sh
+npm install devtools-tracing
+```
+
+## CLI
+
+Analyze traces directly from the command line:
+
+```sh
+npx devtools-tracing <command> <trace-file>
+```
+
+Supports both `.json` and `.json.gz` trace files.
+
+### Commands
+
+```sh
+# Top CSS selectors by elapsed time and match attempts, plus invalidation tracking
+npx devtools-tracing selector-stats trace.json.gz
+
+# INP (Interaction to Next Paint) breakdown
+npx devtools-tracing inp trace.json.gz
+
+# Timeline category statistics
+npx devtools-tracing stats trace.json.gz
+
+# Source map symbolication (writes a .symbolicated.json.gz alongside the input)
+npx devtools-tracing sourcemap trace.json.gz
+```
+
+See the [`commands/`](./commands) directory for full source.
+
+## Library usage
+
+```ts
+import * as fs from 'node:fs';
+import * as zlib from 'node:zlib';
+import { initDevToolsTracing, Trace } from 'devtools-tracing';
+
+// Must be called once before using the library.
+initDevToolsTracing();
+
+const raw = fs.readFileSync('trace.json.gz');
+const traceData = JSON.parse(
+  zlib.gunzipSync(raw).toString(),
+) as Trace.Types.File.TraceFile;
+
+const model = Trace.TraceModel.Model.createWithAllHandlers();
+await model.parse(traceData.traceEvents, {
+  isCPUProfile: false,
+  isFreshRecording: false,
+  metadata: traceData.metadata,
+});
+
+const parsedTrace = model.parsedTrace(0);
+```
+
+## How it works
+
+A [build script](./generate.ts) extracts trace-related code from the `chrome-devtools-frontend` npm package into `lib/`, resolving dependencies via AST analysis and stubbing browser APIs. The result is bundled into a single CommonJS file via esbuild.
+
+## License
+
+BSD-3-Clause, matching the license of [chrome-devtools-frontend](https://github.com/ChromeDevTools/devtools-frontend/blob/main/LICENSE).

package/cli.ts

@@ -0,0 +1,46 @@
+import { run as cssSelectors } from './commands/selector-stats.js';
+import { run as inp } from './commands/inp.js';
+import { run as sourcemap } from './commands/sourcemap.js';
+import { run as stats } from './commands/stats.js';
+
+const commands: Record<string, (tracePath: string) => Promise<void>> = {
+  'selector-stats': cssSelectors,
+  inp,
+  sourcemap,
+  stats,
+};
+
+function printUsage() {
+  console.log('Usage: devtools-tracing <command> <trace-file>');
+  console.log('\nCommands:');
+  console.log('  selector-stats  Top CSS selectors from selector stats and invalidation tracking');
+  console.log('  inp            Extract INP (Interaction to Next Paint) breakdown');
+  console.log('  sourcemap      Symbolicate a trace using source maps');
+  console.log('  stats          Generate timeline category statistics');
+}
+
+async function main() {
+  const [command, tracePath] = process.argv.slice(2);
+
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const run = commands[command];
+  if (!run) {
+    console.error(`Unknown command: ${command}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  if (!tracePath) {
+    console.error(`Missing trace file path.`);
+    console.error(`Usage: devtools-tracing ${command} <trace-file>`);
+    process.exit(1);
+  }
+
+  await run(tracePath);
+}
+
+main();

package/{examples → commands}/inp.ts

@@ -3,12 +3,7 @@ import * as zlib from 'node:zlib';
 
 import { initDevToolsTracing, Trace } from '../';
 
-async function main() {
-  const tracePath = process.argv[2];
-  if (!tracePath) {
-    console.error('Usage: npm run examples:inp <path-to-trace-file>');
-    process.exit(1);
-  }
+export async function run(tracePath: string) {
   initDevToolsTracing();
 
   const fileData = fs.readFileSync(tracePath);
@@ -30,5 +25,3 @@ async function main() {
     inp,
   });
 }
-
-main();

package/commands/selector-stats.ts

@@ -0,0 +1,145 @@
+import * as fs from 'node:fs';
+import * as zlib from 'node:zlib';
+
+import { initDevToolsTracing, Trace } from '../';
+
+const SelectorTimingsKey = Trace.Types.Events.SelectorTimingsKey;
+
+export async function run(tracePath: string) {
+  initDevToolsTracing();
+
+  const fileData = fs.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith('.gz')
+    ? zlib.gunzipSync(fileData)
+    : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString(),
+  ) as Trace.Types.File.TraceFile;
+
+  const traceModel = Trace.TraceModel.Model.createWithAllHandlers({
+    debugMode: true,
+    enableAnimationsFrameHandler: false,
+    maxInvalidationEventsPerEvent: 20,
+    showAllEvents: false,
+  });
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false,
+  });
+  const parsedTrace = traceModel.parsedTrace(0)!;
+  const parsedTraceData = parsedTrace.data;
+
+  // --- Selector Stats ---
+  const selectorStatsData = parsedTraceData.SelectorStats;
+  const selectorMap = new Map<
+    string,
+    Trace.Types.Events.SelectorTiming
+  >();
+
+  for (const [, value] of selectorStatsData.dataForRecalcStyleEvent) {
+    for (const timing of value.timings) {
+      const key =
+        timing[SelectorTimingsKey.Selector] +
+        '_' +
+        timing[SelectorTimingsKey.StyleSheetId];
+      const existing = selectorMap.get(key);
+      if (existing) {
+        existing[SelectorTimingsKey.Elapsed] +=
+          timing[SelectorTimingsKey.Elapsed];
+        existing[SelectorTimingsKey.MatchAttempts] +=
+          timing[SelectorTimingsKey.MatchAttempts];
+        existing[SelectorTimingsKey.MatchCount] +=
+          timing[SelectorTimingsKey.MatchCount];
+        existing[SelectorTimingsKey.FastRejectCount] +=
+          timing[SelectorTimingsKey.FastRejectCount];
+      } else {
+        selectorMap.set(key, { ...timing });
+      }
+    }
+  }
+
+  const allTimings = [...selectorMap.values()];
+  const TOP_N = 15;
+
+  // Top selectors by elapsed time
+  const byElapsed = allTimings
+    .sort(
+      (a, b) =>
+        b[SelectorTimingsKey.Elapsed] - a[SelectorTimingsKey.Elapsed],
+    )
+    .slice(0, TOP_N);
+
+  console.log(`\n=== Top ${TOP_N} CSS Selectors by Elapsed Time ===\n`);
+  for (const t of byElapsed) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1000).toFixed(2);
+    console.log(
+      `  ${elapsedMs}ms | attempts: ${t[SelectorTimingsKey.MatchAttempts]} | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`,
+    );
+  }
+
+  // Top selectors by match attempts
+  const byAttempts = [...selectorMap.values()]
+    .sort(
+      (a, b) =>
+        b[SelectorTimingsKey.MatchAttempts] -
+        a[SelectorTimingsKey.MatchAttempts],
+    )
+    .slice(0, TOP_N);
+
+  console.log(`\n=== Top ${TOP_N} CSS Selectors by Match Attempts ===\n`);
+  for (const t of byAttempts) {
+    const elapsedMs = (t[SelectorTimingsKey.Elapsed] / 1000).toFixed(2);
+    console.log(
+      `  ${t[SelectorTimingsKey.MatchAttempts]} attempts | ${elapsedMs}ms | matches: ${t[SelectorTimingsKey.MatchCount]} | ${t[SelectorTimingsKey.Selector]}`,
+    );
+  }
+
+  // --- Invalidation Tracking ---
+  const invalidatedNodes = selectorStatsData.invalidatedNodeList;
+  console.log(
+    `\n=== Invalidation Tracking (${invalidatedNodes.length} invalidated nodes) ===\n`,
+  );
+
+  // Aggregate selectors that caused invalidations
+  const invalidationSelectorCounts = new Map<string, number>();
+  for (const node of invalidatedNodes) {
+    for (const sel of node.selectorList) {
+      const count = invalidationSelectorCounts.get(sel.selector) ?? 0;
+      invalidationSelectorCounts.set(sel.selector, count + 1);
+    }
+  }
+
+  const topInvalidationSelectors = [...invalidationSelectorCounts.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, TOP_N);
+
+  console.log(
+    `  Top ${TOP_N} selectors causing invalidations:\n`,
+  );
+  for (const [selector, count] of topInvalidationSelectors) {
+    console.log(`  ${count}x | ${selector}`);
+  }
+
+  // Subtree vs single-node invalidations
+  const subtreeCount = invalidatedNodes.filter((n) => n.subtree).length;
+  console.log(
+    `\n  Subtree invalidations: ${subtreeCount} / ${invalidatedNodes.length} total`,
+  );
+
+  // --- Totals ---
+  let totalElapsedUs = 0;
+  let totalMatchAttempts = 0;
+  let totalMatchCount = 0;
+  for (const t of allTimings) {
+    totalElapsedUs += t[SelectorTimingsKey.Elapsed];
+    totalMatchAttempts += t[SelectorTimingsKey.MatchAttempts];
+    totalMatchCount += t[SelectorTimingsKey.MatchCount];
+  }
+  console.log(`\n=== Totals ===\n`);
+  console.log(`  Unique selectors: ${allTimings.length}`);
+  console.log(`  Total elapsed: ${(totalElapsedUs / 1000).toFixed(2)}ms`);
+  console.log(`  Total match attempts: ${totalMatchAttempts}`);
+  console.log(`  Total match count: ${totalMatchCount}`);
+}

package/commands/sourcemap.ts

@@ -0,0 +1,114 @@
+import * as fs from 'node:fs';
+import * as zlib from 'node:zlib';
+
+import {
+  initDevToolsTracing,
+  createSourceMapResolver,
+  symbolicateTrace,
+  Trace,
+} from '../';
+
+export async function run(tracePath: string) {
+  initDevToolsTracing();
+
+  const fileData = fs.readFileSync(tracePath);
+  const decompressedData = tracePath.endsWith('.gz')
+    ? zlib.gunzipSync(fileData)
+    : fileData;
+  const traceData = JSON.parse(
+    decompressedData.toString(),
+  ) as Trace.Types.File.TraceFile;
+
+  const traceModel = Trace.TraceModel.Model.createWithAllHandlers();
+  const resolveSourceMap = createSourceMapResolver({
+    fetch: verboseFetch,
+  });
+
+  await traceModel.parse(traceData.traceEvents, {
+    isCPUProfile: false,
+    isFreshRecording: false,
+    metadata: traceData.metadata,
+    showAllEvents: false,
+    resolveSourceMap,
+  });
+
+  const parsedTrace = traceModel.parsedTrace(0)!;
+  const parsedTraceData = parsedTrace.data;
+  const scripts = parsedTraceData.Scripts.scripts;
+
+  const metadataSourceMaps = traceData.metadata?.sourceMaps?.length ?? 0;
+  console.log(`Found ${scripts.length} scripts in trace`);
+  console.log(`Source maps in trace metadata: ${metadataSourceMaps}\n`);
+
+  // Diagnostic: show script properties to explain resolution results.
+  let withUrl = 0;
+  let withFrame = 0;
+  let withSourceMapUrl = 0;
+  let withElided = 0;
+  for (const script of scripts) {
+    if (script.url) withUrl++;
+    if (script.frame) withFrame++;
+    if (script.sourceMapUrl) withSourceMapUrl++;
+    if (script.sourceMapUrlElided) withElided++;
+  }
+  console.log('Script breakdown:');
+  console.log(`  with url:                ${withUrl}`);
+  console.log(`  with frame:              ${withFrame}`);
+  console.log(`  with sourceMapUrl:       ${withSourceMapUrl}`);
+  console.log(`  with sourceMapUrlElided: ${withElided}`);
+  console.log(`  (resolution requires url + frame + sourceMapUrl/elided)\n`);
+
+  let resolvedCount = 0;
+  for (const script of scripts) {
+    if (!script.sourceMap) {
+      continue;
+    }
+    resolvedCount++;
+
+    const sourceMap = script.sourceMap;
+    const sourceURLs = sourceMap.sourceURLs();
+
+    console.log(
+      `  ${script.url || script.scriptId} -> ${sourceURLs.length} sources, ${sourceMap.mappings().length} mappings`,
+    );
+  }
+
+  console.log(
+    `Resolved source maps for ${resolvedCount} of ${scripts.length} scripts\n`,
+  );
+
+  // Symbolicate the raw trace events in-place using resolved source maps.
+  const result = symbolicateTrace(traceData.traceEvents, scripts);
+  console.log(
+    `Symbolicated ${result.symbolicatedFrames} frames across ${result.symbolicatedEvents} events`,
+  );
+
+  // Write the symbolicated trace to a new file.
+  const outPath = tracePath.replace(/(\.(json|json\.gz))$/i, '.symbolicated$1');
+  if (outPath === tracePath) {
+    console.error(
+      'Could not determine output path (expected .json or .json.gz extension)',
+    );
+    process.exit(1);
+  }
+  const outputJson = JSON.stringify(traceData);
+  if (outPath.endsWith('.gz')) {
+    fs.writeFileSync(outPath, zlib.gzipSync(outputJson));
+  } else {
+    fs.writeFileSync(outPath, outputJson);
+  }
+  console.log(`Wrote symbolicated trace to ${outPath}`);
+}
+
+async function verboseFetch(url: string): Promise<Response> {
+  console.log(`[sourcemap] fetching ${url}`);
+  const response = await fetch(url);
+  if (!response.ok) {
+    console.warn(
+      `[sourcemap] ${url} -> ${response.status} ${response.statusText}`,
+    );
+  } else {
+    console.log(`[sourcemap] ${url} -> ok`);
+  }
+  return response;
+}

package/{examples → commands}/stats.ts

@@ -8,12 +8,7 @@ import {
   Trace,
 } from '../';
 
-async function main() {
-  const tracePath = process.argv[2];
-  if (!tracePath) {
-    console.error('Usage: npm run examples:stats <path-to-trace-file>');
-    process.exit(1);
-  }
+export async function run(tracePath: string) {
   initDevToolsTracing();
 
   const fileData = fs.readFileSync(tracePath);
@@ -27,7 +22,6 @@ async function main() {
   const traceModel = Trace.TraceModel.Model.createWithAllHandlers({
     debugMode: true,
     enableAnimationsFrameHandler: false,
-    // includeRuntimeCallStats: false,
     maxInvalidationEventsPerEvent: 20,
     showAllEvents: false,
   });
@@ -62,5 +56,3 @@ async function main() {
 
   console.log(stats);
 }
-
-main();