pprof for Node.js

Install the pprof package and save it to your local package.json using npm.

npm install --save pprof

Before using pprof, ensure your environment meets the following requirements:

1. Node.js Version: Your application must use Node.js 18 or greater (tested on 18, 20, and 22).
2. Build Dependencies: The package contains a native component that is compiled during installation using node-gyp. You must have the necessary build dependencies for node-gyp installed on your platform.
3. pprof CLI: To view the profiles collected by this module, you must have the pprof command-line tool installed on your system.

Heap profiling requires a two-step process: enabling the profiler at application startup and then triggering the collection of profiles.

// 1. Enable heap profiling at the start of the application
// The average number of bytes between samples.
const intervalBytes = 512 * 1024;

// The maximum stack depth for samples collected.
const stackDepth = 64;

heap.start(intervalBytes, stackDepth); 

// 2. Collect and save a profile in profile.proto format
const profile = await pprof.heap.profile();
const buf = await pprof.encode(profile);
fs.writeFile('heap.pb.gz', buf, (err) => {
  if (err) throw err;
});

If the module is loaded via the Node.js --require flag (specifically when the parent module is internal/preload), the profiler starts automatically. Upon process exit, it synchronously captures the time profile, encodes it, and writes it to a file named pprof-profile-<process.pid>.pb.gz.

node --require pprof-nodejs your-app.js

You can collect a wall time profile for an entire process execution without modifying your source code by requiring pprof at startup. This will automatically save a profile file named pprof-profile-${process.pid}.pb.gz.

# Start program from the command line
node --require pprof app.js

# View the profile (replace ${process.pid} with the actual PID)
pprof -http=: pprof-profile-${process.pid}.pb.gz

To collect a wall time profile programmatically, use pprof.time.profile() to specify the collection duration, then use pprof.encode() to convert the profile into a buffer suitable for saving to a file.

const profile = await pprof.time.profile({
  durationMillis: 10000,    // time in milliseconds for which to 
                           // collect profile.
});
const buf = await pprof.encode(profile);
fs.writeFile('wall.pb.gz', buf, (err) => {
  if (err) throw err;
});

If you require a heap profile in the V8 allocation profile format instead of the standard profile.proto format, use the pprof.heap.v8Profile() method.

const profile = await pprof.heap.v8Profile();

Once a profile (wall time or heap) has been saved as a .pb.gz file, use the pprof command-line tool with the -http flag to view it in a web browser.

# For a wall time profile
pprof -http=: wall.pb.gz

# For a heap profile
pprof -http=: heap.pb.gz

The heap object provides methods for memory profiling. Use heap.start() to begin profiling, heap.stop() to end the session, and heap.profile() to get the profile. Additionally, heap.v8Profile() is available to access the raw V8 heap profile.

import { heap } from 'pprof-nodejs';

heap.start();
// ... perform work ...
const profile = heap.stop();
// or
const v8Profile = heap.v8Profile();

The v8Profile function returns the current heap profile in the raw V8 allocation profile format (AllocationProfileNode).

Note: This function will throw an error if the heap profiler has not been enabled via start().

import { v8Profile } from 'pprof';

const v8Data = v8Profile();

Use the stop function to disable heap profiling. If the profiler has not been started, calling stop does nothing.

import { stop } from 'pprof';

stop();

The library provides encoding utilities to convert profile data into the required format. encode is available for asynchronous encoding, while encodeSync performs synchronous encoding.

import { encodeSync } from 'pprof-nodejs';

const buffer = encodeSync(profile);