Looking inside the engine

A scanner for the JavaScript engine

An engine is the program that runs your JavaScript. Chrome and Node both use an engine called V8. While your code runs, V8 makes its own private choices. For example, it may build a faster version of a function that you call many times. The part of V8 that does this is called the JIT compiler (JIT means "just in time": it works while the program runs).

Normally you never see these choices, and that is good. Your program should depend only on what JavaScript promises, not on one engine's private choices. But when you study a speed problem, it helps to see what the engine did. A few V8 tools can show you that.

Most of these tools are flags. A flag is an extra word you type after a command, and it starts with two dashes. For example, in node --trace-opt file.js, the flag is --trace-opt. It asks Node to print notes about what V8 did.

Think of a scanner that a mechanic plugs into a car. The car drives the same way. The scanner only reports what is happening inside the engine.

This lesson follows Writing engine-friendly code. Next comes CPU profiling in depth, which shows where your program spends its time. These lessons explain the engine parts you will see here: bytecode and interpreters, tiered compilation, optimizing compilers, and speculation and deoptimization.

Start with a tiny hot function

Hot code is code that runs many times. The engine may spend extra work on hot code to make it faster. We start with a tiny hot function and its printed result, before we add any 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));

In plain words, line by line:

1. Line 1 makes a function called add.
2. Line 2 gives back the sum of its two inputs.
3. Line 5 calls add one thousand times with numbers. This is the warm-up: it makes add hot.
4. Line 6 calls add(2, 3) once more and prints 5.

The loop does not promise that V8 will make a faster version of add. It only gives us a small example that runs the same way every time. When you study the engine, change one thing at a time: the number of calls, the kind of values you pass, or the flag you use.

Always keep the last console.log. It shows what JavaScript itself says. If the printed result is wrong, the bug is in your program, not in the engine. If the result is right, any note from the engine is only about how V8 chose to run the code.

The step-through below is a model. Small helper functions such as warmUp and getStatus stand in for the real V8 tools, so you can see each step in order. You will meet the real tools later in this lesson.

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

A shell is a small program that runs your code from a terminal. d8 is V8's own shell. It runs a JavaScript file, prints with console.log, and accepts V8 flags. It shows V8 more directly than a browser page does. But it is not the browser your users run.

# d8 is V8's own shell. jsvu downloads recent engines.
npm install --global jsvu
jsvu

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

In plain words, line by line:

1. Line 1 is a comment.
2. Line 2 installs jsvu with npm, the tool that installs JavaScript packages.
3. Line 3 starts jsvu. It asks which engines you want and downloads them into the folder ~/.jsvu/bin.
4. Line 5 is a comment. PATH is the list of folders your terminal searches for programs.
5. Line 6 prints the version of the V8 shell that jsvu downloaded.
6. Line 7 runs file.js with that V8 shell.

jsvu stands for "JavaScript engine Version Updater". It gets you a recent V8 shell without building V8 yourself. Write down the engine version next to every result, because the notes an engine prints can change from one version to the next.

To see which flags your copy accepts, run d8 --help. A command copied from an older or newer V8 may be refused, may have a different name, or may print less. That is normal for these tools. It is one more reason to keep your test file next to your notes.

Trace optimization and deoptimization

Optimization means the engine builds a faster version of a function. It does this after it has watched the function run and has seen what kind of values it gets. For example, if add always gets numbers, V8 can build a fast version made only for numbers.

Deoptimization is the opposite step. The fast version only works for the values the engine expected. When a different kind of value arrives, the engine drops the fast version and goes back to the slower, general version that works for any value.

A trace is a list of notes that the engine prints while it works. Two flags turn on these notes.

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

// The words change between V8 versions. Node 22 / V8 12.4 prints:
// marking ... for optimization
// compiling method
// completed compiling
// bailout ... deoptimizing

Line 1 starts Node with two flags and runs file.js:

• --trace-opt prints a note when V8 builds a faster version of a function.
• --trace-deopt prints a note when V8 drops one.

Lines 3 to 7 are comments. They show words that Node 22 (with V8 12.4) prints, such as marking ... for optimization, compiling method, completed compiling, and bailout ... deoptimizing. Other V8 versions can use other words. So look for the name of your function, not for one exact phrase.

