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 particuarly 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. Permenantly ignoring an error will remove it from notifications and taking up uneccesary 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 occurences.

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 additonal functionality such as JavaScript sourcemaps, custom data, breadcrumbs and tags.

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 initilization
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: '', // A unique ID, email address, or another ID such as a UUID
  isAnonymous: false, // Indicates whether the user is anonymous or not
  email: '', // 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('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 set a version for your app by calling:

rg4js('setVersion', '');

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.

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.

Browsers have varying behavior for errors that occur in scripts located on domains that are not the origin. Many of these will be listed in Raygun as 'Script Error', or will contain poor stack traces. You can filter out these errors by enabling the ignore3rdPartyErrors option.

note: Checkout 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.

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', ['']);

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.