jakebailey/pprof-it

A handy pprof wrapper for NodeJS

pprof-it

pprof-it is a convenient wrapper to pprof that makes it easy to capture CPU and memory profiles of node programs.

(Technically, pprof-it uses DataDog's fork of pprof-node, as it supports newer versions of node and includes prebuilds for many more platforms.)

Usage

To use pprof-it, use pprof-it in place of node:

$ npx pprof-it path/to/script.js

Or, ensure node is run with --require=pprof-it:

# Directly running with node
$ node --require pprof-it path/to/script.js

# Executables via npm/npx (v7+)
$ npx --node-option="--require pprof-it" <executable name>
$ npm exec --node-option="--require pprof-it" <executable name>

# Executables via npm/npx (v6)
$ npx --node-arg="--require pprof-it" <executable name>

# Executables via yarn (usually)
$ node --require pprof-it $(yarn bin <executable name>)

The NODE_OPTIONS environment variable may be used to pass --require, but is not recommended as more than one process may emit profiles.

By default, pprof-it will produce both heap and time profiles and write them to the current directory.

To view the profiles, you can use SpeedScope for a quick and easy view, or use the pprof utility for more info, like:

# CLI interface
$ go run github.com/google/pprof@latest pprof-time-10503.pb.gz
# Browser interface
$ go run github.com/google/pprof@latest -http=: pprof-time-10503.pb.gz

Options

pprof-it's behavior can be configured via the following environment variables.

• PPROF_PROFILERS: Which profilers to run, separated by commas. The currently available profilers are heap and time. Defaults to heap,time.

• PPROF_OUT: Where to write the profiles. Defaults to the current working directory.

• PPROF_SANITIZE: Enables sanitization of paths in output profiles. May be off or on. Defaults to off.

• PPROF_LINE_NUMBERS: Attempts to collect line numbers. This option is documented as experimental upstream (but seems to work), and only works for time profiles. May be off or on. Defaults to on.

• PPROF_HEAP_OUT: Output path for the heap profile, if enabled. If this path is relative, it will be relative to PPROF_OUT. If a directory, the profile will be placed in that directory with the default name. Defaults to pprof-heap-${process.id}.pb.gz.

• PPROF_HEAP_INTERVAL: Average number of bytes between heap samples. Defaults to 512*1024.

• PPROF_HEAP_STACK_DEPTH: Maximum stack depth for heap samples. Defaults to 64.

• PPROF_TIME_OUT: Output path for the time profile, if enabled. If this path is relative, it will be relative to PPROF_OUT. If a directory, the profile will be placed in that directory with the default name. Defaults to pprof-time-${process.id}.pb.gz.

• PPROF_TIME_INTERVAL: Average number of microsoeconds between time samples. Defaults to 1000.

• PPROF_SIGNAL_EXIT: Enables handling of exit signals (e.g., SIGINT). May be off or on. Since signals are handled asynchronously, pprof-it's registration of signal handlers may prevent exiting (as node will no longer attempt to interrupt normal code execution, e.g. quitting on Ctrl+C). Defaults to on.

• PPROF_LOGGING: Controls pprof-it's logging. May be off or on. Defaults to on.

On Windows, where setting environment variables temporarily is less convenient, it's simplest to just use cross-env to handle this:

$ npx cross-env PPROF_OUT=C:\foo\bar node --require pprof-it path\to\script.js