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.

param 1 object dictionary of key-value pairs OR
param 1 string Metadata key
param 2 string Metadata value for this page session.
returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

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

configure

Function

Update the Agent Options after install.

param 1 TrackJSOptions Options to be updated
returns boolean true if successful
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

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

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.

param 1 string Severity level. “log”,”debug”,”info”,”warn”,”error”
param …n Any properties to be logged
returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

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

Handlers.expressErrorHandler

Function

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

Agent must be installed. See install.

param 1 Object Options for the handler
Options.next Boolean Whether to pass errors on to the next handler. If you do not have another handler, this may cause duplicate errors to be captured. Default false.
returns Function Express Error Middleware function.
Since 1.0.0

Example

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

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

Handlers.expressRequestHandler

Function

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

Agent must be installed. See install.

returns Function Express Request Middleware function.
Since 1.0.0

Example

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

var app = express()
  .use(TrackJS.Handlers.expressRequestHandler())
  // your other handlers

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.

param TrackJSOptions Options to install with.
returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

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

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.

param Function Error handler function to be attached to the agent.
returns undefined
Since 1.0.0

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;
});

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.

param 1 object dictionary of keys OR
param 1 string Metadata key
returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

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

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.

param 1 Any Error to be reported
param 2 TrackJSOptions Optional. Agent options to be overrode for this operation.
returns boolean True if the error was sent. False if it was ignored due to rules or custom handlers.
Since 1.0.0

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" }});

uninstall

Function

Removes the agent from the current environment.

See install.

returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.uninstall();

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.

returns undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.usage();