Readme for jsErrLog
What is this?
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
directly after your browsers
<head> tag. You may optionally, directly
after the script tag, add additional parameters to the error
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
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.
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.
- 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.
- 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:
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
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.
document.URLat which the error occured.
ln: The line number in
flon which the error occurred.
cn: The col number in
flon 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.infostring 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.
Generally it is good to clean up in the client's DOM. This is done by adding the following line in your response body:
(which is PHP) can be substituted with your
language specific way of extracting the value of the GET parameter
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.
This project can be forked from Github. Please issue pull requests from feature branches.
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.