caution

You are reading documentation for an outdated version. Here’s the latest one!

Error tracking

The Errors tracker plugin provides two ways of tracking exceptions: manual tracking of handled exceptions using trackError and automatic tracking of unhandled exceptions using enableErrorTracking.

Error events can be manually tracked and/or automatically tracked.

Install plugin

JavaScript (tag)

Tracker Distribution	Included
sp.js	✅
sp.lite.js	❌

Download:

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr (latest)
Available on unpkg	unpkg (latest)

Note: The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

window.snowplow('addPlugin', 
  "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-error-tracking@3/dist/index.umd.min.js",
  ["snowplowErrorTracking", "ErrorTrackingPlugin"]
);

Browser (npm)

• npm install @snowplow/browser-plugin-error-tracking@3
• yarn add @snowplow/browser-plugin-error-tracking@3
• pnpm add @snowplow/browser-plugin-error-tracking@3

import { newTracker } from '@snowplow/browser-tracker';
import { ErrorTrackingPlugin, enableErrorTracking } from '@snowplow/browser-plugin-error-tracking';

newTracker('sp1', '{{collector_url}}', { 
   appId: 'my-app-id', 
   plugins: [ ErrorTrackingPlugin() ],
});

enableErrorTracking();

Manual error tracking

Use the trackError method to track handled exceptions (application errors) in your JS code. This is its signature:

JavaScript (tag)

snowplow('trackError', {
  /** The error message */
  message: string;
  /** The filename where the error occurred */
  filename?: string;
  /** The line number which the error occurred on */
  lineno?: number;
  /** The column number which the error occurred on */
  colno?: number;
  /** The error object */
  error?: Error;
});

Browser (npm)

trackError({
  /** The error message */
  message: string;
  /** The filename where the error occurred */
  filename?: string;
  /** The line number which the error occurred on */
  lineno?: number;
  /** The column number which the error occurred on */
  colno?: number;
  /** The error object */
  error?: Error;
});

Name	Required?	Description	Type
message	Yes	Error message	string
filename	No	Filename or URL	string
lineno	No	Line number of problem code chunk	number
colno	No	Column number of problem code chunk	number
error	No	JS ErrorEvent	ErrorEvent

Of these arguments, only message is required. Signature of this method defined to match window.onerror callback in modern browsers.

JavaScript (tag)

try {
  var user = getUser()
} catch(e) {
  snowplow('trackError', {
    message: 'Cannot get user object',
    filename: 'shop.js',
    error: e
  });
}

Browser (npm)

try {
  var user = getUser()
} catch(e) {
  trackError({
    message: 'Cannot get user object',
    filename: 'shop.js',
    error: e
  });
}

Using trackError it's assumed that developer knows where errors could happen, which is not often the case. Therefor it's recommended to use enableErrorTracking as it allows you to discover errors that weren't expected.

Automatic error tracking

Use the enableErrorTracking method to track unhandled exceptions (application errors) in your JS code. This is its signature:

JavaScript (tag)

snowplow('enableErrorTracking', {
  /** A callback which allows on certain errors to be tracked */
  filter?: (error: ErrorEvent) => boolean;
  /** A callback to dynamically add extra context based on the error */
  contextAdder?: (error: ErrorEvent) => Array<SelfDescribingJson>;
  /** Context to be added to every error */
  context?: Array<SelfDescribingJson>;
}

Browser (npm)

enableErrorTracking({
  /** A callback which allows on certain errors to be tracked */
  filter?: (error: ErrorEvent) => boolean;
  /** A callback to dynamically add extra context based on the error */
  contextAdder?: (error: ErrorEvent) => Array<SelfDescribingJson>;
  /** Context to be added to every error */
  context?: Array<SelfDescribingJson>;
});

Name	Required?	Description	Type
filter	No	Predicate to filter exceptions	(ErrorEvent) => Boolean
contextAdder	No	Function to get dynamic context	(ErrorEvent) => Array<SelfDescribingJson>
context	No	Additional custom context	Array<SelfDescribingJson>

Unlike trackError you need enable error tracking only once:

JavaScript (tag)

snowplow('enableErrorTracking')

Browser (npm)

enableErrorTracking();

Application error events are implemented as Snowplow self-describing events. Here is the schema for an application_error event.