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

Current Tags

0.3.1 ... latest (10 years ago)

2 Versions

0.3.1 ... 10 years ago
0.3.0 ... 13 years ago