README.md

pprof support for Node.js

pprof support for Node.js.

Prerequisites

1. Your application will need to be using Node.js 16 or greater.

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

   • pprof has prebuilt binaries available for Linux arm64/x64, Alpine Linux x64, macOS arm64/x64, and Windows x64 for Node 16/18/20/22/23. No additional dependencies are required.
   • For other environments: on environments that pprof does not have prebuilt binaries for, the module node-gyp will be used to build binaries. See node-gyp's documentation for information on dependencies required to build binaries with node-gyp.

3. The pprof CLI can be used to view profiles collected with this module. Instructions for installing the pprof 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 @datadog/pprof

Using the Profiler

Collect a Wall Time Profile

In code:

1. 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;
   });

2. View the profile with command line pprof:

   pprof -http=: wall.pb.gz

Requiring from the command line

1. Start program from the command line:

   node --require @datadog/pprof app.js

2. A wall time profile for the job will be saved in pprof-profile-${process.pid}.pb.gz. View the profile with command line pprof:

   pprof -http=: pprof-profile-${process.pid}.pb.gz

Collect a Heap Profile

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 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();