1. Home
  2. Language Guides
  3. JavaScript
  4. Crash Reporting
  5. Advanced Features

Advanced Features

Getting started with Raygun4JS is straightforward using the basic installation, but sometimes you want additional options and functionality.

Post installation

Once you have set up the basic installation of Raygun and are successfully seeing data on your dashboard you might be wondering - what next?

JavaScript particularly can be a noisy language when it comes to errors, as third party scripts and plugins might be creating a lot of error volume. If this is the case you will want to alter your notification settings to ensure you're not getting bombarded with notifications whilst using Crash Reporting.

Raygun requires you to curate your errors and crashes down to the things you care about most by using the workflow tools with your team to manage their progress to resolution. Raygun is not a logging tool and requires work to sort out what needs fixing first, that has the biggest impact on your users. Permanently ignoring an error will remove it from notifications and taking up unnecessary quota from your monthly usage allowance, so for high frequency errors that you cannot fix, move them to this status as soon as you can, choosing not to store future occurrences.

If you have enabled Real User Monitoring for your application, user sessions will start to be tracked automatically once set up. View the performance timings of pages within user sessions and look for ways to improve them once you have collected enough data.

Users will be anonymous until you set up User Tracking to identify authenticated users of your app.

You can then explore additional functionality such as JavaScript sourcemaps, custom data, breadcrumbs and tags.

If you would like to defer the loading of the Raygun snippet, you can do so by adding the defer attribute to the script tag.

This will ensure the script is loaded after the page has finished loading, but before the DOMContentLoaded event is fired.

We strongly recommend that you place the script tag for the provider snippet first and mark all of your other scripts with defer (but not async). This will guarantee that the Raygun4JS provider is executed before any of the others.

To configure the Raygun4JS provider, call one of these and pass in an options object:

An example:

rg4js('options', {
  allowInsecureSubmissions: true,
  ignoreAjaxAbort: true,
  ignoreAjaxError: true,
  debugMode: true,
  ignore3rdPartyErrors: false,
  wrapAsynchronousCallbacks: true,
  excludedHostnames: ['localhost', '\.dev'],
  excludedUserAgents: ['PhantomJS', 'MSIE'],
  disableErrorTracking: false,
  disablePulse: false,
  pulseMaxVirtualPageDuration: 1800000,
  pulseIgnoreUrlCasing: false,
  automaticPerformanceCustomTimings: false
});

This should contain one or more of these keys and a value to customize the behavior:

allowInsecureSubmissions - posts error payloads over HTTP. This allows IE8 to send JS errors.

ignoreAjaxAbort - User-aborted Ajax calls result in errors - if this option is true, these will not be sent.

ignoreAjaxError - Ajax requests that return error codes will not be sent as errors to Raygun if this option is true.

debugMode - Raygun4JS will log to the console when sending errors.

ignore3rdPartyErrors - ignores any errors that have no stack trace information. This will discard any errors that occur completely within 3rd party scripts - if code loaded from the current domain called the 3rd party function, it will have at least one stack line and will still be sent. This option removes nonsense 'Script Errors' from your Raygun dashboard.

wrapAsynchronousCallbacks - disables wrapping of async setTimeout/setInterval callbacks when set to false. Defaults to true. This option is respected when attach() is called.

excludedHostnames - Prevents errors from being sent from certain hostnames (domains) by providing an array of strings or RegExp objects (for partial matches). Each should match the hostname or top level domain (TLD) that you want to exclude. Note that protocols are not tested.

excludedUserAgents - Prevents errors from being sent from certain clients, based on their user agent string. Pass in an array of strings or RegExp objects. Useful for ignoring headless browsers in unit testing, or old/problematic clients.

