Agent Options

The Agent Options allows you to customize the agent to best meet the needs of your application. The following config options can be provided to the install, configure, or passed as an override to track.

Required options must be provided when installing the agent.


application

String

A application allows you to segment your reported error data by codebase or deployment environment. This key is generated when you create an Application segment in your Dashboard. Learn more about application segmentation.

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    application: "{APPLICATION}"
});

correlationId

String

A correlationId is an arbitrary string identifier that will combine errors into a series. It allows you to see all the errors that happened on an activity together.

Default Generated UUIDv4
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    correlationId: "user@/widgets/123"
});

dependencies

Boolean

Whether the agent should attempt discovery of the Node modules installed into the environment when loaded. This is done by shelling out to npm list asynchronously.

Default true
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    dependencies: false
});

metadata

{ [key: string]: string }

Hash of metadata key-value pairs to be added to the agent. See addMetadata().

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    metadata: {
        "shard": "alpha1"
    }
});

onError

Function

Error handler function to be added to the agent. Invoked when the agent has detected an error but before it has been reported. The callback function is presented with the payload, which can be manipulated by the callback.

The callback returns a boolean with true indicating that the error should be reported and false that the error should be ignored.

This is useful for:

  • adding custom context
  • removing sensitive data
  • complex error grouping
  • complex ignore logic.

See onError().

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    onError: (payload) => {
        // ignore errors from local environments.
        if (payload.url.indexOf("localhost") >= 0) {
            return false;
        }
        return true;
    }
});

sessionId

String

Customer-generated identification string for the current session. Use this to correlate error reports with external logs and reporting data.

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    sessionId: "4973c64584a84df1a925fdc4138c8d81"
});

token

String

Required

Customer account token, generated by TrackJS. This identifies error traffic for your account. Get this from the install page.

Default None
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}"
});

userId

String

Customer-generated identification string for the current user. Use this to identify and correlate errors happening to a single user. If you do not wish to send Sensitive Data to TrackJS, do not send an externally identifiable string.

If you do not provide a userId, one will be generated based on other available data.

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    userId: "sam@customer.org"
});

version

String

Customer-generated identification string for running application version. Use this to identify and correlate errors happening to a release of your application. This could be a semver string, or a git commit hash.

Default undefined
Since 1.0.0

Example

import { TrackJS } from "trackjs-node";

TrackJS.install({
    token: "{TOKEN}",
    version: "3.2.1"
});