nodprof - profiling for node.js

nodprof command line

The nodprof command can be used to:

• run a node.js module and profile the execution
• start an HTTP server used to display profiling results

A static-ish demo of nodprof is available at http://muellerware.org/nodprof-static/

When profiling a node.js module, the profiling results will be stored in a JSON file in a directory indicated by the nodprof configuration.

The nodprof HTTP server provides a viewer for these profiling results. You can also use the nodprof module API to add the nodprof viewer to your own application via middleware.

To run the server, use the --serve option. If the --serve option isn't used then nodprof will run the remainder of the command-line as a module invocation and profile the execution.

When profiling a module, profiling will be started, the module will be require()d, and when process emits the exit event, profiling will be stopped and the data written out.

example command line invocation

sudo npm -g install nodprof
nodprof --serve --port 8081&
nodprof `which npm` info grunt
open http://localhost:8081

This will:

• install nodprof globally
• start the nodprof server on port 8081
• profile npm info grunt
• open a browser to view the results

nodprof configuration

nodprof uses a configuration to determine the values of various twiddleable values it uses. These values can be set in the following places, listed in precedence order:

• command line options
• environment variables
• configuration file values
• default values

command line options

options specified as Boolean can be specified without a Boolean value, in which case the value is assumed to be true.

-c --config	path	the location of the configuration file
-v --verbose	Boolean	be noisy
-x --debug	Boolean	be very noisy
-p --port	Number	the HTTP port when running the server
-d --data	path	the directory to use to read and write profiling data
-s --serve	Boolean	run the HTTP server
-h --heap	Boolean	generate a heap snapshot
-r --profile	Boolean	generate a profile

environment variables

PORT

Number

the HTTP port when running the server

configuration file values

The configuration file is a JSON file whose content is an object with the following properties:

verbose	Boolean	same as --verbose
debug	Boolean	same as --debug
port	Number	same as --port
data	path	same as --data
heap	Boolean	same as --heap
profile	Boolean	same as --profile

default values

--verbose	Boolean	false
--debug	Boolean	false
--config	path	~/.nodprof/config.json, where ~ is the value of the USERPROFILE environment variable on windows
--port	Number	3000
--data	path	~/.nodprof/data (see note on --config above)
--serve	Boolean	false
--heap	Boolean	true
--profile	Boolean	true

nodprof module API

The nodprof module provides low-level support for profiling via exported functions. The functions return large JSON-able objects.

nodprof.profileStart()

Start profiling. Does nothing if profiling already started.

Returns nothing.

nodprof.profileStop()

Stop profiling. Does nothing if profiling already stopped.

Returns a ProfileResults object or null if profiling was not started.

nodprof.isProfiling()

Returns true if profiling has been started, else false.

nodprof.heapSnapshot()

Returns a HeapSnapshotResults object.

nodprof.middleware(config)

Returns a function which can be used as connect middleware to provide the function of the command-line nodprof server in your application. The url is the directory-sh uri to mount the functionality under, and defaults to /nodprof.

The config parameter specifies a configuration object, which is the same format as the configuration file specified above.

Example for express:

app.use("/nodprof/", nodprof.middleware())

nodprof object shapes

For more detail on what the values in these objects mean, see the source at https://code.google.com/p/v8/source/browse/trunk/include/v8-profiler.h

ProfilesResult object

dateStarted:	Date	the date the profile was started
dateStopped:	Date	the date the profile was stopped
head:	ProfileNode	the first node in the profile

ProfilesNode object

functionName:	String	the name of the function executing
scriptName:	String	the name of the script executing
lineNumber:	Number	the line number executing
totalTime:	Number	total amount of time take at this node
selfTime:	Number	the time taken by this node not including called functions
totalSamples:	Number	total number of samples retrieved
selfSamples:	Number	the numer of samples retrieved not including called functions
children:	[ProfileNode]	nodes called from this node

HeapSnapshotResults object

date:	Date	the date the heap snapshot was taken
root:	String	the id of the root object (a HeapNode)
nodes:	Object	an object whose keys are ids and values are a HeapNode

HeapNode object

type:	Number	the type of node
name:	String	the name of the node
size:	Number	the size of the node
edges:	[HeapEdge]	the edges of the node

HeapEdge object

type:	Number	the type of edge
name:	String	the name of the edge
node:	String	the id of the node the edge points to

nodprof development

If you want to hack on nodprof, the workflow:

1. clone the git repo
2. cd into the project directory
3. run make watch
4. edit the files in your flavorite editor
5. when you save files, the code will be rebuilt, and server restarted
6. generate some profiling data, view in the restarted server

Then iterate on 4, 5, and 6.