Javascript Library Documentation

For any web site or web app we highly recommend using our JustLog.IT Javascript library in your pages. Our pre-built library wraps all the logging functionality. Track actions, performance, and make sure you are logging any script errors.

Getting Started

Add the following script block into your web site or application. This script will initialize the JustLog.IT javascript library, initializing it properly. The only thing you need to do is add the logging token in from your application settings.

<script type="text/javascript">
   (function (token) {
       function append(scriptid, url, async) {
           var d = document, sn = 'script', f = d.getElementsByTagName(sn)[0];
           if (!f) f = d.head;
           var s = d.createElement(sn);
           s.async = async;
           s.id = scriptid;
           s.src = url;
           f.parentNode.insertBefore(s, f);
       }
       if (!window.justlogit) window.justlogit = {};
       window.justlogit.token = token;
       window.justlogit.userid = 'web user id';
       window.justlogit.dnt = false;
       window.justlogit.handleGlobalErrors = true;
       append('justlogit', '//cdn.justlog.it/justlogit.min.js', false);
   })('your token here');
</script>

That's it. Our library doesn't have any external dependencies so you're good to go.

Library Details

The following are the Properties and Methods available in the JLI Javascript library.

Properties

These are the public properties available on the logging object. To access the object use the window.justlogit parent object.

token
This is the logging token for the current application.
userid
Your identifier for the current user. This should be some kind of value that allows you to map them to your other systems.
handleGlobalErrors
If this is true it will enable global error logging, so any errors not caught and handled will get logged here.
generateRandomId
JustLog.IT will generate a random identifier for the current user if you enable this and have not assigned your own user identifier. This isn't perfect but it will help to correlate the actions from the current user.

Methods

This is the list of methods on the logging interface you can call to store values from your running web application.

logPerformance(start, end, name, additionalValues)
Logs a performance record. Performance is calculated by taking the start and endtimestamps (Date objects) and getting the millisecond difference between them.
Parameters
  • start - the starting date object
  • end - the ending date object
  • name - the name to give the performance log. Typically a method or action name.
  • additionalValues - (optional) an object structure containing key:value pairs to be added to the log with the timing.
logEvent(name, details, additionalValues)
Log some action or event you want to track.
Parameters
  • name - the name to give the performance log. Typically a method or action name.
  • details - (optional) any additional description to provide for the event.
  • additionalValues - (optional) an object structure containing key:value pairs to be added to the log with the timing.
logError(err, details, additionalValues)
Logs the details of an error. The error object is expected to have thedefault error object properties (message and stack)
Parameters
  • err - the error object.
  • details - (optional) an additional description of the error.
  • additionalValues - (optional) an object structure containing key:value pairs to be added to the log with the timing.
logInformation(method, details, additionalValues)
Logs an information record. These information entries are useful to provide extra contextaround things like errors.
Parameters
  • method - the name of the method where the information is being logged from.
  • details - information details which can be used for debugging information.
  • additionalValues - (optional) an object structure containing key:value pairs to be added to the log with the timing.
enableUserTracking()
Enables user tracking which will allow you to correlate logged items to specificusers. By default user tracking is disabled. Details on how user tracking works is in a following section.
setUserMarker(marker)
Allows you to set the specific user marker you want to use to correlate any actionsto a specific user. This can be a user identifier from your system or any other type of value you want to use. When you set this value it turns on User Tracking at the same time.
Parameters
  • marker - the user identifier you want to use for the current user. Note this is a legacy function. You can, and probably should, use the global userid property (described under the properties section).
doNotTrack(value)
To support newer privacy laws we have put in a Do Not Track setting for the justlog.it script library. When DNT is enabled we store less information about the connecting user to maintain their privacy.
Parameters
  • value - boolean value indicating whether do not track should be enabled

Calling Methods

When our script initially executes (loads) it will attach a global logging object to the window object. Thisglobal object is called justlogit.

To call logging methods from anywhere in your javascript code by making the following call: window.justlogit.

ex: window.justlogit.logError(err);

How it Works

This section provides some details on how the Javascript library interfaces withthe JustLog.IT REST-ful API. This section is here to answer any questions you may have on how this works in case you have concerns around it.

When logging errors the Javascript library executes a POST call using the XMLHttpRequestjavascript object. The passed in error object is processed into a json object structure and posts it to the error logging endpoint.

All other logging calls use a light-weight mechanism to trigger a GET request to feed the detailsto the logging system. This mechanism is typically referred to as a Pixel Drop. A Pixel Drop forces a GET request by writing a hidden image to the html dom using javascript. The source (src) value for the image is the url plus query string for the logging system. The reason this is lighter weight than using an XMLHttpRequest object is it puts the load onto the browsers dom processor instead of the javascript engine. Most browsers handle async resource requests very efficiently.

User Correlation / Tracking

In order to really have visibility into what is happening with your application it is important to be able to correlate actions to your specific users. This helps in troubleshooting errors, looking for performance issues, and tracking flows through your app.

To track your users the best option is for you to provide us with a unique user identifier. For example, the same identifier you use to track them after they have logged in. There are 2 options to set this up. First you can assign the id as the script loads:
window.justlogit.userid = 'your id';
Or you can call the following method:
window.jsutlogit.setUserMarker('your id');

User tracking is enabled by default. And if you don't provide an identifier our script will automatically generate a "correlation id". The correlation id is just a random number that we attempt to store in a cookie and use for future visits from this user. It allows us to try and track user flows even without a specific identifier. This allows for some basic correlation even on your web site where users do not log in or provide an identifier.

If you want to disable user tracking, you can do this as the script loads by setting this variable:
window.justlogit.dnt = true;
Or you can call the following method:
window.jsutlogit.doNotTrack(true);

Turning off tracking does not prevent log entries from being sent. It prevents personally identifiable information (PII) from being stored with the logged information. It also prevents the system from attempting to geo-locate the information beyond the country level. It will also prevent any user identifier from being passed with the log entries. Obviously this will significantly reduce the usefulnes of the user activity tracking, making it very difficult to look at user flows.

Logging Page Load Times

A very common thing you might want to do is log the load times for your web pages. Slow web pages aredefinitely the bane of web users and something that has been proven to directly, negatively, impact revenue on sites due to users leaving.

Our javascript library can be used to log page load speeds with reasonable accuracy. Note that the only wayto get 100% accurate load times is from the browser since it controls the entire load. Load times recorded by scripts are less accurate as they require the start time of the load to be recorded after the page starts loading.

That said you can get a decent level of accuracy by following these steps:

  • As soon as possible (ideally in the <head> section of your page) capture the current timestamp:
    ex: var start = new Date();
  • Somewhere on the page hook the window.load event so you know when the DOM is ready:
    ex: window.load = function () { var loaded = new Date(); }
    You can also use the JQuery primary callback function to log this timestamp.
  • After the window load event fires and you have captured the load finished time you will call thelogPerformance method on the justlogit window object.
    ex: justlogit.logPerformance(start, loaded, 'Page Name - Load');

That call will log the performance of the page load, at least up to the point where the DOM is ready, so allinitial resource calls have completed. In addition we will automatically capture values such as the user agent so you can see which browser this applies to and the location of the request so you can correlate slower performance with location if necessary.

close
Sign up to get started