Readme for jsErrLog

What is this?

jsErrLog is a simple JavaScript script that catches your in-browser JavaScript errors and posts them to the jsErrLog Service. This enables you to always be on top of your JavaScript errors.

jsErrLog Service Homepage and demo site: http://jserrlog.appspot.com (note: the demo site may be out of sync with the code here, so mix'n'match at your own risk)

How to use

Insert

<script type="text/javascript" src="jserrlog.js"></script>

directly after your browsers <head> tag. You may optionally, directly after the script tag, add additional parameters to the error report handling:

<script type="text/javascript">
    // Configure site parameters
	// Optional to allow the error message to also be presented to the user
    //jsErrLog.debugMode = true;
    // Optionally add additional debug information to the jsErrLog.info
    // message field
    //jsErrLog.info = "Populated the Info Message to pass to logger"
    // Optionally specify URL to which the logging should be done
    //jsErrLog.url = "http://www.myservice.com/logger.js";
	// Optionally specify certain querystring parameters never to pass to the logging service
	// either on the fileloc or the server name. Simply list them in the array
	// and script will check for them (case insensitive)
	//jsErrLog.qsIgnore = ["userid","password"];
	// If you want to ignore certain domains from reporting (eg Twitter API) add them to
	//jsErrLog.domainIgnore = ["http://ignore.domain.com","https://do.not.track.net"]
	// Limit number of errors that will be sent for a page (default is 10, -1 allows infinite)
	//jsErrLog.maxRep = 10;
</script>

The options are:

jsErrLog.debugMode: Set to true if you'd like the web browser not to swallow in-browser errors.
jsErrLog.info: A custom string bundled with the HTTP GET request. Can be used to add additional information, such as a customer number, extra state or similar.
jsErrLog.url: The absolute URL to which GET requests will be made. See below for more information on how to do this. If not specified, the jsErrLog.url will default to http://jserrlog.appspot.com/logger.js
jsErrLog.qsIgnore: populates an array of querystring parameters to be stripped before reporting
jsErrLog.domainIgnore: populates an array of prefixes that will be ignored on file location before reporting, can be used to avoid reporting on ad server or 3rd party sites - for example jsErrLog.domainIgnore = ["http://api.twitter.com","http://api.maps.google.com"];
jsErrLog.maxRep: Max number of errors that will be reported for a page

Which web browsers does this script support?

IE 6.0 and above. IE10+ supports colNo on error reports
Firefox 3.6.22 and above
Chrome 10 and above (including ChromeOS and on Android). Chrome 30+ supports colNo on error reports
Safari 5.1 and above / WebKit nightlies (thought this error needs resolving.)
Opera v11.60 (and Opera.Next v12) with Presto/2.10.229 JS engine and above

Un-supported browsers at this time

Android

Additional information

Original blog posts are available here.

If your browser is not in the list above, please consider opening up the jsErrLog demo page (src/demo/index.html) to help us verify whether the script works in your browser or not.

How to point jsErrLog to your own service

There are a couple of cases when you might want to host your own jsErrLog server that receives all the errors on your site:

You are worried about security. This includes:
That user credentials might get passed to the appspot service and be publicly available for others to view as long as they know your full domain URL.
That the response JavaScript file in the future might contain malicious code that enables cross site scripting attacks (XSS).
You would like to have the errors e-mailed to you directly.
You would like to incorporate the error messages into your existing company workflow. Two examples are
Sending out an e-mail to one or multiple people about the error.
Adding the JavaScript to some ticketing system.
You are on an Intranet that blocks communication out to the WWW.

To roll your own jsErrLog service there are two things you need to do:

Override the default URL that the jsErrLog browser script should use.
Implement your server side engine to handle the requests coming in from browsers.

Overriding the default URL

This one is easy. Just set the jsErrLog.url to something similar to the URL of your error logger. A full example here below:

<script type="text/javascript" src="jserrlog.js"></script>
<script type="text/javascript">
    jsErrLog.url = "http://www.myownservice.com/logger.js";
</script>

note that it is recommended for the URL to end with '.js'. Also note that it must support HTTP GET requests.

Implementing your own logging service

For every client side (in-browser) JavaScript error, an HTTP GET request is is being made to the URL you specified. Every request contains the following parameters:

i: A unique identifier that identifies the a temporary <script /> tag added to your <head> … </head>. This identifier is used in the response back to the client. See more on this below.
sn: The document.URL at which the error occured.
fl: The JavaScript file in which the error occurred.
ln: The line number in fl on which the error occurred.
cn: The col number in fl on which the error occurred.
err: A string describing the error.
ui: A (most certainly) unique string for your error message. It is being generated according to RFC 4112, section 4.4.
info: The optionally specified jsErrLog.info string set when loading the page.

You can verify that the format of the parameters using a tool such as Fiddler to watch the messages as they are sent over http.

The response given by your service must be valid JavaScript. This is very important, as it otherwise might lead to a flood of requests coming in as one JavaScript yields another one (and each one a new request).

Generally it is good to clean up in the client's DOM. This is done by adding the following line in your response body:

jsErrLog.removeScript(<?=$_GET['i']?>);

where (which is PHP) can be substituted with your language specific way of extracting the value of the GET parameter i.

You may also add additional JavaScript in your response if you want to. You could for example show a simple alert(…) box telling the user that the error has been logged and that you are looking into it. However, do note that the alert box might pop up multiple times being both annoying and/or making the browser unusable if stuck in a bad loop. Another option would be to have a 'soft popup' show up in the client's web interface.

Also, note that not all JavaScript errors will always be errors that the user will notice. Maybe he/she will never click on the button that would trigger the broken callback function etcetera.

Contribute

This project can be forked from Github. Please issue pull requests from feature branches.

License

Copyright © 2014 This work is free. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See the COPYING file or http://www.wtfpl.net/ for more details.

jainprash/jsErrLog