Agent Methods

The following methods are available on the TrackJS namespace (since 3.0.0) or the trackJs namespace for earlier versions.

WARNING If you are referencing the agent as a separate script, you should perform a safety check for the existence of the TrackJS namespace before calling any function. This will prevent your code from failing if the agent is blocked by a third-party.

addMetadata

Function

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 give you the capability to filter the Dashboard in your own way.

If the metadata key already exists, it will be updated with the new value. See removeMetadata.

Example

if (window.TrackJS) {
    TrackJS.addMetadata("user_subscription", "professional");
    TrackJS.addMetadata("user_role", "owner");
    TrackJS.addMetadata("server", "YOUR_SERVER_ID");
}

Copy

import { TrackJS } from "trackjs";
TrackJS.addMetadata("user_subscription", "professional");
TrackJS.addMetadata("user_role", "owner");
TrackJS.addMetadata("server", "YOUR_SERVER_ID");

Copy

if (window.trackJs) {
    trackJs.addMetadata("user_subscription", "professional");
    trackJs.addMetadata("user_role", "owner");
    trackJs.addMetadata("server", "YOUR_SERVER_ID");
}

Copy

attempt

Function

Invoke a function with a try-catch wrapper and report any errors to TrackJS. Context to invoke the function and parameters can be passed as additional parameters.

Example

TrackJS.attempt(function multiply(a, b) {
    return a*b;
}, {}, 4, 8); // 32

Copy

import { TrackJS } from "trackjs";
TrackJS.attempt(function multiply(a, b) {
    return a*b;
}, {}, 4, 8); // 32

Copy

trackJs.attempt(function multiply(a, b) {
    return a*b;
}, {}, 4, 8); // 32

Copy

configure

Function

Update the Agent Config after install. Not all options can be updated, see the Changeable flag in the Config SDK.

Example

window.TrackJS && TrackJS.configure({
    userId: "sam@customer.com",
    sessionId: "17734FEB342"
});

Copy

import { TrackJS } from "trackjs";
TrackJS.configure({
    userId: "sam@customer.com",
    sessionId: "17734FEB342"
});

Copy

window.trackJs && trackJs.configure({
    userId: "sam@customer.com",
    sessionId: "17734FEB342"
});

Copy

console.log

Function

Record a Telemetry event into the log with default severity. The TrackJS.console.log function is a private clone of the global console.log for context that is relevant for debugging, but should not be displayed in the browser console.

Example

window.TrackJS && TrackJS.console.log("it's happening!", { foo: "bar" });

Copy

import { TrackJS } from "trackjs";
TrackJS.console.log("it's happening!", { foo: "bar" });

Copy

window.trackJs && trackJs.console.log("it's happening!", { foo: "bar" });

Copy

console.debug

Function

Record a Telemetry event into the log with debug severity. The TrackJS.console.debug function is a private clone of the global console.debug for context that is relevant for debugging, but should not be displayed in the browser console.

Example

window.TrackJS && TrackJS.console.debug("it's happening!", { foo: "bar" });

Copy

import { TrackJS } from "trackjs";
TrackJS.console.debug("it's happening!", { foo: "bar" });

Copy

window.trackJs && trackJs.console.debug("it's happening!", { foo: "bar" });

Copy

console.info

Function

Record a Telemetry event into the log with info severity. The TrackJS.console.info function is a private clone of the global console.info for context that is relevant for debugging, but should not be displayed in the browser console.

Example

window.TrackJS && TrackJS.console.info("it's happening!", { foo: "bar" });

Copy

import { TrackJS } from "trackjs";
TrackJS.console.info("it's happening!", { foo: "bar" });

Copy

window.trackJs && trackJs.console.info("it's happening!", { foo: "bar" });

Copy

console.warn

Function

Record a Telemetry event into the log with warning severity. The TrackJS.console.warn function is a private clone of the global console.warn for context that is relevant for debugging, but should not be displayed in the browser console.

Example

window.TrackJS && TrackJS.console.warn("it's happening!", { foo: "bar" });

Copy

import { TrackJS } from "trackjs";
TrackJS.console.warn("it's happening!", { foo: "bar" });

Copy

window.trackJs && trackJs.console.warn("it's happening!", { foo: "bar" });

Copy

console.error

Function

