Profile, debug, optimize and understand node applications.
Profile, debug, optimize and understand node applications. With the help of native bindings to the v8-profiler you're able to take snapshosts of the heap, profile CPU usage and debug your code with breakpoints while running.
The debugger is there to inspect taken snapshots visually, or interact with your remote processes in a convenient way. It's built upon the WebInspector front-end that is shipped with most WebKit variants.
This project is mainly inspired by three modules:
Heap profiling is exposed via the
heap object and enables you to take snapshots and manage the snapshosts. The
heap exposes the interface implemented in the v8 HeapProfiler.
Structure of a snapshot:
uid: <NUMBER> // internally generated idroot: <NODE>title: <STRING> // empty if not passed as argument to takeSnapshot()type: <STRING> // "Full" is the default and only optionnodes: <STRING> // amount of nodesdelete: Function: deletegetNode: Function: getNodegetNodeById: Function: getNodeByIdserialize: Function: serialize
Take a snapshot of the current process:
var heap = require'profiler'heap;var snapshot = heaptakeSnapshot'a-meaningful-name';
Serialize a snapshot as JSON into a file:
Delete one snapshot:
Delete all snapshots:
Get the current
count of snapshots:
Get/Find a snapshot:
// get by indexheapgetSnapshot0;// find by UIDheapfindSnapshot1;
A snapshot consists of many nodes, starting with the
root node which is exposed as top-level property. The structure of a node:
id: <NUMBER> // internal IDptr: <NUMBER> // pointer addresstype: <STRING> // type of the node like: 'Object', 'String', 'Array'...dominatorNode: <NODE> // This is the node that participates in every path from the snapshot root to the current nodename: '' // Depending on node's type this can be the name of the constructor (for objects), the name of the function (for closures), string value, or an empty string (for compiled code)approximateRetainedSize: <NUMBER> // imprecise guess on the retainedsize of the noderetainersCount: <NUMBER> // Retainer nodes count of the nodechildrenCount: <NUMBER> // count of childrensize: <NUMBER> // node's own size in bytesgetChild: Function: getChild // Retrieves a child by indexgetRetainer: Function: getRetainer // Returns a retainer by indexgetRetainedSize: Function: getRetainedSize // That is, self + sizes of the objects that are reachable only from this object. In other words, the size of memory that will be reclaimed having this node collected. This call returns an accurate number of approximateRetainedSize
Get a node by it's ID:
snapshotgetChild1; // will return the root element
Hook into running processes and take snapshots.
var repl = require'repl';replcreateRepl;
The repl listens on a
signal by default
SIGUSR2 to start and stop the debug server.
You can change the
port by passing a config object:
var repl = require'repl';replcreateRepl event: 'SIGUSR1' host: '0.0.0.0' port: 11111 ;
To start the interactive debugger call:
Per default the debugger will start on http://localhost:1337/debug.
Overwrite the default port and host with:
debugger --host=0.0.0.0 --port=9000
You can preload heap snapshots for inspection with a comma-separated list:
Binding functions like
getSnapshot() which take a variable
id causing a segmentation fault when called with an invalid reference.
This module is early alpha. Many of the documented interfaces aren't even implemented yet as this README.md is developed with principle of RDD.
To build the node addon and install dependencies run:
To run all tests:
This repository is organized and maintained with the help of gitflow. Developers are encouraged to use it when working with this repository.
We use the following naming convention for branches:
master(will be or has been released)
(empty version prefix)
During development, you should work in feature branches instead of committing to
master directly. Tell gitflow that you want to start working on a feature and it will do the work for you (like creating a branch prefixed with
git flow feature start <FEATURE_NAME>
The work in a feature branch should be kept close to the original problem. Tell gitflow that a feature is finished and it will merge it into
master and push it to the upstream repository:
git flow feature finish <FEATURE_NAME>
Even before a feature is finished, you might want to make your branch available to other developers. You can do that by publishing it, which will push it to the upstream repository:
git flow feature publish <FEATURE_NAME>
To track a feature that is located in the upstream repository and not yet present locally, invoke the following command:
git flow feature track <FEATURE_NAME>
Changes that should go into production should come from the up-to-date master branch. Enter the "release to production" phase by running:
git flow release start <VERSION_NUMBER>
In this phase, only meta information should be touched, like bumping the version and update the history. Finish the release phase with:
git flow release finish <VERSION_NUMBER>
This project is versioned with the help of the Semantic Versioning Specification using
0.0.0 as the initial version. Please make sure you have read the guidelines before increasing a version number either for a release or a hotfix.
- Fork Prof
- Create a topic branch
git checkout -b my_branch
- Push to your branch
git push origin my_branch
- Create a Pull Request from your branch
- Fork Prof
- Create a feature
git flow feature start my-feature
- Publish your featue
git flow feature publish my-feature
- Create a Pull Request from your branch
git clone email@example.com:goldjunge/prof.git
- Home: https://github.com/goldjunge/prof
- Docs: https://github.com/goldjunge/prof
- Bugs: https://github.com/goldjunge/prof/issues
- implement snapshot header handling
- implement remote connection to node process in debug mode
- implement cpu profiling
- implement interactive console
- implement breakpoints
- generate docs (man?)
- generate site