exceptions.js, JS错误报告使用 stacktraces,屏幕截图 & DOM

分享于 

26分钟阅读

GitHub

  繁體 雙語
Exceptions for javascript
  • 源代码名称:exceptions.js
  • 源代码网址:http://www.github.com/steaks/exceptions.js
  • exceptions.js源代码文档
  • exceptions.js源代码下载
  • Git URL:
    git://www.github.com/steaks/exceptions.js.git
    Git Clone代码到本地:
    git clone http://www.github.com/steaks/exceptions.js
    Subversion代码到本地:
    $ svn co --depth empty http://www.github.com/steaks/exceptions.js
    Checked out revision 1.
    $ cd repo
    $ svn up trunk
    
    exceptions.js

    Exceptions.js 是使Javascript错误有用的库。 包括 stacktraces,屏幕截图,DOM转储,浏览器信息,用户点击Javascript错误时的等等。 库可以用作独立开放源码项目,也可以用于exceptionsjs平台( https://www.exceptionsjs.com ),将报告的异常转换为电子邮件。 请参阅演示:https://www.exceptionsjs.com/demo

    基本设置和用法

    
    
    
    
    <script type="text/javascript" src="path/to/exceptions.js"></script>
    
    
    
    ex.handler
    
    
     //Reporting to exceptionsjs platform is the easiest way to track your exceptions.
    
    
     //Register for free at https://www.exceptionsjs.com.
    
    
    . reportToExceptionsJsPlatform({ clientId: "CLIENT_ID" })
    
    
     //Set a custom report post request that will be issued when an exception is reported.
    
    
     //if you want to bypass the exceptionsjs platform and handle the exception yourself.
    
    
    . reportPost({ url: "http://localhost/path/to/errorhandler/" });
    
    
    
    
    
    
    
    
    //exceptions.js will handle any error.
    
    
    var foo = {}, oops = foo.uhoh.doesNotExist;
    
    
    throw new Error("Something went wrong!");
    
    
    throw "Something went wrong!";
    
    
    
    //you can also report exceptions.
    
    
    new ex.Exception("Something went wrong!").report();
    
    
    
    //or throw an exception.
    
    
    throw new ex.Exception("Something went wrong!");
    
    
    
    //exceptions.js provides convienence methods that make code more readable.
    
    
    function myFunc(requiredArg) {
    
    
     ex.throwIf(!requiredArg, "The requiredArg argument was not provided!!!");
    
    
    }
    
    
    
    //and types that make errors more explicit
    
    
    function WillWriteInTheFuture() {
    
    
     throw ex.NotImplementedException();
    
    
    }
    
    
    
    //and other useful features including support for inner exceptions,
    
    
    //ability to include extra data with your exceptions, abilities protect
    
    
    //against bursts or repeated exceptions
    
    
    
    

    API

    exceptions.js 将异常属性添加到公开以下内容的窗口对象中:

    属性说明
    处理程序对象负责处理命中 window.onerror的错误,并指定包括 stacktrace.js url。html2canvas.js url。post url ( 在报告错误时发出post请求)。post标头。回调( 报告错误时执行的函数) 和回调消息的全局配置。
    Guard保护你的页面在应用程序遇到异常时保护你的页面减慢或者大量错误邮件
    选项报告单个异常时应该打开或者关闭的选项。
    异常基本异常来自异常的所有其他异常 inherit。
    ArgumentException继承自异常的异常,它对于引发或者报告与函数参数相关的异常非常有用
    继承自异常的异常,它对于引发或者报告与无效操作相关的异常非常有用
    NotImplementedException继承自异常的异常,它对于引发或者报告与未实现代码相关的异常非常有用
    EvalException从异常继承的异常,它对于引发或者报告与eval错误相关的异常非常有用
    RangeException从异常继承的异常,它对于引发或者报告与范围错误相关的异常非常有用
    ReferenceException从异常继承的异常,它对于引发或者报告与引用错误相关的异常非常有用
    SyntaxException从异常继承的异常,它对于引发或者报告与语法错误相关的异常非常有用
    TypeException继承自异常的异常,它对于引发或者报告与类型错误相关的异常非常有用
    URIException继承自异常的异常,它对引发或者报告与URI错误相关的异常非常有用
    createCustomException可以用于创建自定义函数的函数。 使用createCustomException创建 ArgumentException,InvalidOperationException和 NotImplementedException
    throwIf调用 Exception.throwIf的shorthand 方法。 使用这里函数有条件地引发异常。
    reportIf调用 Exception.reportIf的shorthand 方法。 使用这里函数有条件地引发异常。

    异常

    构造函数

    异常是包装错误并提供本机错误类不提供的额外功能的基异常类。 可以扩展异常类以使用 exceptions.createCustomException 创建自定义异常。

    参数

    需要参数类型说明
    邮件字符串或者错误不是创建具有错误对象或者错误消息的异常。 如果传递消息或者简单地将所提供的错误作为所包装的基础错误,则这里构造函数将创建新的Error(message)。
    配置对象不是使用配置对象配置异常。 配置上的所有属性都是可选的。

    配置

    属性类型说明
    姓名字符串为异常提供一个 NAME。 如果未提供 NAME,则检查你是否手动设置了从该异常创建的错误。 否则,我们回退到这个异常构造函数的NAME。 NAME 仅用于报告目的。 NAME 中没有功能轴。 常见的情况应该是不要提供名称。
    翻译异常异常是递归的,因此你可以创建一个由当前异常包装的内部异常。
    数据对象提供要与这里异常关联的任何信息。 你会注意到,当屏幕截图选项被启用时,屏幕截图属性被添加到数据对象。 此外,浏览器属性也会添加到数据对象。
    选项选项在大多数情况下提供选项对象,defaultOptions就足够了,不需要这个属性。

    返回。

    词性说明
    异常创建的异常
    
    
    
    
    var foo = new ex.Exception("Oh no!");
    
    
    var bar = new ex.Exception(new Error("Oh no!");
    
    
    var baz = new ex.Exception("Oh no!", {
    
    
     name: "OverriddenExceptionName",
    
    
     innerException: foo,
    
    
     data: {
    
    
     foo: "bar"
    
    
     },
    
    
     options: new ex.Options().stacktrace(false).screenshot(false)
    
    
    });
    
    
    
    
    static 函数

    如果条件为 true,则引发异常。

    参数

    需要参数类型说明
    状态bool是的如果 true 抛出异常
    邮件字符串不是如果提供了消息,则创建一个异常。 返回到一般消息的回退。
    
    
    
    
    ex.Exception.throwIf(1 === 1, "Error message");
    
    
    
    
    reportIf

    如果条件为 true,则报告异常。

    参数

    需要参数类型说明
    状态bool是的在 true 中报告异常
    邮件字符串不是如果提供了消息,则创建一个异常。 返回到一般消息的回退。
    
    
    
    
    ex.Exception.reportIf(1 === 1, "Error message");
    
    
    
    
    方法 innerException

    获取内部异常

    返回。

    词性说明
    异常内部异常

    把 stacktrace

    返回。

    词性说明
    字符串stacktrace
    数据

    获取数据对象

    返回。

    词性说明
    对象数据对象
    命令行选项

    获取选项

    返回。

    词性说明
    选项异常的选项
    电子邮件名称

    获取名称

    返回。

    词性说明
    字符串异常的名称
    错误

    获取基础错误

    返回。

    词性说明
    错误基础错误
    电子邮件消息

    获取错误消息

    返回。

    词性说明
    字符串错误消息
    报告

    报告异常( 不 it )。 如果启用post请求选项,发布到 exception.js 平台,或者在启用报告回调选项时执行自定义报告功能,则报告异常涉及发出一个序列化异常对象。

    toSerializableObject

    将异常转换为更容易序列化的简单对象。

    返回。

    词性说明
    对象{ NAME: NAME,消息: 消息,stacktrace: stacktrace,数据:数据,innerException: 可以序列化内部异常对象,错误: 基础错误 }
    toJSONString

    将从toSerializableObject创建的可以序列化异常对象转换为JSON字符串。

    返回。

    词性说明
    字符串可以序列化异常对象的JSON字符串

    ArgumentException

    ArgumentException继承自异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"ArgumentException"而不是"异常。"使用ArgumentException引发或者报告无效参数。

    InvalidOperationException继承自异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是""而不是"异常。"使用来引发或者报告无效操作。

    NotImplementedException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。

    EvalException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 默认的错误将是 EvalError。

    RangeException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 默认的错误将是RangeError字体。

    ReferenceException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 默认的错误将是 ReferenceError。

    SyntaxException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 缺省错误将是 SyntaxError。

    TypeException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 默认错误将是 TypeError。

    URIException

    NotImplementedException继承了异常。它具有与异常相同的static 函数和方法。 但是,默认 NAME 是"NotImplementedException"而不是"异常。"使用NotImplementedException抛出或者报告未实现的执行代码的尝试。 默认的错误将是 URIError。

    ##createCustomException 使用createCustomException函数创建自定义异常类

    参数

    需要参数类型说明
    配置对象是的配置对象以创建自定义异常

    配置

    属性类型说明
    异常函数自定义异常的构造函数。 这里构造函数应调用它的异常的基构造函数。 为了便于调试,你可能希望这里函数具有名称。
    baseException异常自定义异常将从
    defaultOptions选项如果未指定其他选项,则默认情况下将对该异常使用的选项。 默认情况下,你将希望启用所有选项。

    返回。

    词性说明
    对象自定义异常。该类型将是你在 config.exception 属性中提供的函数。
    
    
    
    
    var ArgumentException = ex.createCustomException({
    
    
     exception: function ArgumentException(message, config) {
    
    
     if (!(this instanceof ArgumentException)) {
    
    
     return new ArgumentException(message, config);
    
    
     }
    
    
     ex.Exception.call(this, message, config);
    
    
     },
    
    
     baseException: ex.Exception
    
    
    });
    
    
    
    
    
    
    
    
    var FooArgumentException = ex.createCustomException({
    
    
     exception: function FooArgumentException(message, config) {
    
    
     if (!(this instanceof FooArgumentException)) {
    
    
     return new FooArgumentException(message, config);
    
    
     }
    
    
     ex.ArgumentException.call(this, message, config);
    
    
     },
    
    
     baseException: ex.ArgumentException,
    
    
     defaultOptions: new ex.Options().toggleAll(true).reportCallback(false)
    
    
    });
    
    
    
    

    ##handler 处理程序负责处理命中的错误,并指定包括 url。html2canvas.js url。post url ( 在报告错误时发出post请求)。post消息头。回调( 报告错误时执行的函数) 和回调函数在内的全局配置。

    static 属性

    处理程序的作用域选项。 选项为无。异常和所有选项。 将作用域设置为无信号表示处理程序将不会处理 window.onerror 中的任何内容。 将作用域设置为异常信号,以指示处理程序只能处理引发的异常,而不会引发任何其他异常。 将作用域设置为处理程序将处理 window.onerror 中所有内容的所有信号。

    static 函数作用域

    在 window.onerror 中执行时获取或者设置处理程序的作用域。 作用域指的是具有三个选项的handler.scopeOption: 无,异常和全部。将范围设置为无信号,该处理程序将无法处理 window.onerror 中的任何内容。 将作用域设置为异常信号,以指示处理程序只能处理引发的异常,而不会引发任何其他异常。 将作用域设置为处理程序将处理 window.onerror 中所有内容的所有信号。

    参数

    需要参数类型说明
    作用域int不是如果指定,设置处理程序作用域。 使用 window.handler.scopeOption。

    返回。

    词性说明
    处理程序scopeOption
    
    
    
    
    handler.scope(handler.scopeOption.all)
    
    
    
    
    保护

    获取或者设置将用于限制异常选项的保护。 参数

    需要参数类型说明
    guardGuard不是防止出现异常。重复异常或者任何其他不应该报告的异常的保护。

    返回。

    词性说明
    处理程序Guard
    
    
    
    
    ex.handler.guard(new ex.Guard()
    
    
     //Protect against a burst of exceptions where you're considering
    
    
     //a"burst" 10 exceptions in the last two seconds. This protection
    
    
     //will ensure that we'll never report more than 10 exceptions in a
    
    
     //2 second window.
    
    
    . protectAgainstBurst({ count: 10, seconds: 2 })
    
    
     //Protect against any situation you desire with the protectAgainst
    
    
     //funciton. We happen to be protecting ourselves from generating
    
    
     //a stacktrace for SyntaxExceptions. Note, this is an arbitrary
    
    
     //protection and not necessary. It is only used to show you can
    
    
     //protect against any situation and can turn on/off options individually.
    
    
    . protectAgainst(function (o, exception) {
    
    
     if (exception instanceof ex.SyntaxException) {
    
    
     o.stacktrace(false);
    
    
     }
    
    
     return o;
    
    
     }));
    
    
    
    
    html2canvasUrl

    获取或者设置拉 html2canvas.js.的url

    需要参数类型说明
    html2canvasUrl字符串不是指向 html2canvas.js的url

    返回。

    词性说明
    处理程序字符串
    stacktraceUrl

    获取或者设置拉 html2canvas.js.的url

    需要参数类型说明
    stacktraceUrl字符串不是指向 stacktrace.js的url

    返回。

    词性说明
    处理程序字符串
    reportPost

    获取或者设置在报告后发布序列化异常的配置。

    需要参数类型说明
    配置对象不是如何发送post请求以将异常发送到任意url的配置
    属性类型需要描述
    postUrl字符串是的post请求 url
    postHeadersarray不是带有 { bstrHeader的对象的array: ""。bstrValue:"值 }

    返回。

    词性说明
    处理程序配置
    reportCallback

    获取或者设置在报告异常时将执行的回调。

    需要参数类型说明
    回拨函数不是报告异常时将执行的回调。

    返回。

    词性说明
    处理程序函数
    reportToExceptionsjsPlatform

    启用到exceptionsjs平台的发布。 通过解析序列化异常并构建包含 stacktraces。截屏和额外信息的有用异常电子邮件,exceptionsjs平台处理你的Javascript错误。 https://exceptionsjs.com exceptionsjs平台的register。 只有启用了允许不安全报告的选项时,这里选项才有效。 如果启用了安全报告,则必须使用完整的oauth2进程将异常发送到excpetionsjs平台。 有关许多语言的有用库,请参见 https://exceptionsjs.com 插件,使提交异常与完整的oauth2过程更容易。

    需要参数类型说明
    配置对象不是指定要如何向exceptionsjs平台报告的配置对象
    属性类型需要描述
    宋体字符串不是将与exceptionsjs平台一起使用的外接程序
    字符串不是将接收异常的电子邮件地址

    返回。

    词性说明
    处理程序对象
    loadStacktraceJs

    异步加载 stacktrace.js

    loadHtml2Canvas

    加载脚本时异步加载 html2cavas.js 并执行回调。

    需要参数类型说明
    回拨函数不是当 html2canvas.js 加载时将执行的回调
    reportedExceptions

    获取所有报告异常。这包括所有带有 report()的exeptions报告和在 window.onerror 中使用 exeptions.handler的所有错误处理程序。

    retrieveReportedExceptionsCount

    helper 函数,以获取以前x 数秒内报告的异常( 请参见处理程序。reportedexceptions )的计数。

    需要参数类型说明
    int不是最后的秒数,我们关心的是异常。 如果没有指定,我们将使用自异常处理程序设置之后报告的异常总数。

    异常的##Options 选项。 Options,Options,post,post,post当报告异常时,将异常检索到指定 url,将异常发布到指定的url,发布异常的序列化JSON表示,将请求发布到指定的url。

    方法 stacktrace

    获取或者设置检索stacktrace选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用is选项,如果启用,则为 true。 如果启用启用,则禁用stacktrace选项。

    返回。

    词性说明
    选项bool
    屏幕截图

    获取或者设置检索屏幕截图选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用屏幕截图选项如果启用为 true。 如果启用为 false,则禁用屏幕截图选项。

    返回。

    词性说明
    选项bool
    reportPost

    获取或者设置检索日志选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用时通过post请求选项向任意url报告,如果启用为 true。 如果启用为 false,则禁用该选项。

    返回。

    词性说明
    选项bool
    reportCallback

    获取或者设置报表回调选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用 true 时启用回拨选项。 如果启用为 false,则禁用回拨选项。
    reportToExceptionsJsPlatform

    获取或者将报表设置为exceptionsjs平台选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用后,启用投递到 reportToExceptionsJsPlatform。 如果启用了 false,则禁用reportToExceptionsJsPlatform选项。

    返回。

    词性说明
    选项bool
    DOMDump

    获取或者设置DOM转储选项。

    需要参数类型说明
    启用bool不是如果未定义则返回当前选项。 启用时启用DOM转储选项( 如果启用)。 如果启用了 false,则禁用DOM转储选项。

    返回。

    词性说明
    选项bool
    toggleAll

    根据启用参数切换所有选项

    需要参数类型说明
    启用bool不是如果 true 启用所有选项。 如果 false 或者未定义,则禁用所有选项。

    返回。

    词性说明
    选项选项对象

    执行异常操作的##Guard 有时开销很大或者多余。 例如如果你在一行中遇到 10错误,则可能不希望对页面进行屏幕截图,因为这可能导致noticable性能错误。 指定带有 ex.handler.guard()的保护以禁用不希望执行的异常选项。 守卫为所有报告的异常限制选项。

    protectAgainstBurst

    如果超过了报告的计数阈值,则禁用异常选项。 有关我们如何定义报告的异常的更多信息,请参见 handler.reportedExceptions。

    需要参数类型说明
    配置对象是的指定你希望如何保护页面免遭意外异常的配置对象
    属性类型需要描述
    计数数int是的不能超过的阈值,以免禁用异常选项。
    int不是最后的秒数,我们关心的数。 如果没有指定,我们将使用自异常处理程序设置之后报告的异常总数。
    optionsFunc函数不是启用/禁用并返回在超出异常阈值的情况下的选项。 如果没有指定,我们将禁用异常的所有选项。 你可能只希望禁用这里函数中的选项。

    返回。

    词性说明
    Guard守卫
    
    
    
    
    ex.handler.guard(new ex.Guard()
    
    
    . protectAgainstBurst({
    
    
     count: 10,
    
    
     seconds: 2,
    
    
     optionsFunc: function (o) { return o.stacktrace(false); }
    
    
     }));
    
    
    
    
    protectAgainst

    使用指定的限制函数禁用异常选项。 注意:请参阅 window.handler.retrieveReportedExceptionsCount 和 window.handler.reportedExceptions 以获得易用性实用程序。

    需要参数类型说明
    restrictFunc函数是的禁用异常选项并返回选项对象的函数。 该函数将接收两个参数: 异常的当前选项和异常本身。 它应该返回提供的选项对象。

    返回。

    词性说明
    Guard守卫
    
    
    
    
    ex.handler.guard(new ex.Guard()
    
    
     //Protect against a burst of exceptions where you're considering
    
    
     //a"burst" 10 exceptions in the last two seconds. This protection
    
    
     //will ensure that we'll never report more than 10 exceptions in a
    
    
     //2 second window.
    
    
    . protectAgainstBurst({ count: 10, seconds: 2 })
    
    
     //Protect against any situation you desire with the protectAgainst
    
    
     //funciton. We happen to be protecting ourselves from generating
    
    
     //a stacktrace for SyntaxExceptions. Note, this is an arbitrary
    
    
     //protection and not necessary. It is only used to show you can
    
    
     //protect against any situation and can turn on/off options individually.
    
    
    . protectAgainst(function (o, exception) {
    
    
     if (exception instanceof ex.SyntaxException) {
    
    
     o.stacktrace(false);
    
    
     }
    
    
     return o;
    
    
     }));
    
    
    
    

    STA  rep  REPO  Report  DOM  堆栈  
    相关文章