A trace note is a clue, not a final answer. First check that the function name and the values match your small test file. Then check whether the same thing happens when a real user is waiting. Do not change a whole app because one local trace looks busy.

Here is an example. A product list calls one price function with numbers while you scroll. Once, a bad server reply sends a string instead. A trace can tell you that V8 dropped its fast version at that moment. It cannot tell you what made the page slow. That could be the check on the server reply, drawing the list, the network, or the dropped fast version. A profile and a timed click answer that question; the next lesson covers profiles.

The step-through below shows a type change. It is a model: the helper optimizeOnNextCall stands in for a real V8 tool. The printed 21 is real JavaScript.

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));

Percent functions and status bits

V8 has some hidden functions whose names start with a percent sign, such as %GetOptimizationStatus. They are called V8 intrinsics. Here is what to know about them:

• They are not part of JavaScript. Browsers reject them.
• They only work when you start Node or d8 with the flag --allow-natives-syntax.
• Their names and what they return can change from one V8 version to the next.

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

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

In plain words, line by line:

1. Lines 1 to 3 make the same add function.
2. Line 5 tells V8 to start collecting notes about how add is used.
3. Line 6 calls add(1, 2), so V8 sees two numbers.
4. Line 7 asks V8 to build the faster version on the next call.
5. Line 8 is that next call, add(2, 3).
6. Line 9 asks V8 for a status number that describes add, and prints it.

The status number packs several yes-or-no facts into one number. Each fact is one bit: one binary digit that is either on or off. The bits are worth 1, 2, 4, 8, 16, and so on. For example, 17 is 16 + 1, so the bit worth 16 and the bit worth 1 are on, and all the others are off.

This lesson checks just one fact, on Node 22. After lines 5 to 8, the status always has the bit worth 16 turned on. We call that bit "optimized". This is not a promise from V8 that 16 always means this. We also do not decode the other bits.

To test one bit, use status & 16. The & operator keeps only the bits that are on in both numbers. If the answer is 16, that bit is on. If it is 0, the bit is off. The & is ordinary JavaScript. The meaning "16 is optimized" comes only from our test on one V8 version.

Model a status decoder

A decoder turns a status number into words. The playground below is a model of that. It does not look inside your browser's engine. It gives the same answer every time, so you can compare choices. You can turn three things on or off:

• the warm-up calls with numbers,
• the request to build a faster version on the next call,
• a later call with a string.

Turn one choice on or off. Then read the status and the trace note that the model prints. With the first two choices on, the status is 17, which has the bit worth 16 on. When a string arrives later, + joins text instead of adding, and the model prints a note about dropping the fast version.

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);

Log viewers: Indicium and Deopt Explorer

Trace notes are accurate, but there can be thousands of them. A log file is a file where the engine saves its notes instead of printing them. Two tools draw log files as pictures and lists you can click through:

• Indicium, a log viewer made by the V8 team.
• Deopt Explorer, an extension for the VS Code editor, made by Microsoft.

Use them only after you have a small test file and know which function you are looking for.

# Save V8 notes to log files while you study a small test file.
node --log-ic --log-maps --log-deopt file.js
node --prof file.js

# Open the log in a viewer such as Indicium or Deopt Explorer.
# A viewer helps you look through the notes. It does not change the program.

In plain words, line by line:

1. Line 1 is a comment.
2. Line 2 saves three kinds of notes: --log-ic for how property reads went, --log-maps for object shapes, and --log-deopt for dropped fast versions.
3. Line 3 uses --prof to save a log of where time was spent.
4. Lines 5 and 6 are comments: you open the log in a viewer, and the viewer does not change your program.

These flags only record what happened in one run. A viewer helps you move around those notes. Neither one proves that a note is the reason a page felt slow.

Open the log in a viewer that reads that kind of file. Show only the function from your test file, then go back to your source code. A picture is easier to scan than text. But you still need three things: the values you passed, the note the engine printed, and a slowdown you can measure.

When a viewer shows many notes, start small. Search for add, or the function from your test file. Find the call where the values changed, and look at the notes around it. A colorful timeline is not a list of things to rewrite. It only makes the notes easier to move through.

Print bytecode

