Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pmuellr/nodprof
profiling for node.js using v8 natives
https://github.com/pmuellr/nodprof
Last synced: about 1 month ago
JSON representation
profiling for node.js using v8 natives
- Host: GitHub
- URL: https://github.com/pmuellr/nodprof
- Owner: pmuellr
- License: apache-2.0
- Created: 2013-07-16T16:43:08.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2013-09-16T14:59:51.000Z (over 11 years ago)
- Last Synced: 2024-11-13T07:55:25.723Z (about 2 months ago)
- Language: JavaScript
- Size: 891 KB
- Stars: 20
- Watchers: 2
- Forks: 5
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
`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.
### `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
### `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.