pprof support for Node.js
pprof support for Node.js.
Prerequisites
-
Your application will need to be using Node.js 14 or greater. This package is tested against current versions of Node.js: 14, 16, 18, and 20.
-
The
pprof
module has a native component that is used to collect profiles with v8's CPU and Heap profilers. You may need to install additional dependencies to build this module.- For Linux:
pprof
has prebuilt binaries available for Linux and Alpine Linux for Node 14 and 16. No additional dependencies are required. - For other environments: when using
@google-cloud/profiler
on environments thatpprof
does not have prebuilt binaries for, the modulenode-gyp
will be used to build binaries. Seenode-gyp
's documentation for information on dependencies required to build binaries withnode-gyp
.
- For Linux:
-
The
pprof
CLI can be used to view profiles collected with this module. Instructions for installing thepprof
CLI can be found here.
Basic Set-up
Install pprof
with npm
or add to your package.json
.
# Install through npm while saving to the local 'package.json'
npm install --save pprof
Using the Profiler
Collect a Wall Time Profile
In code:
-
Update code to collect and save a profile:
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; });
-
View the profile with command line
pprof
:pprof -http=: wall.pb.gz
Requiring from the command line
-
Start program from the command line:
node --require pprof app.js
-
A wall time profile for the job will be saved in
pprof-profile-${process.pid}.pb.gz
. View the profile with command linepprof
:pprof -http=: pprof-profile-${process.pid}.pb.gz
Collect a Heap Profile
-
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);
-
Collect heap profiles:
-
Collecting and saving 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; })
-
View the profile with command line
pprof
.pprof -http=: heap.pb.gz
-
Collecting a heap profile with V8 allocation profile format:
const profile = await pprof.heap.v8Profile();
-