traceable

Capture, parse and format V8 stack trace.

Installation

npm install traceable

Usage

traceable([input], [options])

The main function can:

• Capture and normalize the stack trace from the current invocation
• Parse stack trace from an Error object
• Recongize asyncStack on an Error object
• Format the stack trace

The returned object is an instance of StackTrace.

1var traceable = require('traceable');
2
3// main function is aliased as a property of the module
4traceable.trace === traceable;
5
6// get stack trace
7traceable();
8
9// get stack trace with top most N frames skipped
10traceable(2);
11
12// get stack trace with frames above myFunc skipped
13traceable(myFunc);
14
15// get stack trace captured by the Error object
16var err = new Error();
17traceable(err);
18
19// same as above in case only the stack trace itself is available
20var stack = err.stack
21traceable(stack);

Options

Below is an exhausive list of options, with the default value shown.

1{
2    // string prepended to each frame
3    // if supplied with number, that number of spaces is prepended
4    indent: "    ",
5
6    // hide frames from source files specified (see 'Blackboxing')
7    blackbox: [],
8
9    // format the stack trace when StackTrace.toString is called
10    formatter: Formatter.default,
11
12    // descriptive label for anonymous function
13    anonString: "",
14
15    // show column number
16    showColumnNumber: false,
17
18    // show eval site if function is from eval'd code
19    showEvalOrigin: true,
20
21    // append async stack trace if any
22    showAsyncOrigin: true,
23
24    // show original source file path (see 'Paths to source files')
25    showFullPath: false,
26
27    // show original function name (see 'Function names')
28    showRawFunctionName: false
29}

Paths to source files

Unless showFullPath is set to true, paths to source files are stripped as relative to:

• the innermost node_modules folder
• any of the global module paths
• directory of the main module
• process working directory

/path/to/node_modules/my-mod/node_modules/traceable/traceable.js is resolved as traceable/traceable.js

Function names

Unless showRawFunctionName is set to true, function names are manipulated as follow:

• function which aliased to another name takes the highest precedence

  Object.aliasedName instead of Object.origName [as aliasedName]

• function names resolved with pseudo-namespaces are stripped

  Object.myFunc instead of Object.$.extend.myFunc

• if the function is called on an anonymous object (often calling function of an object literal) and the function is not defined on Object.prototype, the type name is replaced with ?:

  ?.resolve instead of Object.resolve; while

  Object.hasOwnProperty is kept

Blackboxing

Blackboxing, similar to the node inspector interface, can hide frames from certain source file as specified.

Paths can be:

• names to built-in modules: fs.js
• relative to the innermost node_modules folder
• relative to any of the global module paths
• relative to directory of the main module
• relative to process working directory

If a path resolves to a folder, all scripts under that folder will be blackboxed. Thus:

/path/to/program/node_modules/my-mod/node_modules/nested/util/x.js can be blackboxed by one of the following path:

• nested/util/x.js,
• nested/util,
• nested

traceable.StackTrace

The StackTrace object is an Array-prototyped object that contains StackFrame objects parsed from the stack trace.

So you can freely work with the parsed stack trace with functions like Array.filter and Array.forEach etc.

1var st = traceable(err);
2st.forEach(function (v) {
3    // prints the function name of each call site
4    console.log(v.functionName);
5});

traceable.StackFrame

The StackFrame object represent each call site parsed and contains normalized information about the call site.

1{
2    // formatted string from built-in CallSite.toString()
3    rawString: '    at new Object.extend.doSomething (/path/to/my/script.js:50:4)'
4
5    // whether the call site is native
6    native: false,
7
8    // whether the call site is called by 'new' operator
9    isConstructor: true,
10
11    // type name of 'this' object in the call site
12    typeName: 'Object',
13
14    // function name resolved by V8
15    rawFunctionName: 'extend.doSomething',
16
17    // full path of the script file
18    // null for native call site
19    fileName: '/path/to/my/script.js',
20
21    // line number of the call site
22    // null for native call site
23    lineNumber: 50,
24
25    // column number of the call site
26    // null for native call site
27    columnNumber: 4,
28
29    // a StackTrace object parsed from the async stack trace
30    // if the Error object is prep'd with async stack trace
31    // otherwise undefined
32    asyncOrigin: <#StackTrace>,
33
34    // a StackFrame object of the eval call site
35    // if the call site in a function compiled in eval or new Function
36    // otherwise null
37    get evalOrigin(),
38
39    // function name
40    get functionName(),
41
42    // formatted string of the function location
43    // depends on options.formatter
44    get source()
45}

traceable.Formatter([options])

Provides means to customize the formatted output of the stack trace.

There is two built-in formatters, default and native.

• traceable.Formatter.default (a.k.a inspector style):

  (anonymous function) @ /trace-test/anon.js:2
  MyClass.method       @ myclass/myclass.js:210
  dynamic_function     @ <anonymous>:2 eval at myclass/helper.js:50

• traceable.Formatter.native

  at /trace-test/anon.js:2:10
  at MyClass.extend.myMethod (/trace-test/node_modules/myclass/myclass.js:210:4)
  at dynamic_function (eval at /trace-test/node_modules/myclass/helper.js:50:12, <anonymous>:2:4)

You can create your own formatter by defining functions the handle different components of a stack trace.

All options are optional, if not specified the native style is used. The second parameter options is the options passed to traceable().

Each function should return a string.

1new traceable.Formatter({
2    // format the entire stack trace
3    // called by StackTrace.toString
4    formatTrace: function (stackTrace, options) { ... },
5
6    // format each call site
7    formatFrame: function (stackFrame, options) { ... },
8
9    // format the location of call site
10    // called by StackFrame.source
11    formatSource: function (stackFrame, options) { ... },
12
13    // format eval site which is appended to the source
14    // called by StackFrame.source
15    formatEvalOrigin: function (stackFrame, options) { ... },
16
17    // format async marker and the whole async stack trace
18    // called by StackFrame.toString
19    // see async stack trace example below
20    formatAsyncOrigin: function (stackTrace, options) { ... }
21})

traceable.prepAsyncStack([skip])

Enable more verbose stack trace in async operation.

Similar to long-stack-trace but instead of wrapping async function such as setTimeout and EventEmitter.on, it records the current stack trace and return a prep function.

1function somethingAsync() {
2    var prep = traceable.prepAsyncStack();  // returns a function
3    setTimeout(function () {
4        var err = new Error();
5        // the stack trace captured by prepAsyncStack()
6        // is assigned to the Error object
7        throw prep(err);
8    });
9}
10process.on('uncaughtException', function(err){
11    // recognizes the prep'd async stack
12    console.log(traceable(err));
13});

would output the following to console:

    at async.js:6:19
    [async]
    at somethingAsync (async.js:2:16)
    at someOtherFunction (main.js:40:4)

Options

skip: Number of frames to skip

License

The MIT License (MIT)

Copyright (c) 2015 misonou

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.