disableAnonymousUserTracking - Prevent user data being sent for anonymous users (those where setUser hasn't been called).

disableErrorTracking - Prevent all errors from being sent.

disablePulse - Prevent Real User Monitoring events from being sent.

apiEndpoint - A string URI containing the protocol, domain and port (optional) where all payloads will be sent to. This can be used to proxy payloads to the Raygun API through your own server. When not set, this defaults internally to the Raygun API, and for most usages you won't need to set this.

clientIp - A string containing the client's IP address. RUM requests will be associated to this IP address when set. Particularly useful when proxying payloads to the Raygun API using the apiEndpoint option and maintaining RUM's geographic lookup feature.

Note: navigator.sendBeacon is used to send RUM payloads when a page is unloading. As such, the clientIp feature will not work with payloads sent when a page is unloading.

pulseMaxVirtualPageDuration - The maximum time a virtual page can be considered viewed, in milliseconds (defaults to 30 minutes).

pulseIgnoreUrlCasing - Ignore URL casing when sending data to Real User Monitoring.

captureUnhandledRejections - Automatically report errors relating to unhanded promise rejections. Browser support for this option is dependant on the unhandledrejection event.

setCookieAsSecure - If cookies are being used (only used on browsers which don't support localStorage or sessionStorage) then they will be created using the ; secure flag and thus cookies only work on HTTPS.

captureMissingRequests - RUM uses the window.performance API to track XHR timing information and (depending on the browser) not all non-2XX XHR timings are recorded by this API. This option enables the tracking of these missing XHR's calls by tracking the difference between send & success XHR handlers. This is not enabled by default due these timings being as accurate as the performance API.

automaticPerformanceCustomTimings - When enabled Raygun4JS will track each performance.measure call as a custom timing entry. This enables developers to use a native API for tracking performance timings. More information about performance.measure can be found on MDN.

Raygun4JS listens for errors reported by the onerror handler. However, sometimes you will want to send custom handled errors manually, either in an exception handler or from within a try/catch block. You can use the following code to do so:

rg4js('send', {
   error: new Error('my error message'),
});

Your Raygun dashboard can display tags for specific errors you want to identify, or filter by. Perhaps these are issues affecting your billing pages or you want to be able to identify when errors come from a specific part of your stack. These are arrays of strings or numbers. This is done in a similar way to attaching custom data, like so:

// After initialization
rg4js('withTags', ['tag1', 'tag2']);

// When manually sending a error
rg4js('send', {
  error: e,
  tags: ['tag3']
});

You can optionally configure User Tracking, either anonymously or non-anonymously (if your app has the concept of a logged-in user and their data available). Here's an example of how to set it up with Raygun4JS:

rg4js('setUser', {
  identifier: 'hello@raygun.com', // A unique ID, email address, or another ID such as a UUID
  isAnonymous: false, // Indicates whether the user is anonymous or not
  email: 'hello@raygun.com', // Optional 
  firstName: 'Ronald', // Optional
  fullName: 'Ronald Raygun', // Optional
  uuid: 'BAE62917-ACE8-ab3D-9287-B6A33B8E8C55' // Optional device identifier
});

By default, Raygun4JS assigns a unique anonymous ID for the current user. This is stored in LocalStorage or as a Cookie (if localStorage is not available).

To reset the anonymous user data you can call:

rg4js('getRaygunInstance').resetAnonymousUser();

rg4js('options', { disableAnonymousUserTracking: true });

When a user has logged out of your application, you can remove their data from all subsequent crash reports with setUser like so:

rg4js('setUser', {
  isAnonymous: true
});

The Raygun object has a withCustomData() function where you can pass in JavaScript objects that will be sent with each error that occurs. This allows you to provide any useful data that is global or in scope.

There are two ways to do this:

On initialization:

Custom data can be attached to all error instances sent to Raygun by calling the withCustomData method:

rg4js('withCustomData', { foo: 'bar' });

note: When providing custom data be careful to ensure that objects passed do not contain circular references.

During a send:

Custom data can also be passed when manually sending errors to Raygun. This allows you to add in-scope variables to provide you with more context about the error.

// When manually sending an error
rg4js('send', {
  error: e,
  customData: { foo: 'bar' }
});

// The customData key accepts both array and object formats
rg4js('send', {
  error: e,
  customData: [{ foo: 'bar' }]
});

note: When both methods of passing custom data are used both objects passed are merged together and will send with each error instance.

To send the state of variables at the time an error occurs, you can pass withCustomData a function. This needs to return an object. For example:

var desiredNum = 1;

function generateCustomData() {
 return { num: desiredNum };
}

rg4js('withCustomData', generateCustomData);

generateCustomData will be called when Raygun4JS is about to send an error, which will construct the custom data. This will be merged with any custom data provided on a Raygun.send() call.

You can control custom grouping for error instances by passing in a callback. This will override the automatic grouping and be used to group error instances together. Errors with the same key will be placed within the same error group. The callback's signature should take in the error payload, stackTrace and options and return a string, ideally 64 characters or less. If the callback returns null or a non-string the error will be grouped using Raygun's server side grouping logic (this can be useful if you only wish to use custom grouping for a subset of your errors).

var groupingKeyCallback = function (payload, stackTrace, options) {
  // Inspect the above parameters and return a hash derived from the properties you want
  return payload.Details.Error.Message; // Naive message-based grouping only
};

rg4js('groupingKey', groupingKeyCallback);

You can set a version for your app by calling:

rg4js('setVersion', '1.0.0.0');

This will allow you to filter the errors in your Raygun dashboard by that version. You can also select only the latest version, to ignore errors that were triggered by previous versions of your code. The parameter should be a string in the format x.x.x if you want to get the version sorting in Raygun to work nicely. Where x is a non-negative integer.

rg4js('onBeforeSend', function (payload) {
  return payload;
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be called immediately before the payload is sent. The one parameter it gets will be the payload that is about to be sent. Thus from your function you can inspect the payload and decide whether or not to send it.

From the supplied function, you should return either the payload, or return false.

If your function returns a truthy object, Raygun4js will attempt to send it as supplied. Thus, you can mutate it as per your needs - preferably only the values if you wish to filter out data that is not taken care of by filterSensitiveData(). You can also of course return it as supplied.

If, after inspecting the payload, you wish to discard it and abort the send to Raygun, simply return false.

Example:

var myBeforeSend = function (payload) {
  console.log(payload); // Modify the payload here if necessary
  return payload; // Return false here to abort the send
}

rg4js('onBeforeSend', myBeforeSend);
rg4js('onAfterSend', function (xhrResponse) {
  // Inspect the XHR response here
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be immediately called after the XHR request for a Crash Reporting or RUM event responds successfully, or errors out (its onerror was called). You can inspect the one parameter, which is the XHR object containing the HTTP response data.

rg4js('onBeforeSendRUM', function (payload) {
  return payload;
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be called immediately before any Real User Monitoring events are sent. The one parameter it gets will be the payload that is about to be sent. Thus from your function you can inspect the payload and decide whether or not to send it.

From the supplied function, you should return either the payload (intact or mutated as per your needs), or false.

If your function returns a truthy object, Raygun4JS will attempt to send it as supplied. Thus, you can mutate it as per your needs. You can also of course return it as supplied.

If, after inspecting the payload, you wish to discard it and abort the send to Raygun, simply return false.

Example:

var myBeforeSend = function (payload) {  
  console.log(payload); // Modify the payload here if necessary  
  return payload; // Return false here to abort the send  
}

rg4js('onBeforeSendRUM', myBeforeSend);

rg4js('onBeforeXHR', function (xhr) {
  // Mutate the xhr parameter as per your needs
});

Call this function when you want control over the XmlHttpRequest object that is used to send error payloads to the API. Pass in a callback that receives one parameter (which is the XHR object). Your callback will be called after the XHR object is opened, immediately before it is sent.

For instance, you can use this to add custom HTTP headers.

As above for custom data, withTags() can now also accept a callback function. This will be called when the provider is about to send, to construct the tags. The function you pass to withTags() should return an array (ideally of strings/Numbers/Dates).

rg4js('withTags', function() {
  return ['tag1', 'tag2']
});

When offline saving is enabled errors are caught when there is no network activity and are then saved in LocalStorage. Once connectivity is regained, previously saved errors will then be sent. This is useful in environments where a users' internet connection is not constant.

Offline saving is disabled by default. To enable the offline saving option, call the rg4js method with saveIfOffline, as shown below:

rg4js('saveIfOffline', true);

If an error is caught and no network connectivity is available, or if the request times out after 10s, the error will be saved to LocalStorage.

Browser behavior varies for errors occurring in scripts located on a domain other than the origin. Many of these will be listed in Raygun as 'Script Error', or will contain poor stack traces. There are a few steps you can take to prevent third party errors from being sent to your Raygun application.

Raygun's ignore3rdPartyErrors option targets and filters out these errors.

note: See the whitelisting domains feature to enable the transmission of errors from certain domains. 

rg4js('options', { ignore3rdPartyErrors: true });

This option will also block errors that occur in scripts injected into your site by browser extensions, bots or crawlers.

Permanently ignore third party error groups as they occur to prevent them being sent to Raygun in the future.

Set up inbound filters to filter out any patterns in 3rd party errors and prevent them from being sent to Raygun.

Use onBeforeSend() to inspect error payloads and determine if it's a third party error and should be rejected.

You can blacklist keys to prevent their values from being sent in the error payload, by providing an array of key names:

rg4js('filterSensitiveData', ['password', 'credit_card']);

If any key matches one in the input array, its value will be replaced with the string [removed by filter].

By default this is applied to the UserCustomData object only (legacy behavior). To apply this to any key-value pair, you can change the filtering scope:

rg4js('setFilterScope', 'all'); // Filter any key in the payload
rg4js('setFilterScope', 'customData'); // Just filter the custom data (default)

You can also pass RegExp objects in the array to filterSensitiveData, for controllable matching of keys:

var creditCardDataRegex = /credit\D*/; // Remove any keys that begin with 'credit'
rg4js('filterSensitiveData', [creditCardDataRegex]);

Raygun4JS features sourcemap support through the transmission of line and column numbers for errors, where available. See the sourcemaps documentation for more information.

Allow transmission of errors to Raygun from certain domains, accepting those domains as an array of strings:

rg4js('options', { ignore3rdPartyErrors: true });
rg4js('whitelistCrossOriginDomains', ['code.jquery.com']);

This can be used to allow errors from remote sites, subdomains and CDNs when the ignore3rdPartyErrors feature is enabled.

To get full stack traces from cross-origin domains or subdomains, these requirements should be met:

  • The remote domain should have Access-Control-Allow-Origin set (to include the domain where raygun4JS is loaded from).
  • The script tag must also have crossOrigin="Anonymous" set.
  • Recent versions of Firefox (>= 31) will transmit errors from remote domains with full stack traces if the header is set.

In Chrome, if the origin script tag and remote domain do not meet these requirements the cross-origin error will not be sent.

Other browsers may send on a best-effort basis (version dependent) if some data is available, but potentially without a useful stacktrace. The provider will cancel the send if no data is available.

The provider is open source and available at the Raygun4js repository.

On this page: