https://github.com/jakebailey/pprof-it
A handy pprof wrapper for Node.js
https://github.com/jakebailey/pprof-it
Last synced: 3 months ago
JSON representation
A handy pprof wrapper for Node.js
- Host: GitHub
- URL: https://github.com/jakebailey/pprof-it
- Owner: jakebailey
- License: mit
- Created: 2022-01-14T22:48:01.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2026-03-13T11:41:24.000Z (3 months ago)
- Last Synced: 2026-03-29T08:05:14.264Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.44 MB
- Stars: 97
- Watchers: 1
- Forks: 1
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/datadog/pprof-nodejs) 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`:
```sh
$ npx pprof-it path/to/script.js
```
Or, ensure `node` is run with `--require=pprof-it`:
```sh
# Directly running with node
$ node --require pprof-it path/to/script.js
# Executables via npm/npx (v7+)
$ npx --node-option="--require pprof-it"
$ npm exec --node-option="--require pprof-it"
# Executables via npm/npx (v6)
$ npx --node-arg="--require pprof-it"
# Executables via yarn (usually)
$ node --require pprof-it $(yarn bin )
```
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](https://www.speedscope.app/) for
a quick and easy view, or use the
[`pprof` utility](https://github.com/google/pprof) for more info, like:
```sh
# 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:
```ps1
$ npx cross-env PPROF_OUT=C:\foo\bar node --require pprof-it path\to\script.js
```