devtools-tracing

Node.js library for programmatic analysis of Chrome DevTools performance traces. Re-exports the trace processing engine from chrome-devtools-frontend and provides higher-level utilities for common tasks.

Install

npm install devtools-tracing

CLI

Analyze traces directly from the command line:

npx devtools-tracing <command> <trace-file>

Supports both .json and .json.gz trace files.

Commands

# 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 -H "Cookie: $cookie" -H "User-Agent: $ua"

See the commands/ directory for full source.

Library usage

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 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.