JS Perf Investigation

SpiderMonkey Performance Investigation

This skill guides a structured, evidence-driven performance investigation for the SpiderMonkey JavaScript engine. The methodology has four phases: hypothesis generation, evidence gathering, patch writing, and evaluation. Each phase builds on the last: resist the urge to skip ahead to writing patches before you have empirical evidence that a change will help.

When asked to create multiple patches, iterate through the phases each time to ensure each patch is independently validated and measured. Always create commits before moving onto a new patch if you are creating multiple patches. This will make it easier to review and to measure contribution.

The end result of this skill will be a summary of the investigation, and one or more patches that measurably improve the performance of the targeted workload, with each patch describing supporting evidence and measured impact.

Prerequisites

The user should provide:

• A workload to investigate (a JS file, benchmark suite, or instructions to reproduce)
• A build configuration or existing shell to use

You have access to:

• samply — sampling profiler that produces Firefox Profiler-compatible output
• profiler-cli — for analyzing profiles. This can also be used to investigate Gecko profiler profiles if the investigation is being done in the browser.
• searchfox-cli — source code search for the Firefox codebase

For more details on how to use these tools load the "profiler-analysis" skill, which will also hint on how to get the tools installed if needed.

An artifacts/ directory can be created and this is excluded from version control.

Phase 1: Hypothesis Generation

The goal is to identify where time is being spent and form testable hypotheses about what could be improved.

1.1 Prepare the build

Use an opt-nodebug (optimized, no debug checks) build. Debug builds distort profiles with assertion overhead.

The user should provide or confirm the mozconfig to use. The key settings for an opt-nodebug build are:

ac_add_options --enable-optimize
ac_add_options --disable-debug

If the user hasn't specified a mozconfig, ask them — build configurations vary across machines and the user will know which obj-dir and config is appropriate for their setup.

Always run the shell with --strict-benchmark-mode when investigating performance. This flag validates the runtimeconfiguration and will error if something would produce unreliable numbers (e.g. JIT is disabled unexpectedly). Generating profiles without this flag risks producing misleading data.

1.2 Establish the workload

Examine the workload to understand what it does. If the workload has an iteration count or loop parameter, determine an appropriate count so that the workload runs for at least 30 seconds under profiling. Statistical profilers need sufficient samples to produce meaningful data — short runs produce noisy profiles where real hotspots are hard to distinguish from sampling noise.

For targeted micro-optimizations (e.g. improving a single opcode or a specific stub), longer runs (60s+) may be necessary to accumulate enough samples in the specific code path of interest.

If the workload driver supports iteration configuration, prefer that.

Otherwise, wrap it:

for (let i = 0; i < ITERATIONS; i++) {
    load("workload.js");  // or call the main function
}

1.3 Profile

Record a profile with samply. Always set IONPERF=func and PERF_SPEW_DIR so that JIT-compiled functions appear with readable names in the profile instead of raw addresses. The overhead is negligible:

mkdir -p artifacts/perf-spew
PERF_SPEW_DIR=artifacts/perf-spew IONPERF=func \
    samply record --save-only -o artifacts/profile.json.gz -- \
    ./obj-opt-nodebug/dist/bin/js --strict-benchmark-mode workload.js

Using --save-only avoids opening the browser and gives you a local file you can analyze with profiler-cli. Save profiles to the artifacts/ directory; you may need to gzip the profile for profiler-cli to read it.

For deeper JIT investigation (e.g. understanding what IR the JIT emitted for a hot function), use IONPERF=ir instead — see references/advanced-tools.md.

1.4 Analyze the profile

Start broad and narrow down: Looking at the profile, answer some of the following questionsfile:

1. What are the top CPU consumers?
2. What does the call tree look like top-down?
3. Who calls a hot function?
4. What does a specific function's time look like with callees collapsed?

For Speedometer profiles, always use --focus-marker="-async,-sync" to exclude async idle time between benchmark iterations.

1.5 Form hypotheses

Based on the profile data, form specific, testable hypotheses. Good hypotheses look like:

• "Function X is called Y times from path Z — reducing call frequency by caching result W should save ~N% of its self time"
• "The JIT is spending M% of time in IC stubs for property access pattern P — a specialized stub for this pattern could reduce that"
• "Allocation pressure in function F is causing N% GC time — pretenuring could help"

Bad hypotheses (avoid these):

• "Let's tune the inlining threshold" — tuning existing knobs tends to overfit to the current benchmark state rather than making general engine progress
• "This function seems slow, let's rewrite it" — without understanding why it's slow

Phase 2: Evidence Gathering

Before writing a patch, gather enough evidence to be confident the hypothesis is sound.

2.1 Source investigation

Use searchfox-cli to understand the relevant code and understand the current behavior.

Use searchfox-cli for blame on relevant code, as well as git history on relevant files. This might provide context on why things are the way they are.

2.2 Instrumentation

Profiling shows where time is spent but not always why. When your hypothesis depends on runtime state (data distributions, cache hit rates, list lengths, frequency of code paths), add temporary instrumentation to measure it directly.

Use MOZ_LOG or JS_LOG for instrumentation.

JS_LOG(debug /* you can also add your own channel, but debug should be unused */, Debug, "list length: %zu, sorted: %s",
           list.length(), isSorted ? "yes" : "no");

Throttle instrumentation output when it would fire on every iteration — use a counter to log every Nth occurrence, or accumulate statistics and log a summary. Unthrottled logging in a hot path will drown the output and slow the workload enough to distort measurements.

static uint32_t callCount = 0;
if (++callCount % 10000 == 0) {
    JS_LOG_FMT(debug, Debug, "after %u calls: avg length = %zu",
               callCount, totalLength / callCount);
}

Re run with MOZ_LOG=debug:5 to see the output.

In a browser build you can add profiler markers instead of logging which can be read through gecko-profiling and the profiler-cli.

2.3 Re-run with instrumentation

Run the instrumented build and collect the data. This confirms whether your hypothesis about runtime behavior is correct before you invest in writing a real patch.

Phase 3: Patch Writing

Now that you have evidence, write the patch.

3.1 Design for measurability

Where possible, gate the optimization behind a JS::Prefs preference so you can do apples-to-apples comparison on the same binary. This eliminates build-to-build variation as a confounding factor and makes it trivial to re-measure later.

To add the pref, add an entry to StaticPrefList.yaml:

- name: javascript.options.experimental.my_optimization
  type: bool
  value: true
  mirror: always
  set_spidermonkey_pref: always

Then guard the code path:

if (JS::Prefs::experimental_my_optimization()) {
    // new path (default: on)
} else {
    // old path
}

Use set_spidermonkey_pref: always (not startup) so the pref can be toggled via --setpref without requiring a restart:

# Measure with optimization (default):
./js --strict-benchmark-mode workload.js
# Measure without:
./js --strict-benchmark-mode --setpref experimental.my_optimization=false workload.js

Note that pref-gating is not always feasible. For changes on extremely hot paths (tight JIT loops, inline caches), the branch on the pref check itself can be costly enough to distort measurements. In those cases, fall back to saving the obj-dir from a build without the patch and comparing against a build with the patch applied.

Note: You can't save -just- a js binary, as there are dynamically linked libraries. Always save the obj-dir, or create a different mozconfig.

3.2 Add development logging

During patch development, add JS_LOG logging to the debug channel to verify the new code path is being taken where expected. Throttle by a counter to avoid flooding output. Do a run with the instrumentation logging to ensure the logging fires when/where/as-much as expected. Remove or reduce this logging before the patch is finalized.