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

```bash
./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:**

```bash
./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`:

```bash
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

1. **Generate the log:** Run `d8` with the `--prof` flag.

   ```bash
   <path_to_d8> --prof <script.js>
   ```

   This generates a `v8.log` file.

2. **Analyze the log:** Run the appropriate script for your platform on the log
   file.

   ```bash
   ./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.