🔥 single-command flamegraph profiling 🔥
Discover the bottlenecks and hot paths in your code, with flamegraphs.
0x can profile and generate an interactive flamegraph for a Node process in a single command, on both Linux and OS X. Whilst this seems trivial... it's not. Well it wasn't before 0x.
An example interactive flamegraph can be viewed at http://davidmarkclements.github.io/0x-demo/
Node v6+
OS
npm install -g 0x
Prefix the usual command for starting a process with 0x:
0x my-app.js
You can make the flamegraph automatically open in your browser with:
0x -o my-app.js
Using a custom Node.js executable:
0x -- /path/to/node my-app.js
Passing custom arguments to node:
0x -- node --trace-opt --trace-deopt my-app.js
Once we're ready to generate a flamegraph we send a SIGINT.
The simplest way to do this is pressing CTRL+C.
When 0x catches the SIGINT, it process the stacks and
generates a profile folder (<pid>.flamegraph), containing flamegraph.html
Due to security reasons Docker containers tend to result in the following error:
Cannot read kernel map
perf_event_open(..., PERF_FLAG_FD_CLOEXEC) failed with unexpected error 1 (Operation not permitted)
perf_event_open(..., 0) failed unexpectedly with error 1 (Operation not permitted)
Error:
You may not have permission to collect stats.
[...]
We can work around this problem by running our container with the --privileged option
or add privileged: true in your docker-compose.yml file.
See the Docker's doc for more info.
Generating a flamegraph can be quite intense on CPU and memory, if we have restricted resources we should generate the flamegraph in two pieces.
First we can use the --collect-only flag to purely capture stacks.
0x --collect-only my-app.js #0x on the server
Press ctrl+c when ready, this will create the usual profile folder,
holding one file, that stacks.$PID.out file.
Now we need to transfer the stacks file from our production server to our local dev machine.
Let's say the pid was 7777, we can generate the flamegraph locally with
0x --gen stacks.7777.out # 0x locally
Now the hard work is done away from production, ensuring we avoid any service-level problems.
Alternatively if we transfer the entire folder (containing the stacks file),
we can pass the folder to --visualize-only:
0x --visualize-only 7777.flamegraph # create a flamegraph.html in 7777.flamegraph
As your stack grows you may have memory issues with both Node and your browser.
For Node, run with the following flag
--stack-size=8024
For Chrome, run with the following flag
--js-flags="--stack-size 8024"
Where 8024 is the megabytes of RAM required to run load stack. Adjust this as needed and confirm you have it to spare.
If you are getting empty output stacks, you may have to run with sudo:
sudo 0x my-app.js
Use -- to set the node executable and/or set node flags
0x [0xFlags] -- node [nodeFlags] script.js [scriptFlags]
For instance
0x --open -- node --zero-fill-buffers script.js --my-own-arg
Print usage info
Open the flamegraph on your browser using open or xdg-open (see
https://www.npmjs.com/package/open for details).
The name of the HTML file, without the .html extension Can be set to - to write HTML to STDOUT
Set the title to display in the flamegraph UI.
Specify artifact output directory
Default: ${process.cwd()}/{PID}.flamegraph(-${Date.now()})?
Generate the flamegraph from a specified stacks.out file.
The --tiers and --langs flags can also be combined with this flag.
Outputs to STDOUT unless the --name flag is set, in which case
outputs to a file {name}.html in the current folder.
Generates an flamegraph.svg file in the artifact output directory,
in addition to the flamegraph.html file.
Milliseconds. Delay before tracing begins (or before stacks are processed in the Linux case), allows us to ignore initialisation stacks (e.g. module loading).
Example: 0x -d 2000 my-app.js
Default: 300
Color code the stacks by JS and C
Example: 0x -l my-app.js
Default: false
A comma separated list
Overrides langs, Color code frames by type
Examples: 0x -t my-app.js
Default: false
Exclude tiers or langs, comma seperated list
Options: v8, regexp, nativeC, nativeJS, core, deps, app, js, c
Examples:
0x -x v8,nativeC,core my-app.js
0x -x c my-app.js
Default: v8
Include tiers, Overwrites exclude. Really only useful for including the v8 tier (which is excluded by default).
Options: v8, regexp, nativeC, nativeJS, core, deps, app, js, c
Example: 0x --include v8 my-app.js
Default: false
Dark or Light theme
Options: dark | light
Example: 0x --theme light my-app.js
Default: dark
Limit output, the only output will be fatal errors or
the path to the flamegraph.html upon successful generation.
Default: false
Suppress all output, except fatal errors.
Default: false
Save the intermediate JSON tree representation of the stacks.
Default: false
Don't generate the flamegraph, only create the stacks output.
Default: false
Supply a path to a profile folder to build or rebuild visualization from original stacks. Similar to --gen flag, except specify containing folder instead of stacks file.
Default: ''
Specify stdout or stderr as 0x's output stream.
Default: stderr
Show output from dtrace or perf tools
Default: false
Prefixes the current timestamp to the Profile Folder's name minimizing collisions in containerized environments
Example: 1516395452110-3866.flamegraph
By default, a profile folder will be created and named after the PID, e.g.
3866.flamegraph (we can set this name manually using the --output-dir flag).
The Profile Folder can contain the following files
--json-stacksThe is helpful, because there's other things you can do with stacks output. For instance, checkout cpuprofilify and traceviewify.
Want to try it out? Clone this repo, run npm i -g and
from the repo root run
0x examples/rest-api
In another tab run
npm run stress-rest-example
To put some load on the rest server, once that's done use ctrl + c to kill the server.
Now try some other options, e.g.
0x -t examples/rest-api
See ./examples/babel for an example. Note the babel require hook is not currently supported. Notes on using the babel-cli instead can be found in the babel example readme.
0x can also be required as a Node module and scripted:
const zeroEks = require('0x')
const path = require('path')
zeroEks({
argv: [path.join(__dirname, 'my-app.js'), '--my-flag', '"value for my flag"'],
workingDir: __dirname
})
require('0x')(opts, binary, cb)The cb option is a error first callback which is invoked after a
profile folder has been created and populated.
The binary option can be false (to default to the node executed resolved
according to environment PATH) or a string holding the path to any
node binary executable.
The opts argument is an object, with the following properties:
argv (array) – requiredPass the arguments that the spawned Node process should receive.
workingDir (string)The base directory where profile folders will be placed.
Default: process.cwd()
name (string)The name of the flamegraph HTML output file, without the extension.
Default: flamegraph
open (boolean)See --open
quiet (boolean)See --quiet
silent (boolean)See --silent
jsonStacks (boolean)See --json-stacks
svg (boolean)See --svg
logOutput (boolean)See --log-output
timestampProfiles (boolean)traceInfo (boolean)See --trace-info
theme (string)See --theme
include (string)See --include
exclude (string)See --exlude
langs (string)See --langs
tiers (string)See --tiers
gen (string)See --gen
output-dir (string)See outputDir
title (string)See --title
delay (number)See --delay
visualizeOnly (string)See --visualize-only
collectOnly (boolean)See --collect-only
require('0x').stacksToFlamegraph(opts, binary, cb)This method will take a captured stacks input file and generate a flamegraph HTML file.
It takes the same arguments as the main function, but the
gen argument (which should hold a path to the source
stacks file) and the name argument (which should specify a
destination out file) is required.
If you still need support for Node v4, use 0x v2.x.x
Don't use v1, it was an experiment and is non functional Should have be v0...
Yes please!
DEBUG=0x* 0x my-app.js
0x is generously sponsored by nearForm
This tool is essentially a mashup from various info and code sources, and therefore would have taken much longer without the following people and their Open Source/Info Sharing efforts
MIT and Apache (depending on the code, see LICENSE.md)
v3.0.2
FAQs
🔥 single-command flamegraph profiling 🔥
The npm package 0x receives a total of 22,664 weekly downloads. As such, 0x popularity was classified as popular.
We found that 0x demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.