Traceback: easy access to the call stack, for Node.js

Writing a Node app? Need to know the function backtrace? Don't want to compile C++ code? Use Traceback.

Traceback provides a normal JavaScript array of the execution stack frames. You can see function names, line numbers, and other useful stuff.

Traceback is available from NPM.

$ npm install traceback

Example

example.js

var traceback = require('../traceback');
 
function start() { first() }
function first() { second() }
var second = function() { last() }
 
function last() {
  var stack = traceback();
  console.log('I am ' + stack[0].name + ' from file ' + stack[0].file)
 
  for(var i = 1; i <= 3; i++)
    console.log('  ' + i + ' above me: ' + stack[i].name + ' at line ' + stack[i].line);
}
 
start();

Output:

I am last from file example.js
  1 above me: second at line 5
  2 above me: first at line 4
  3 above me: start at line 3

Usage

Simply calling traceback() gives you the stack, with the current function in position 0.

Stack frame objects have normal V8 CallSite objects as prototypes. All those methods will work. You can also call traceback.raw() to get the exact stack made by V8.

But traceback()'s stack frame objects have convenient attribute names:

• name | The function name
• path | The absolute path of the file defining the function
• file | The basename of the path file ("example.js")
• line | The line number in the file
• col | The column number in the file
• pos | The byte position in the file
• fun | The function itself
• method | If this function was called as a method, the name it is stored as
• this | The object bound to the label this in the function
• type | The type of this; the name of the constructor function (Object, ReadStream, etc.)
• origin | The CallSite that ran eval(), if this frame is an eval
• is_top | Boolean indicating whether the function was called with a global this
• is_eval | Boolean indicating whether the function comes from an eval() call
• is_native | Boolean indicating whether the function is native
• is_ctor | Boolean indicating whether this is a constructor (new) call

They also work correctly in JSON.stringify().

Tests

Tests use node-tap. Clone this Git repository, run npm install and then run the tests through npm:

$ npm test

> traceback@0.3.1 test /Users/jhs/src/traceback
> tap test/

ok test/api.js ...................................... 326/326
ok test/fail.js ....................................... 36/36
ok test/format.js ....................................... 7/7
ok test/readme.js ....................................... 2/2
total ............................................... 371/371

ok

License

Apache 2.0