Flame graph instrumentation for streamline.js, based on Brendan Gregg's FlameGraph

Installation

npm install streamline-flamegraph

Recording

First you need to instrument your code to record performance counters:

var recorder = require('streamline-flamegraph/lib/record').create(options).run();

This will start the recording and create a perf-recorded.gz file in the current working directory of the process.

The recording can be stopped by calling recorder.stop() but you don't need to call it if you want to record till the process exits.

The options argument allows you to pass configuration parameters (see below)

Generating the flamegraph

Once you have recorded data, you need to transform it into a flame graph. This is done with a simple command:

bin/gen-graphs.sh

This will generate two flame graphs in the current directory:

• perf-cpu.svg: CPU only graph
• perf-full.svg: CPU+IO graph

Configuration

You can pass the following configuration options to the create call.

{
	// sampling rate, in milliseconds, 1 by default
	rate: 1,
	// root of source tree (will be trimmed from full file names to get relative paths)
	// by default: ""
	sourceRoot: __dirname,
	// pattern for source link URLs
	// by default: "file://{fullpath}#{line}"
	sourceUrl: "https://github.com/Sage/streamline-flamegraph/tree/master/{relpath}#L{line}",
}

The sourceUrl option allows you to create hyperlinks to the your github repository, or to open your favorite source editor (for example "subl://open/?url=file://{fullpath}&line={line}" for Sublime Text with subl:// URL handler extension).

Gotchas

The flamegraph only displays streamline stacks (but it displays the async stacks). If you want a complete graph including sync JS calls and C++ stacks, see https://gist.github.com/trevnorris/9616784).

The 3 main streamline modes (callbacks, fibers, generators) are supported, but streamline's fast mode must be off.

API may still evolve so I haven't documented it yet.

Credits

Thanks to Brendan Gregg for the great Perl script (deps/flamegraph.pl).

License

MIT (streamline.js) + CDDL (see deps/flamegraph.pl)