v8-profile - SKILL.md Agent Skill

name: v8-profile description: Profiling V8 execution.

V8 Profiling

This skill explains how to profile V8 execution using native tools to understand where time is spent. Make sure to only profile on a quiet system to get the best results.

Linux Profiling

On Linux, prefer using the ./tools/profiling/linux-perf-d8.py script. This script automates the process of running Linux perf with V8, and critically, it runs perf inject --jit afterwards to ensure that JIT-compiled JavaScript function names are resolved in the profile.

Usage

./tools/profiling/linux-perf-d8.py [OPTIONS] <path_to_d8> [D8_OPTIONS] <script.js> [-- <script_args>]

Use the --help option and docs/linux-perf.md for further information.

Example:

./tools/profiling/linux-perf-d8.py out/release/d8 harness.js -- core.js data.json

The script will generate a .perf.data.jitted file in the output directory (defaults to current directory or specified by --perf-data-dir).

If you get too few ticks, you can run a script multiple times and combine all the profiles using pprof.

Analysis

To view the report, use perf report:

perf report --stdio -i path/to/file.perf.data.jitted

Other Platforms (or fallback)

For all other platforms, or when perf is not available, use the platform-specific tick processor script in ./tools/. These tools analyze the v8.log file generated by V8's built-in profiler.

Available Scripts

Linux: ./tools/linux-tick-processor
macOS: ./tools/mac-tick-processor
Windows: ./tools/windows-tick-processor.bat
FreeBSD: ./tools/freebsd-tick-processor

Usage

Generate the log: Run d8 with the --prof flag.
```
<path_to_d8> --prof <script.js>
```
This generates a v8.log file.
Analyze the log: Run the appropriate script for your platform on the log file.
```
./tools/linux-tick-processor v8.log
```

Performance Warning

CRITICAL: Do NOT use heavy logging flags (like --trace-ic, --trace-deopt, --trace-gc) in parallel with profiling unless explicitly investigating those specific events. Heavy logging significantly affects performance and will distort the profile results, leading to inaccurate conclusions about where time is spent in normal execution.