Looking inside the engine

A scanner for the JavaScript engine

JavaScript normally hides the engine's internal choices. That is good: your program should depend on language behavior, not on one JIT compiler. When performance work needs evidence, a few V8 tools show what one run decided.

Think of a car's diagnostic scanner plugged into its dashboard port. The car drives the same, but the scanner shows which parts are warm and when it switches gears. Engine flags are that scanner for JavaScript: useful evidence, not controls that make the engine permanently better.

This lesson follows Writing engine-friendly code. It prepares you for CPU profiling in depth, where a profile answers where time went. Related lessons explain bytecode and interpreters, tiered compilation, optimizing compilers, and speculation and deoptimization.

Start with a tiny hot function

Hot code is code that runs often enough that an engine may spend extra work trying to run it efficiently. Start with a visible result before adding any engine flag.

1function add(a, b) {2  return a + b;3}4 5for (let index = 0; index < 1000; index += 1) add(index, 1);6console.log(add(2, 3));

Line 1 declares add. Line 2 returns the sum. Line 5 calls it one thousand times with numbers, which is our simple warm-up. Line 6 calls it once more with 2 and 3, so the real output is 5.

The loop does not guarantee that any specific V8 version optimizes add. It simply makes a small repeatable example. A useful investigation changes one thing at a time: calls, argument types, or the flags used to observe it.

Keep the final console.log even when an experiment becomes more advanced. It gives you a language-level anchor. If a trace changes but the output becomes wrong, investigate the JavaScript program first. If the output stays correct, the trace describes a possible implementation choice rather than a new language rule.

1function add(a, b) {Run2  return a + b;3}4 5warmUp(add);6prepare(add);7optimizeOnNextCall(add);8const result = add(2, 3);9const status = getStatus(add);10console.log(result, status);

d8 and jsvu

d8 is V8's developer shell. It can run a file, print with console.log, load another script, and accept flags. It is a closer V8 observation tool than a browser page, but it is not the browser your users run.

# d8 is V8's developer shell. jsvu downloads recent engine builds.
npm install --global jsvu
jsvu

# Add ~/.jsvu/bin to your PATH, then run the V8 shell it installed.
~/.jsvu/bin/v8 --version
~/.jsvu/bin/v8 file.js

The first command installs the updater. The second command chooses engines interactively. jsvu downloads selected builds into ~/.jsvu/bin; after adding that folder to your path, the last line runs its V8 binary on file.js.

jsvu means JavaScript engine version updater. It is helpful when you need a recent V8 shell without compiling V8 from source. Use a local copy for investigation, then record the engine family beside your result because output can change across versions.

Use d8 --help or the downloaded shell's help output to see what that build accepts. A command copied from a different V8 revision can be rejected, renamed, or report a different amount of detail. That is normal for diagnostic tooling and another reason to keep a reproduction file beside notes from an investigation.

Trace optimization and deoptimization

Optimization is an engine choosing a faster implementation after collecting useful feedback. Deoptimization is an engine returning from an optimized assumption to a more general path when that assumption no longer fits.

node --trace-opt --trace-deopt file.js

// Trace words vary in their surrounding details. Look for:
// optimizing
// completed optimizing
// bailout
// deoptimizing

The command starts Node with both trace flags and runs file.js. The stable words to look for are optimizing, completed optimizing, bailout, and deoptimizing. The surrounding addresses, timings, and formatting are not stable facts.

A trace line is a question, not a verdict. Match the function name and the input sequence to your small reproduction. Then decide whether the event occurs in the real slow interaction. Do not tune a full application because one local trace is noisy.

For example, a product list may call one formatter with numbers during normal scrolling and once with a string from an unvalidated API response. A trace can tell you that the engine changed its path. It cannot tell you whether validation, list rendering, network work, or the changed path is the important user-facing cost. A profile and a measured interaction answer that later question.

1function add(a, b) {Run2  return a + b;3}4 5add(2, 3);6add(4, 5);7optimizeOnNextCall(add);8add(6, 7);9console.log(add("2", 1));

Native syntax and status bits

V8 intrinsics are percent-prefixed diagnostic functions exposed only when V8 permits its native syntax. They are not standard JavaScript. They only work with --allow-natives-syntax, and their names and meanings can change between V8 versions.

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

%PrepareFunctionForOptimization(add);
add(1, 2);
%OptimizeFunctionOnNextCall(add);
add(2, 3);
console.log(%GetOptimizationStatus(add));

Line 5 prepares add for this diagnostic experiment. Line 7 asks V8 to optimize the next call. Line 8 supplies that call. Line 9 prints a status number. Treat the number as bit flags: each bit can represent a property, but decode only bits you verified for your own engine.

This lesson verifies one narrow fact in Node 22's V8 family: after prepare, request, and call, the returned status has the lesson's optimized bit, 16, set. It does not claim that 16 is a permanent public V8 contract or decode the rest of the number.

A bit flag is a number whose binary digits are separate on-or-off pieces of information. The model uses status & 16 to ask whether the 16 bit is present. That operation is ordinary JavaScript, but choosing what the bit means comes from a specific diagnostic experiment. Keep those two ideas separate.

Model a status decoder

The playground turns one status number into labels. It lets you change warm-up calls, an optimize-on-next-call request, and a later type change. The output is deliberately modeled so every state is readable and repeatable in the browser.

