Top Level API

TrackJS will automatically track many errors. Often the default settings and behavior are good enough. However, there may be times when you wish to manually track errors or wrap certain critical functions. For these use cases, we provide a top-level API.

Important! If you’re using our CDN to host the tracker script (as opposed to bundling), please check for the existence of the global trackJs object before invoking API calls. Networks are not reliable so there’s always a small chance of load failure. Additionally, some aggressive ad blockers will prevent our script from loading off the CDN. The easiest way to prevent issues is to bundle our script with yours.

You may certainly continue to use our CDN, but please use the following test for the trackJs global object before invoking API calls:

// Quick check to make sure trackJs has loaded.
window.trackJs && trackJs.track(someError)

Functions

trackJs.track()

Directly invoke TrackJS to transmit an error with the provided message. The message can be of any type. If it is not a string, it will be passed through the serialize function before transmission. If it is an Error, the details and stacktrace will be recorded.

The resulting error will include any logs that may have been captured from console, network, or visitor.

/**
  * Directly invokes an error to be sent to TrackJS.
  *
  * @method track
  * @param {Error|String} error The error to be tracked. If error does not have a stacktrace, will attempt to generate one.
  */
trackJs.track("Logical error: state should not be null");

try {
  // do something
} catch (e) {
  trackJs.track(e);
}

trackJs.attempt()

Invoke a function within a try/catch wrapper to automatically capture any errors that may arise. Context and arguments to the function can be passed as additional parameters.

/**
  * Invokes the provided function within a try/catch wrapper
  * that forwards the error to TrackJS.
  *
  * @method attempt
  * @param {Function} func The function to be invoked.
  * @param {Object} context The context to invoke the function with.
  * @param {...} Additional arguments passed to the function.
  * @returns Output of the function.
  */
trackJs.attempt(function (a, b) {
  throw new Error("oops");
}, this, "5", "50");
// Error is tracked and rethrown

trackJs.addMetadata(key, value)

Add a key-value pair of data that will describe errors captured in this page view. You can use this to track any arbitrary data that is interesting for you, such as whether it is a paying customer, their transaction id, or anything else.

These metadata key-values are sent with each error and the UI will give you tools to group and filter them.

/**
  * addMetadata
  * Adds a new key-value pair to the metadata store. If the key already exists
  * it will be updated.
  *
  * @param {String} key
  * @param {String} value
  */
trackJs.addMetadata("customerType", "awesome");

trackJs.removeMetadata(key)

You can also remove a key from the metadata, in case the user takes some action during the session that invalidates it.

/**
  * removeMetadata
  * @method
  * Removes a key from the metadata store, if it exists.
  *
  * @param {String} key
  */
trackJs.removeMetadata("customerType");

trackJs.configure()

Update the TrackJS configuration after initialization. Not all parameters are available to be updated after initialization.

/**
  * Configures the instance of TrackJS with the provided configuration.
  *
  * @method configure
  * @param {Object} params The Configuration object to apply
  * @returns {Boolean} True if the configuration was successful.
  */
trackJs.configure({

  // Custom session identifier.
  sessionId: "",

  // Custom user identifier.
  userId: "",

  // Custom application identifier.
  version: ""

});

trackJs.console

Record an event into the Telemetry Timeline log with appropriate severity. Any objects passed into the function will be serialized. These will honor any custom serializer setup in the configuration.

/**
  * Records a debug event into the rolling event log.
  *
  * @method debug
  * @param {Any} ... Arguments to be recorded.
  */
trackJs.console.debug("a message"); // debug severity
trackJs.console.log("another message"); // log severity

trackJs.console.error()

Record an event into the Telemetry Timeline log with error severity. This will also fire an error to our servers in the default case. This can be customized. Any objects passed into the function will be serialized.

/**
  * Records a error event into the rolling event log, and flushes the log
  * to TrackJS with an error.
  *
  * @method error
  * @param {Any} ... Arguments to be recorded.
  */
trackJs.console.error("a message");

trackJs.watch()

Return a wrapped and watched version of a function that will automatically capture any errors that may arise. Context for the function can be passed as additional argument.

/**
  * Returns a wrapped and watched version of the function to automatically
  * catch any errors that may arise.
  *
  * @method watch
  * @param {Function} func The function to be watched.
  * @param {Object} context The context to invoke the function with.
  * @returns Output of the function.
  */
var wrappedFn = trackJs.watch(function (a, b) {
  throw new Error("oops");
}, this);

wrappedFn("5", "50");
// Error is tracked and rethrown

trackJs.watchAll()

Replace all of the functions on an object with watched versions of the functions that will automatically capture any errors that may arise. Context for the functions will be bound to the object.

/**
  * Wrap and watch all of the functions on an object that will
  * automatically catch any errors that may arise.
  *
  * @method watch
  * @param {Object} obj The object to inspect for functions.
  * @returns {Object} watched object.
  */
trackJs.watchAll(myModel);

var thing = trackJs.watchAll(new Thing());

trackJs.version

Get the current version of the TrackJS script.

trackJs.version; // 2.1.5