v8-log - SKILL.md Agent Skill

name: v8_log description: Understanding v8.log files.

V8 Log Viewer CLI

A standalone command-line tool for analyzing v8.log files. It allows you to inspect internal state of the V8 JavaScript engine.

Requirements

This tool requires the V8 shell (d8) to be installed and accessible. If no local d8 build is available it will try to call back to jsvu's d8 in ~/.jsvu/bin/v8. You can override this by setting the V8_PATH environment variable.

Available Commands

Use the following commands to inspect different aspects of the log. Each command focuses on a specific type of event or structure in the V8 execution profile:

stats Prints aggregated statistics of all events found in the log. Use this to get a quick high-level overview of the log content (e.g., total number of scripts, functions, ICs, and deopts).
ic Lists detailed information about Inline Cache (IC) events. ICs are used by V8 to optimize property accesses based on type feedback. Use this to find polymorphic or megamorphic IC misses that might be causing performance bottlenecks.
script Lists all scripts loaded by V8. Use this to find script IDs for specific source files or to inspect the size of loaded assets.
code Lists all code objects created by V8 (e.g., full code, bytecode, stub handlers). Use this to inspect the generated code entries and their size for specific functions or builtins.
function Lists all compiled functions tracked by V8 and their variants. A function can have multiple compilation variants (e.g., unoptimized bytecode and optimized machine code). Use this to see how many times a function was compiled and at what optimization tiers.
deopt Lists all deoptimizations that occurred. Deoptimizations happen when V8's optimistic assumptions are violated, forcing it to fall back to less optimized code. Use this to find performance cliffs caused by deopts and understand why they happened (e.g., insufficient type feedback).

Usage & Help

To see the full list of common options and specific filter options for any subcommand, rely on the tool's built-in help system:

./tools/v8-logviewer --help

To see specific help, detailed descriptions, and command-specific filter options for any subcommand, run:

./tools/v8-logviewer <command> --help

Logging Flags

To generate a v8.log with specific information, you must pass diagnostic flags to d8 when running your script.

Here are the most common flags to enable specific log events:

--prof Enables execution profiling (ticks). This is required for stats and general profiling analysis.
--log-ic (slow) Logs Inline Cache (IC) events. Required for the ic command.
--log-deopt Logs deoptimizations. Required for the deopt command.
--log-maps (slow) Logs map creation and modification events.
--log-code Logs code events to the log file without profiling. Useful for the code command.
--log-code-disassemble Logs all disassembled code to the log file.
--log-source-code Logs source code information.
--log-all Enables all logging (very verbose!). Use with caution.

Example:

out/release/d8 --log-all my-script.js

This will generate a large v8.log file. It is recommended to use a more targeted set of flags when possible.

Examples

List the 10 largest script summaries to see which ones are interesting:

./tools/v8-logviewer script v8.log --sort=size --limit=10

List details for a specific script id:

./tools/v8-logviewer script v8.log --script-id=170 --details

List all functions details for a specific script:

./tools/v8-logviewer function v8.log --script=example.js

List the last 5 deoptimizations:

./tools/v8-logviewer deopt v8.log --limit=-5

Find all optimized code objects for a specific function:

./tools/v8-logviewer code v8.log --function=myFunction --code-kind=Opt

Count how many IC events happened in a specific time window:

./tools/v8-logviewer ic v8.log --time=500000..600000 --count