Javascript Library Documentation

To simplify adding JustLog.IT logging into your web sites and web applications we have created an easy-to-use Javascript wrapper library. This section outlines how it functions and how to integrate into your websites.

Getting Started

Follow these steps to add our Javascript library to your web site or web application. These steps assume you have already set up your web application as an Application in JustLog.IT.

  • 1. Set a reference to our script: //cdn.justlog.it/justlogit.min.js
  • 2. Add the logging token to the script call. <script src='//cdn.justlog.it/justlogit.min.js' token='000000'></script>

That's it. You do not need to add any additional libraries (jQuery, Angular, etc.) to support this. JustLog.IT uses native javascript functions supported by almost all browsers.

Calling Methods

When our script initally executes (loads) it will attach a global logging object to the window object. This global 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);

Methods

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

MethodParametersDescription
logPerformance
  • start - the Date object marking the start time
  • end - the Date object marking the end time
  • method - the name of the method being tracked
Logs a performance record. Performance is calculated by taking the start and end timestamps (Date objects) and getting the millisecond difference between them.
logEvent
  • name - the name of the event
  • details - (optional) any additional details about the event
Logs an event occurrence for the application.
logError
  • err - the error object caught in your try/catch block
  • details - (optional) any details you want to add to the error being logged.
Logs the details of an error. The error object is expected to have the default error object properties (message and stack)
logInformation
  • method - the method name the details apply to
  • details - the details you want to log.
Logs an information record. These information entries are useful to provide extra context around things like errors.
enableUserTrackingn/aEnables user tracking which will allow you to correlate logged items to specific users. By default user tracking is disabled. Details on how user tracking works is in a following section.
setUserMarker
  • marker - the user identifier you want to use for the current user
Allows you to set the specific user marker you want to use to correlate any actions to 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.
doNotTrack
  • value - boolean value indicating whether do not track should be enabled
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.

How it Works

This section provides some details on how the Javascript library interfaces with the 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 XMLHttpRequest javascript 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 details to 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

One of the things that sets our logging system apart is we have designed our system with user correlation as a first-class citizen. In order to effectively troubleshoot issues and hunt down performance issues knowing which user(s) are being affected is incredibly helpful.

However we do not enable this type of tracking by default. The main reason for this is to allow our customers to more easily comply with some stringent privacy regulations such as the GDPR regulation which imposes substantial penalties for non-compliance. In addition, we don't know automatically the best way to identify your users so need you to provide us with that identifier.

To enable user tracking you call either the enableUserTracking or setUserMarker methods on the logging library. Either of these will enable user tracking and add the user properties to the submissions, which is why that is not a parameter in the logging method calls.

If you call the enableUserTracking method and not the setUserMarker method the Javascript library will create a unique-ish marker we can use to track users. This is most helpful on websites where you probably don't have logged in users. This marker will be appended to the logging submissions and will provide a mechanism to correlate things such as user actions. This marker is added to a cookie (__jilmarker) so it can persist across pages and visits for better correlation.

Common Issues

Missing Token
Probably the most common issue encountered is missing the token on the script tag. If the token is missing no logging calls will occur.

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 are definitely 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 way to 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 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 the logPerformance 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 all initial 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
Get started with two months free.