Tracing optimization and deopt

The mindset: reproduce, trace, read, fix

Optimisation work in V8 is not guesswork. The engine is instrumented from the inside, and Node/d8 expose that instrumentation through flags. The loop is always the same: reproduce the slow path deterministically, run it under the right trace flag, read the events the flag emits, then fix the data or control flow that caused them — never the engine.

These flags work with node (it embeds V8) and with d8 (the standalone V8 shell). For one-off experiments d8 is cleaner because it has no Node noise. For “what is my real app doing” you want node --prof or --cpu-prof.

Tier tracing: —trace-opt and —trace-deopt

--trace-opt prints a line every time a function is selected for optimisation and by which compiler tier. You learn when a function got hot enough to compile and whether it reached Maglev or TurboFan:

$ node --trace-opt app.js
[marking 0x... <JSFunction parseRow> for optimization to MAGLEV, ...]
[completed optimizing 0x... <JSFunction parseRow> (target MAGLEV)]
[marking 0x... <JSFunction parseRow> for optimization to TURBOFAN, ...]

--trace-deopt is the one you reach for most. It prints a line every time an optimised function bails back to the interpreter — the event behind almost every “fast then slow” regression:

[deoptimizing (DEOPT eager): begin 0x... <JSFunction sum> (opt #3) @5, FP to SP ...
 ;;; deoptimize at <app.js:12:14>, reason: Smi, ...

Read it left to right: the kind (eager = the guard failed on entry to a checked operation; lazy = the function was invalidated while suspended on the stack; soft = a feedback-poverty bail-out that does not throw away the code), the function and optimisation id, the bytecode offset (@5), the source location, and the reason — here Smi, meaning a value the optimised code assumed was a small integer was not. That one word is the diagnosis: a number overflowed the Smi range or a non-integer arrived.

IC and bytecode tracing

--trace-ic logs every inline-cache state transition at every property-access and call site: the progression from uninitialised (0) to premonomorphic, monomorphic (1), polymorphic (P), and megamorphic (N). When a hot site you expected to be monomorphic shows N, you have found shape divergence — the subject of unit 03. The log includes the map (hidden-class) pointers it saw, so you can count how many distinct shapes hit the site.

--print-bytecode dumps the Ignition bytecode for each compiled function — useful to confirm what the interpreter actually runs (for example, that a property load became a generic LdaNamedProperty rather than something cheaper). --print-opt-code with --code-comments dumps the TurboFan-generated machine code with annotations tying instructions back to source; you reach for it only when you need to confirm an instruction-level assumption, not for everyday work.

Forcing the issue with —allow-natives-syntax

For deterministic experiments, --allow-natives-syntax unlocks %-prefixed intrinsics so you can drive the optimiser by hand instead of waiting for the function to warm up naturally:

function sum(a, b) { return a + b; }

sum(1, 2);                         // warm up feedback (it has seen Smis)
%OptimizeFunctionOnNextCall(sum);  // request optimisation
sum(3, 4);                         // this call runs optimised code
console.log(%GetOptimizationStatus(sum));

%GetOptimizationStatus(fn) returns a bitmask you decode bit by bit. The bits you care about: is optimised, is turbofanned, is maglevved, is interpreted, marked for deoptimisation, is function, and never optimise (the function contains a construct V8 refuses to optimise). A value with the “optimised” and “turbofanned” bits set means it is running TurboFan code; if “marked for deoptimisation” is set, the next call will bail. Other intrinsics round out the kit: %HasFastProperties(obj) tells you whether an object is still in fast (non-dictionary) mode, and %DebugPrint(obj) dumps its full internal layout — the map pointer, the property values, and the array element kind (PACKED_SMI vs HOLEY, and so on).

Profiling the real app

The trace flags answer “why is this function slow”. To find which function is slow first, profile:

• node --prof writes an isolate-*.log of sampled stacks; node --prof-process isolate-*.log turns it into a human report with a ticks-by-function breakdown and a section that flags Ignition-vs-optimised time and GC time.
• node --cpu-prof writes a .cpuprofile you load straight into the Chrome DevTools Performance panel (or VS Code) for a flame graph — far easier to read than the text profile.

The discipline: profile first to find the dominant cost, then point --trace-deopt / --trace-ic at the function the profile blamed. Tracing the whole app blindly drowns you in lines.