Toggle one choice, read the modeled status, then compare the matching trace line. Number calls lead to status 17 in this model, where 17 includes bit 16. A later string makes + concatenate and gives a modeled deoptimization line.

1function add(a, b) {2  return a + b;3}4 5warmUp(add);6prepare(add);7optimizeOnNextCall(add);8const result = add(2, 3);9const status = getStatus(add);10console.log(result, status);

Indicium and Deopt Explorer

Text logs are honest but long. Indicium and the Microsoft Deopt Explorer VS Code extension are visual tools for exploring V8 log files. Use them after you have a small reproduction and know which function or interaction you are looking for.

# Produce V8 log files while investigating a small reproduction.
node --log-ic --log-maps --log-deopt file.js
node --prof file.js

# Open the produced log in a visual tool such as Indicium or Deopt Explorer.
# Visualizers help explore evidence; they do not change the program.

The first command requests inline-cache, map, and deoptimization logging. The second requests a V8 profiler log. These flags create evidence from a run; a visualizer helps you navigate that evidence. It does not prove that a specific event caused a user-visible slowdown.

Open the produced log with the tool that supports its format, filter to the function you reproduced, and return to source code. A visual display is easier to scan, but the investigation still needs an input, an observed event, and a measurable user effect.

Start narrow when a visualizer has many events. Search for add or the function from your reproduction, note the call that changed its input, and compare nearby events. Do not begin by treating a colorful timeline as a ranking of what to rewrite. Its job is to make raw evidence navigable.

Print bytecode

Bytecode is a compact instruction format an interpreter can execute. Printing it is a way to see that your source became operations, not a promise that every run uses exactly those instructions.

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

console.log(add(2, 3));

Line 1 declares add. Line 2 performs addition. Line 5 calls it and prints 5. Keeping the function this small makes the bytecode output easier to connect to source.

node --print-bytecode --print-bytecode-filter=add file.js

// Bytecode has engine-version-specific offsets. These opcode names are stable
// evidence for this tiny function:
// Ldar a1
// Add a0, [0]
// Return

The filter asks Node to print the bytecode for add. The lesson test verifies real output contains Add and Return. It also shows Ldar on the current Node 22 family, but offsets and register details may vary.

Read the listing from source outward. A load such as Ldar gets a value ready, Add combines the operands, and Return sends the result back to the caller. This is useful because it makes the interpreter concrete, but it is still not a promise that an optimized tier will execute the same listing for every call.

Print optimized code carefully

Optimized-code printing goes one level lower than bytecode. It can show compiler output for a chosen function, but it is dense, build-specific, and often contains machine-level details that do not teach JavaScript semantics.

node --print-opt-code --print-opt-code-filter=add file.js

// This is a diagnostic dump. The format, addresses, and assembly vary by
// Node and V8 build, so compare ideas rather than copying output into tests.

The command filters a dump to add. Read it only after you understand the source, bytecode, and trace. Compare the compiler's decisions within the same experiment; do not compare addresses or paste a local dump into documentation as a universal result.

For most application work, bytecode, trace lines, and a CPU profile are better first tools. Optimized-code printing is for a focused question where the lower-level output can actually change your next measurement.

There is a practical stopping rule: if you cannot describe what source-level question a machine-code dump will answer, do not print it yet. A simple trace may already show the changed assumption. A profile may show that the function is not even on the costly path. Low-level output earns its complexity only when it narrows a real decision.

A careful investigation workflow

Start from a user-visible question, such as a slow search result or a stuttering list. Measure it first. Then make the smallest file that shows the same input pattern, run one flag, and write down what the engine version and trace actually said.

Next, change one input. For example, call add with numbers, then once with a string. If a trace line appears, compare that event to a profile or a real interaction. Finally, remove flags and keep the production code clear unless measurement shows a meaningful improvement.

Write down negative results too. “No trace event appeared for this input on this engine” is useful evidence because it prevents you from repeating the same guess later. Keep the source file, full command, engine version family, input sequence, visible output, and measured symptom together. That record is more valuable than an isolated screenshot of a log.

Common mistakes

• “A trace flag makes production faster.” It reports internal events and can add output overhead.
• “A deoptimization is always bad.” It can be a normal fallback when inputs become more general.
• “A status value is portable.” It is a version-sensitive V8 diagnostic detail.
• “Bytecode is the final execution.” An engine can tier, optimize, or fall back during a run.

Keep the ordinary contract in front: JavaScript must keep the same observable language behavior. The engine can choose different internal paths while preserving what your program prints, returns, throws, and updates.

Practice exercises

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

for (let index = 0; index < 1000; index += 1) add(index, 1);
console.log(add(2, 3));

function add(a, b) { return a + b; }
console.log(add(2, 3));
console.log(add("2", 1));

Check your understanding

Use the quiz to separate normal JavaScript behavior from version-sensitive V8 diagnostics.

Key takeaways

• d8 is V8's developer shell, and jsvu can download recent engine builds.
• Trace flags expose optimization and fallback events for a small reproduction.
• Percent intrinsics need --allow-natives-syntax and can change with V8.
• Indicium and Deopt Explorer help explore V8 log evidence.
• Bytecode and optimized-code dumps are diagnostics, not portable contracts.
• Keep all engine flags for learning and investigation, not production.

Coming next: CPU profiling in depth.