Agent Methods

The following methods are available on the TrackJS namespace of the trackjs-node published module.

addMetadata

Function

Add one or more key-value pairs of strings to describe the current context. 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.

Metadata can also be added during install via options.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

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

Copy

configure

Function

Update the Agent Options after install.

Example

import { TrackJS } from "trackjs-node";

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

Copy

addLogTelemetry

Function

Record a Telemetry console event into the log. Messages sent to this method will not be seen in the global console. If severity is "error", an Error will be captured by the agent.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.addLogTelemetry("info", "my info message", { state: "bar" });

Copy

Handlers.expressErrorHandler

Function

Return an error handler for Express middleware. See Express Integration.

Agent must be installed. See install.

Example

import express from "express";
import { TrackJS } from "trackjs-node";

var app = express()
  // your other handlers
  .use(TrackJS.Handlers.expressErrorHandler({ next: false }));

Copy

Handlers.expressRequestHandler

Function

Return an request handler for Express middleware. See Express Integration.

Agent must be installed. See install.

Example

import express from "express";
import { TrackJS } from "trackjs-node";

var app = express()
  .use(TrackJS.Handlers.expressRequestHandler({ correlationHeader: true }))
  // your other handlers

Copy

install

Function

Installs the agent into the current environment with the provided options.

If the agent has already been installed, it will throw a TrackJSError.

options.token is required, and the method will throw a TrackJSError if omitted.

See uninstall.

Example

import { TrackJS } from "trackjs-node";

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

Copy

isInstalled

Function

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

Example

import { TrackJS } from "trackjs-node";

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

Copy

onError

Function

Attaches a custom error handler to the agent. Use custom handlers to intercept Error Payloads to change their values or prevent them from being captured. Error handlers will be executed in the order that they are attached. Once an error is ignored, no further error handlers will be notified.

Error handler functions take a single payload argument which will be a Capture Payload object. The handler function returns a boolean where true signals the error should continue and false prevents it from being captured.

Error handlers can also be attached during install via options.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.onError((payload) => {
  // re-writing the application based on message value
  if (payload.message.indexOf("foo") >= 0) {
    payload.application = "foo-app"
  };
  return true;
});

TrackJS.onError((payload) => {
  // ignoring errors that come from an ad
  if (payload.url.indexOf("ads.") >= 0) {
    return false;
  }
  return true;
});

Copy

removeMetadata

Function

Removes one or more keys from the metadata store. The key will no longer be included with reported errors.

See addMetadata.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.removeMetadata("user_subscription");
TrackJS.removeMetadata({
    "user_role": false,
    "server": false
});

Copy

track

Function

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

Options can be provided which will override the agent options for this error only. This is useful if you want to include metadata unique to this request, or reroute it to a different application dashboard.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.track(new Error("oops"));
TrackJS.track({ custom: "object" });
TrackJS.track(new Error("oops"), { application: "myapp", metadata: { "module": "olympus" }});

Copy

uninstall

Function

Removes the agent from the current environment.

See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.uninstall();

Copy

usage

Function

Captures a “page-view” usage metric for the TrackJS Dashboard. Useful to understand how active the code is when correlating with error rates.

This API is likely to change as the Node client develops.

Agent must be installed. See install.

Example

import { TrackJS } from "trackjs-node";

TrackJS.usage();

Copy