Before V8 runs a function, it turns your source code into bytecode: a list of small, simple steps. A part of V8 called the interpreter then runs those steps one by one. Printing the bytecode shows you those steps. It does not promise that every call runs exactly these steps, because a faster version may take over later.

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

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

Line 1 makes add. Line 2 adds the two inputs. Line 5 calls it and prints 5. The function is tiny on purpose, so each bytecode step is easy to match to the source.

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

// The numbers in this output change between V8 versions. These step names
// stay the same for this tiny function:
// Ldar a1
// Add a0, [0]
// Return

Line 1 has two flags. --print-bytecode prints bytecode, and --print-bytecode-filter=add keeps only the bytecode for add. The lesson test runs this on Node 22 and checks that the output has Add and Return. It also has Ldar, but other numbers in the listing can change between versions.

Read the three steps of the listing in order:

1. Ldar a1 picks up b, the second input, and holds it ready. In bytecode, a0 is the first input, a, and a1 is the second, b.
2. Add a0, [0] adds a to it. The [0] is a slot where V8 keeps notes about what kinds of values it has seen.
3. Return gives the sum back to the caller.

Print machine code carefully

You can go one level lower than bytecode. V8 can print the machine code of a faster version: the instructions the computer's processor runs directly. This output is long, different for every V8 version, and full of details that teach you nothing about JavaScript itself.

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

// This prints a lot of low-level output. Its layout and memory addresses
// change between Node and V8 versions, so don't copy it into tests.

Line 1 prints the machine code, but only for add. Lines 3 and 4 are comments that warn you: the layout and the memory addresses change from one Node version to the next.

Read this output only after you understand the source, the bytecode, and the trace. Compare it only with output from the same run. Do not compare memory addresses, and do not paste your output into notes as if every computer prints the same thing.

For most app work, bytecode, trace notes, and a CPU profile are better first tools. Print machine code only when you have one narrow question that it can answer.

A simple rule helps. If you cannot say what question about your source code the machine code will answer, do not print it yet. A trace may already show that the engine dropped a fast version. A profile may show that the function is not even slow. Low-level output is worth reading only when it helps you make a real choice.

Steps for studying a slow spot

Start from something a user can notice, such as a slow search or a list that stutters while scrolling. Then follow these steps:

1. Measure how long the slow part takes.
2. Copy just the code you suspect into a small file. This small file is called a reproduction: it shows the same problem on its own.
3. Run it with one flag. Write down the engine version and what the trace actually said.
4. Compare what you found with the real slowdown.

The table lists the tools from this lesson. Read each row as: the tool, what it is, and the first question it can help you answer.

Next, change one input. For example, call add with numbers, and then once with a string. If a trace note appears, compare it with a profile or with a real click. At the end, take the flags out. Keep your app code simple, unless a measurement shows that a change really makes it faster.

Also write down when nothing happened. "No trace note appeared for this input on this engine" is useful, because it stops you from trying the same guess again. Keep these together:

• the test file,
• the full command you ran,
• the engine version,
• the values you passed, in order,
• the printed result,
• the slowdown you measured.

That record is worth more than a single screenshot of a log.

Common mistakes

• "A trace flag makes my app faster." It only prints notes about what the engine did. Printing them can even slow the program down.
• "Dropping a fast version is always bad." It can be the normal thing to do when the values change.
• "A status number means the same thing everywhere." Its meaning can change from one V8 version to the next.
• "Bytecode is how the code always runs." During a run, the engine can switch to a faster version, or back again.

The table below lists things you may see. Read each row as: what you saw, what it tells you, and what it does not tell you.

Remember the main rule. JavaScript must always give the same results: what your program prints, returns, throws, and changes. The engine may run your code in different ways inside, but it must keep those results the same.

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

The quiz asks you to tell plain JavaScript results apart from V8 notes that can change between versions.

Key takeaways

• d8 is V8's own shell, and jsvu downloads recent engines for you.
• --trace-opt and --trace-deopt print notes when V8 builds or drops a faster version. Use them on a small test file.
• Percent functions need --allow-natives-syntax, and they can change with each V8 version.
• Indicium and Deopt Explorer help you look through V8 log files.
• Bytecode and machine code printouts are clues from one version, not rules that hold everywhere.
• Use engine flags only to learn and to study problems. Never turn them on for real users.

Coming next: CPU profiling in depth, which shows where your program spends its time.