Record a Telemetry event into the log with error severity. The TrackJS.console.error function is a private clone of the global console.error for context that is relevant for debugging, but should not be displayed in the browser console.

If the console.error option is on, which is the default, this will also send an error report.

Example

window.TrackJS && TrackJS.console.error("it's happening!", { foo: "bar" });

Copy

import { TrackJS } from "trackjs";
TrackJS.console.error("it's happening!", { foo: "bar" });

Copy

window.trackJs && trackJs.console.error("it's happening!", { foo: "bar" });

Copy

install

Function

Installs the agent into the current document and start reporting errors with the provided Config options.

Before 3.0.0, initializing the agent was automatic as soon as the script was loaded. Config was passed by creating a window._trackJs object with the properties.

Example

window.TrackJS && TrackJS.install({
    token: "YOUR_TOKEN"
    // other config options
});

Copy

import { TrackJS } from "trackjs";
TrackJS.install({
    token: "YOUR_TOKEN"
    // other config options
});

Copy

<script>
window._trackJs = {
    token: "YOUR_TOKEN"
    // other config options
};
</script>
<script src="https://cdn.trackjs.com/releases/current/tracker.js"></script>

Copy

isInstalled

Function

Whether the agent has been installed into the current environment. See install.

Example

window.TrackJS && !TrackJS.isInstalled() && TrackJS.install({
    token: "YOUR_TOKEN"
    // other config options
});

Copy

import { TrackJS } from "trackjs";
if (!TrackJS.isInstalled()) {
    TrackJS.install({
        token: "YOUR_TOKEN"
        // other config options
    });
}

Copy

<script>
window._trackJs = {
    token: "YOUR_TOKEN"
    // other config options
};
</script>
<script src="https://cdn.trackjs.com/releases/current/tracker.js"></script>

Copy

removeMetadata

Function

Removes a key, and any associated value, from the metadata store for this page session. The key will no longer be included with reported errors.

See addMetadata.

Example

if (window.TrackJS) {
    TrackJS.removeMetadata("user_subscription");
}

Copy

import { TrackJS } from "trackjs";
TrackJS.removeMetadata("user_subscription");

Copy

if (window.trackJs) {
    trackJs.removeMetadata("user_subscription");
}

Copy

track

Function

Reports an error to TrackJS immediately with the provided error. If the parameter is not an Error, one will be generated using the serialized parameter as the message.

The reported error will include all Telemetry logged by the agent.

Example

window.TrackJS && TrackJS.track("State.property should be positive");

Copy

import { TrackJS } from "trackjs";
TrackJS.track("State.property should be positive");

Copy

window.trackJs && trackJs.track("State.property should be positive");

Copy

version

String

The version of the agent.

Example

window.TrackJS && TrackJS.version; // 3.0.0

Copy

import { TrackJS } from "trackjs";
TrackJS.version; // 3.0.0

Copy

window.trackJs && trackJs.version; // 3.0.0

Copy

watch

Function

Creates a wrapper around a function that automatically reports any errors that occur. Context for the function can be passed as additional argument.

Example

var protectedFn = TrackJS.watch(function(a, b) {
    throw new Error("oops");
}, this);

protectedFn(1, 2); // Error is reported and rethrown as "TrackJS Caught: oops"

Copy

import { TrackJS } from "trackjs";
var protectedFn = TrackJS.watch(function(a, b) {
    throw new Error("oops");
}, this);

protectedFn(1, 2); // Error is reported and rethrown as "TrackJS Caught: oops"

Copy

var protectedFn = trackJs.watch(function(a, b) {
    throw new Error("oops");
}, this);

protectedFn(1, 2); // Error is reported and rethrown as "TrackJS Caught: oops"

Copy

watchAll

Function

Replaces all the functions on an object with watch wrappers of all the functions. This is useful for watching all the methods on a Class.

Example

var protectedModel = TrackJS.watchAll(myModel);
protectedModel.foo(1, 2); // Errors will be reported and rethrown

Copy

import { TrackJS } from "trackjs";
var protectedModel = TrackJS.watchAll(myModel);
protectedModel.foo(1, 2); // Errors will be reported and rethrown

Copy

var protectedModel = trackJs.watchAll(myModel);
protectedModel.foo(1, 2); // Errors will be reported and rethrown

Copy