README

在所有浏览器中生成、解析和增强JavaScript堆栈跟踪

使用函数调用导致的错误（或您指定的任何条件）的堆栈跟踪来调试和性能分析您的JavaScript。

stacktrace.js使用浏览器的Error.stack机制生成堆栈跟踪，解析它们，并使用源映射增强它们，并使用Promises返回一个包含StackFrames的数组。

正在升级？请查看0.x -> 1.x 迁移指南

用法

从当前位置获取堆栈跟踪

var callback = function(stackframes) {
    var stringifiedStack = stackframes.map(function(sf) {
        return sf.toString();
    }).join('\n');
    console.log(stringifiedStack);
};

var errback = function(err) { console.log(err.message); };

StackTrace.get().then(callback).catch(errback)
=> Promise(Array[StackFrame], Error)
=> callback([StackFrame('func1', [], 'file.js', 203, 9), StackFrame('func2', [], 'http://localhost:3000/file.min.js', 1, 3284)])

window.onerror集成

自动处理错误

window.onerror = function(msg, file, line, col, error) {
    // callback is called with an Array[StackFrame]
    StackTrace.fromError(error).then(callback).catch(errback);
};

从Error获取堆栈跟踪

var error = new Error('BOOM!');

StackTrace.fromError(error).then(callback).catch(errback)
=> Promise(Array[StackFrame], Error)

通过遍历arguments.callee生成堆栈跟踪

这可能捕获参数信息，但不支持ES5严格模式

StackTrace.generateArtificially().then(callback).catch(errback)
=> Promise(Array[StackFrame], Error)

每次给定函数被调用时跟踪

// callback is called with an Array[StackFrame] every time wrapped function is called
var myFunc = function(arg) { return 'Hello ' + arg; }
var myWrappedFunc = StackTrace.instrument(myFunc, callback, errback)
=> Instrumented Function
myWrappedFunc('world');
=> 'Hello world'

// Use this if you overwrote you original function
myFunc = StackTrace.deinstrument(myFunc)
=> De-instrumented Function

获取stacktrace.js

npm install stacktrace-js
bower install stacktrace-js
component install stacktracejs/stacktrace.js
http://cdnjs.com/libraries/stacktrace.js

API

StackTrace.get(/*optional*/ options) => Promise(Array[StackFrame])

从调用点生成回溯，然后解析和增强它。

(可选) options: 对象

• filter: 函数(StackFrame => Boolean) - 仅包括匹配的堆栈条目，其中filter返回true
• sourceCache: 对象 (String URL => String Source) - 预填充源缓存以避免网络请求
• offline: Boolean (默认: false) - 设置为true以防止所有网络请求

StackTrace.getSync(/*optional*/ options) => Array[StackFrame]

从调用点生成回溯，然后解析它。注意：此方法不使用源映射或猜测匿名函数。

(可选) options: 对象

• filter: 函数(StackFrame => Boolean) - 仅包括匹配的堆栈条目，其中filter返回true

StackTrace.fromError(error, /*optional*/ options) => Promise(Array[StackFrame])

给定一个Error对象，使用error-stack-parser来解析它，并使用stacktrace-gps增强位置信息。

error: Error

(可选) options: 对象

• filter: 函数(StackFrame => Boolean) - 仅包括匹配的堆栈条目，其中filter返回true
• sourceCache: 对象 (String URL => String Source) - 预填充源缓存以避免网络请求
• offline: Boolean (默认: false) - 设置为true以防止所有网络请求

StackTrace.generateArtificially(/*optional*/ options) => Promise(Array[StackFrame])

使用stack-generator通过遍历arguments.callee.caller链来生成回溯。

(可选) options: 对象

• filter: 函数(StackFrame => Boolean) - 仅包括匹配的堆栈条目，其中filter返回true
• sourceCache: 对象 (String URL => String Source) - 预填充源缓存以避免网络请求
• offline: Boolean (默认: false) - 设置为true以防止所有网络请求

StackTrace.instrument(fn, callback, /*optional*/ errback) => Function

• 给定一个函数，将其包装，以便在调用时触发一个带有堆栈跟踪的回调。

• fn: Function - 要包装，在调用时调用回调并通过调用传递

• callback: Function - 当fn被调用时，与堆栈跟踪（由StackTrace.get()生成）一起调用

• (可选) 错误回调：函数 - 如果在获取堆栈跟踪时出现问题，则使用错误对象调用。如果无法生成堆栈跟踪，则静默失败（尽管 fn 仍然会被调用）。

StackTrace.deinstrument(fn) => 函数

给定一个已进行代码插入的函数，将其还原为其原始（非代码插入）状态。

• fn：函数 - 代码插入后的函数

StackTrace.report(stackframes, url, message) => Promise(字符串)

给定一个错误信息和堆栈帧数组，将其序列化并发送到指定的URL。Promise由POST请求的响应文本解决。

示例JSON POST数据

{
  message: 'BOOM',
  stack: [
    {functionName: 'fn', fileName: 'file.js', lineNumber: 32, columnNumber: 1},
    {functionName: 'fn2', fileName: 'file.js', lineNumber: 543, columnNumber: 32},
    {functionName: 'fn3', fileName: 'file.js', lineNumber: 8, columnNumber: 1}
  ]
}

• message：字符串 - 错误信息
• stackframes：数组（StackFrame） - 之前包装的函数
• url：字符串 - 发送堆栈JSON的URL

浏览器支持

注意：在IE9或其他非常旧的浏览器中，您将无法获得源映射的好处。

仅使用node.js/io.js吗？

我推荐专门的stack-trace node包，它专门为node构建。它具有非常相似的API，并且也支持源映射。

贡献

此项目遵循开放行为准则。通过参与，您应遵守此准则。

想要被列为贡献者？请从贡献指南开始！

此项目得以实现，归功于这些优秀人士的努力

• Eric Wendelin
• Victor Homyakov
• Oliver Salzburg
• 许多人