Next Phenomenal Microbrewery
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    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

    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.


    Start profiling. Does nothing if profiling already started.

    Returns nothing.


    Stop profiling. Does nothing if profiling already stopped.

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


    Returns true if profiling has been started, else false.


    Returns a HeapSnapshotResults object.


    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

    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.




    npm i nodprof

    Downloadslast 7 days







    last publish


    • avatar