$ npm install superstack
superstack 
long stack traces for node.js over async/io boundaries
install
npm install superstack
use
Just require superstack in your project. Ideally one of the first requires (see how it works for why)
var superstack = require('superstack');
function f () {
throw new Error('foo');
}
setTimeout(f, Math.random());
setTimeout(f, Math.random());
Your stack traces will now extend beyond async call boundaries. From the code above.
Before superstack
Error: foo
at f [as _onTimeout] (.../node-superstack/foobar.js:2:11)
at Timer.listOnTimeout [as ontimeout] (timers.js:110:15)
We have no idea which setTimeout call actually caused the error.
After
Error: foo
at f (/Users/shtylman/projects/node-superstack/foobar.js:4:11)
at Timer.listOnTimeout [as ontimeout] (timers.js:110:15)
at Object.<anonymous> (/Users/shtylman/projects/node-superstack/foobar.js:7:1)
at Module._compile (module.js:456:26)
at Object.Module._extensions..js (module.js:474:10)
at Module.load (module.js:356:32)
at Function.Module._load (module.js:312:12)
at Function.Module.runMain (module.js:497:10)
at startup (node.js:119:16)
at node.js:901:3
Notice that the stacktrace identifies which of the two setTimeout fired first and this caused the error.
options
superstack.empty_frame
By default, the stacktrace appears as one long stacktrace. If you want to see the superstack framing boundaries set this value to a string and it will appear in the callstack.
superstack.async_trace_limit
Set this to a positive number to limit the number of frames superstack will capture. This is how many nested async calls back to report. A values of -1 means unlimited. Default is 10.
superstack.format_stack
Function used by superstack to format the stacktrace string. See the implementation for default. The default conforms to the v8 stacktrace strings.
how it works
Superstack works by intercepting certain node.js EventEmitter, process, and Timer APIs. By intercepting the api call and injecting a wrapper callback, any error can be captured and additional frame information added via Error.prepareStackTrace
The following calls are intercepted.
EventEmitter
- on/addListener
- once
- removeListener
- listeners
process
- nextTick
- _nextDomainTick
globals
- setTimeout
- setInterval
- setImmediate
testing
If you find an instance of usage that is not properly captured, please open an issue and provide a testcase to reproduce.
The usual npm test can be run. A more rigorous set of tests can be run by running the runme.sh script in test/modules. It will clone a few popular node.js repos and run their test suits with superstack enabled. This helps ensure that there are limited side effects.
References
Thanks to mattinsler/longjohn and tlrobinson/long-stack-traces for the ideas and code. Longjohn code is MIT licensed.
Also relevant a pdf on the initial idea of long stack traces via an EventSource.
License
MIT
Current Tags
- 0.0.4 ... latest (11 years ago)
shtylman