Analyze Performance Profiles

Analyze .cpuprofile files (V8 sampling profiler) and DevTools trace files (Trace-*.json, Chrome Trace Event Format) to find performance bottlenecks, compare code paths, and understand timing.

When to Use

• User provides a .cpuprofile or Trace-*.json file and wants to understand performance
• Investigating why one code path is slower than another
• Finding what functions consume the most time
• Comparing "before/after" or "old/new" implementations in a single profile
• Investigating layout thrashing, long tasks, or rendering bottlenecks (trace files)
• Analyzing VS Code user timing marks like code/didResolveTextFileEditorModel (trace files)
• Understanding multi-process behavior (Browser, Renderer, GPU processes in trace files)

Detecting File Type

• .cpuprofile: Top-level JSON with nodes, samples, timeDeltas keys. Created by the VS Code profiler.
• Trace-*.json: Top-level JSON with traceEvents array (and optional metadata). Created by Chrome/Electron DevTools (Performance tab). These are richer than .cpuprofile -- they contain CPU samples, layout/paint events, user timing marks, GC events, input events, and multi-process data.

Key Concepts

• Sampling profiler: The profiler periodically snapshots the call stack. Not every function appears -- only those on the stack when the profiler sampled. Don't expect exact function names; look for patterns and nearby activity.
• Self time: Time spent in the function itself (the leaf/innermost frame).
• Total time: Time the function was anywhere on the stack (includes callees).
• Idle samples: Frames labeled (idle), (program), or (garbage collector) represent no user code running.

Part 1: .cpuprofile Files

Profile Format

A .cpuprofile is JSON with these top-level keys:

• nodes: Array of call frame nodes forming a tree (each has id, callFrame, children)
• samples: Array of node IDs -- one per profiler tick, referencing the leaf (innermost) frame
• timeDeltas: Array of microsecond deltas between consecutive samples
• startTime / endTime: Absolute timestamps in microseconds
• $vscode: Optional VS Code metadata

Procedure

1. Check File Size and Parse

Profile and trace files can exceed V8's string limit (~512MB). Always check the file size first and choose the right parsing strategy:

import { readFileSync, statSync } from 'fs';

const stat = statSync(profilePath);
const sizeMB = stat.size / (1024 * 1024);
console.log(`File size: ${sizeMB.toFixed(0)}MB`);

let data;
if (sizeMB < 400) {
    // Small enough for JSON.parse
    data = JSON.parse(readFileSync(profilePath, 'utf8'));
} else {
    // Too large -- use Buffer-based extraction (see "Handling Huge Files" section)
    data = parseProfileFromBuffer(readFileSync(profilePath));
}

For files under ~400MB, JSON.parse(readFileSync(..., 'utf8')) works fine. For larger files, see the Handling Huge Files section below.

2. Reformat the File (small files only)

Profiles are often single-line JSON. Reformat for inspection (only if small enough):

if (sizeMB < 400) {
    const data = JSON.parse(fs.readFileSync(profilePath, 'utf8'));
    fs.writeFileSync(profilePath, JSON.stringify(data, null, 2));
}

3. Build Data Structures

Write a Node.js analysis script. Build these structures:

// Node lookup
const nodeMap = new Map();       // id -> node
const parentMap = new Map();     // id -> parent id

// Absolute timestamps from deltas
const timestamps = [data.startTime];
for (let i = 0; i < data.timeDeltas.length; i++) {
    timestamps.push(timestamps[i] + data.timeDeltas[i]);
}

// Stack walker (leaf to root)
function getStack(sampleNodeId) {
    const stack = [];
    let id = sampleNodeId;
    while (id !== undefined) {
        const node = nodeMap.get(id);
        if (node) stack.push(node.callFrame.functionName);
        id = parentMap.get(id);

…