Registry / observability / v8-profiler-next

v8-profiler-next

library1.10.0jsnpmunverified

v8-profiler-next provides native Node.js bindings for the V8 JavaScript engine's profiler, enabling developers to capture CPU profiles and heap snapshots of their Node.js applications. It is compatible with a wide range of Node.js versions, from v4.x through v21.x, and supports macOS, Linux, and Windows platforms. The package is currently at version 1.10.0 and receives regular updates, with minor releases approximately every few months, as indicated by its recent changelog. A key differentiator is its ability to operate within `worker_threads`, allowing for isolated profiling of worker contexts without blocking the main thread. It also offers the option to generate CPU profiles in a new format compatible with modern tools like VS Code and Chrome DevTools, which is crucial for streamlined analysis workflows.

observability devops

npm install v8-profiler-next

github ↗package ↗

INSTALL

IMPORT

SIG · V8-PROFILER-NEXT

v8-profiler-next

observabilityjavascriptv1.10.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

v8Profiler

✓ const v8Profiler = require('v8-profiler-next');

✗ import v8Profiler from 'v8-profiler-next';

This package is a CommonJS module. Use `require` for reliable import. While Node.js has ESM-CJS interop, direct `import` might not always behave as expected for `module.exports = {}` type exports.

Demonstrates how to start and stop CPU profiling, configure the output format, save the profile to a file, and release resources after export.

'use strict'; const fs = require('fs'); const v8Profiler = require('v8-profiler-next'); const title = 'my-app-cpu-profile'; // Set generateType 1 to generate the new format for cpuprofiles, // compatible with VS Code and Chrome DevTools parsing. v8Profiler.setGenerateType(1); console.log('Starting CPU profiling for 10 seconds...'); v8Profiler.startProfiling(title, true); setTimeout(() => { const profile = v8Profiler.stopProfiling(title); profile.export(function (error, result) { if (error) { console.error('Error exporting profile:', error); return; } const filename = `${title}.cpuprofile`; fs.writeFileSync(filename, result); console.log(`CPU profile saved to ${filename}.`); profile.delete(); // Important: delete the profile to free up memory console.log('To examine the profile:'); console.log(' 1. Navigate to chrome://inspect in Chrome.'); console.log(' 2. Click "Open dedicated DevTools for Node".'); console.log(' 3. Select the "Profiler" tab.'); console.log(' 4. Load your .cpuprofile file.'); }); }, 10 * 1000); // Profile for 10 seconds for this example

Debug

Known issues

gotchaWhen generating CPU profiles, calling `v8Profiler.setGenerateType(1)` is recommended to produce a format compatible with modern tools like VS Code and Chrome DevTools. Omitting this call may result in an older format that is less widely supported or parsed incorrectly.

fix

Ensure `v8Profiler.setGenerateType(1);` is called before `v8Profiler.startProfiling` for desired output format.

affects: >=1.0.0

gotchaAs a native Node.js addon, `v8-profiler-next` requires a C++ compiler and other build tools (like `node-gyp` dependencies) to be installed on the system where it is being installed. Installation can fail if these prerequisites are missing.

fix

Install build tools appropriate for your OS: `npm install --global windows-build-tools` (Windows) or `sudo apt-get install build-essential` / `xcode-select --install` (Linux/macOS).

affects: >=1.0.0

gotchaProfiling can be resource-intensive and may significantly impact the performance and memory usage of the application being profiled. It is generally not recommended for continuous use in production environments unless carefully managed and for specific diagnostic purposes.

fix

Use profiling in development/staging environments. Limit profiling duration and frequency. Monitor application performance closely during profiling sessions.

affects: >=1.0.0

gotchaAfter exporting a profile or snapshot, it is crucial to call `profile.delete()` or `snapshot.delete()` to free up the memory allocated by the V8 profiler for that specific profile. Failing to do so will lead to memory leaks within your Node.js process.

fix

Always call `.delete()` on the returned profile or snapshot object after you have finished processing and saving its data.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'v8-profiler-next'

The package failed to install correctly, or the build tools required for its native addon were missing during installation, preventing the module from being compiled and found.

fix

Run `npm rebuild v8-profiler-next` or `npm install` again. Ensure necessary build tools (like `node-gyp` dependencies) are installed on your system. Check npm logs for specific compilation errors.

gyp ERR! build error

Native addon compilation failed due to missing system build tools (e.g., C++ compiler, Python), incorrect `node-gyp` setup, or incompatibility with the installed Node.js version headers.

fix

Install required system build tools for `node-gyp` (see `node-gyp` documentation). Ensure your Node.js version is officially supported by the package. Consider using a Node.js version manager (e.g., `nvm`) to align with known compatible versions.

TypeError: v8Profiler.startProfiling is not a function

The `v8Profiler` object was not correctly loaded or initialized, possibly due to a failed native addon compilation, or an incorrect `import` statement in an ESM context that didn't resolve the CJS default export.

fix

Verify package installation and ensure `const v8Profiler = require('v8-profiler-next');` is used if operating in a CommonJS module. If using ESM, ensure proper ESM-CJS interop or consider using a bundler that handles CJS modules.

Upgrade

Version history

1.10.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hyj1991/v8-profiler-next ↗

packagehttps://www.npmjs.com/package/v8-profiler-next ↗