Discover the bottlenecks and hot paths in your code, with flamegraphs.
Visualize Stack Traces
0x can profile and generate an interactive flamegraph for a Node process with a single command,
on any platform which Node runs on (macOs, Linux, Windows, Android...).
Support
Node v20.x and above
Default usage supports any Operating System that Node runs on!
Chrome
Other browsers may open flamegraphs in a degraded, but functional form
Run a given command and then generate the flamegraph.
The command as specified has access to a $PORT variable.
The $PORT variable is set according to the first port that
profiled process opens.
For instance, here's an example of using autocannon
to load-test the process:
0x -P 'autocannon localhost:$PORT' app.js
When the load-test completes, the profiled processed will be
sent a SIGINT and the flamegraph will be automatically generated.
Remember to use single quotes to avoid bash interpolation,
or else escape variable (e.g. 0x -P "autocannon localhost:$PORT" app.js
won't work wheras 0x -P "autocannon localhost:\$PORT" app.js will).
Note: On Windows interpolation usually occurs with %PORT%, however
in this case the dollar-prefix $PORT is the correct syntax
(because the interpolation is not shell based).
Default: ''
--name
The name of the HTML file, without the .html extension
Can be set to - to write HTML to STDOUT (note
due to the nature of CLI argument parsing, this must be set using =,
e.g. --name=-).
If either this flag or --output-html-file is set to -
then the HTML will go to STDOUT.
Default: flamegraph
---title
Set the title to display in the flamegraph UI.
Default: the command that 0x ran to start the process
--output-dir | -D
Specify artifact output directory. This can be specified in template
form with possible variables being {pid}, {timestamp}, {name}
(based on the --name flag) and {outputDir}(variables
must be specified without whitespace, e.g. { pid } is not supported).
Default: {pid}.0x
--output-html | -F
Specify destination of the generated flamegraph HTML file.
This can be specified in template form with possible variables
being {pid}, {timestamp}, {name} (based on the --name flag) and
{outputDir} (variables must be specified without whitespace,
e.g. { pid } is not supported). It can also be set to - to
send the HTML output to STDOUT (note
due to the nature of CLI argument parsing, this must be set using =,
e.g. --output-html=-).
If either this flag or --name is set to -
then the HTML will go to STDOUT.
Default: {outputDir}/{name}.html
--kernel-tracing
Use an OS kernel tracing tool (perf on Linux). This will capture
native stack frames (C++ modules and Libuv I/O),
but may result in missing stacks from Node.js due to the optimizing compiler.
Limit output, the only output will be fatal errors or
the path to the flamegraph.html upon successful generation.
Default: false
--silent | -s
Suppress all output, except fatal errors.
Default: false
--collect-only
Don't generate the flamegraph, only create the Profile Folder,
with relevant outputs.
Default: false
--collect-delay
Delay the collection of stacks by a specified time(ms) relative to the first entry.
Default: 0
--visualize-only
Supply a path to a profile folder to build or rebuild visualization
from original stacks.
Default: undefined
--visualize-cpu-profile
Supply a path to a CPU profile (.cpuprofile). See examples/cpu-profile for examples.
CPU Profile output does not have as much information but it can be exported from Chrome Devtools in the browser. There's also an automated headless tool for doing so: automated-chrome-profiling. For creating Node.js Cpu Profiles in Node see v8-profiler or v8-profiler-next. They can also be generated from Node.js 12 and above using the command-line flag --cpu-prof.
Default: undefined
--kernel-tracing-debug
Show output from perf(1) tools.
Default: false
--tree-debug
Save the intermediate tree representation of captured trace output to a JSON
file.
Default: false
Programmatic API
0x can also be required as a Node module and scripted:
Very complex applications with lots of stacks may hit memory issues.
The --stack-size flag can be used to set the memory to the maximum 8GB
in order to work around this when profiling:
node --stack-size=8024 $(which 0x) my-app.js
There may still be a problem opening the flamegraph in Chrome. The same work
around can be used by opening Chrome from the command line (platform dependent)
and nesting the --stack-size flag within the --js-flags flag:
--js-flags="--stack-size 8024".
This tool is inspired from various info and code sources
and would have taken much longer without the following people and
their Open Source/Info Sharing efforts: