Advanced Features

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

These advanced set up instructions cover both Crash Reporting and Real User Monitoring.

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.

Configuration options

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

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]‘(/documentation/language-guides/javascript/advanced-setup/#crash-reporting-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.

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.

If you need help with any of these behaviours for issues you are experiencing, contact us.

Adding tags

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:

On initilization:

rg4js('withTags', ['tag1', 'tag2']);

During a Send:

rg4js('send', {
  error: e,
  tags: ['tag3']
});

Affected users

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:

constructor() {
    super()

    rg4js('enableCrashReporting', true);
    rg4js('apiKey', 'paste_your_api_key_here');

    this.setupUser();
  }

  setupUser() {
    try {
      var user;
      AsyncStorage.getItem('@raygun:user', (err, result) => {
        if (!result) {
          // One approach is to load the user data from AsyncStorage or the network using fetch(). When that data returns, place the following in its callback:

          user = {
            identifier: 'user@example.com', // A unique ID or email address, or a random ID such as a UUID
            isAnonymous: false, // Or true
            email: 'user@example.com', // Optional
            firstName: 'Foo', // Optional
            fullName: 'Foo Bar', // Optional
            uuid: 'BAE62917-ACE8-ab3D-9287-B6A33B8E8C55' // Optional device identifier
          };

          AsyncStorage.setItem('@raygun:user', JSON.stringify(user), () => { });
        } else {
          user = result;
        }

        rg4js('setUser', JSON.parse(user));
        rg4js('boot'); // Ensure this is called finally
      });

    } catch (e) {
    }
  }

By default, Raygun4JS assigns a unique anonymous ID for the current user. This is stored as a cookie. If the current user changes, to reset it and assign a new ID you can call:

rg4js('getRaygunInstance').resetAnonymousUser();

Disabling anonymous user tracking

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

Rich user data

You can provide data about the currently logged in user to Raygun by calling:

rg4js('setUser', {
  identifier: 'user_email_address@localhost.local',
  isAnonymous: false,
  email: 'emailaddress@localhost.local',
  fullName: 'Foo Bar',
  firstName: 'Foo',
  uuid: 'BAE62917-ACE8-ab3D-9287-B6A33B8E8C55'
});

Only the identifier or the first parameter is required.

This method takes additional parameters that are used when reporting over the affected users. The full method signature is:

setUser: function (user, isAnonymous, email, fullName, firstName, uuid)

All the parameters are strings, except for the isAnonymous bool.

user is the user identifier. This will be used to uniquely identify the user within Raygun. This is the only required parameter, but is of course, only required if you are using User Tracking.

isAnonymous is a bool indicating whether the user is anonymous or actually has a user account. Even if this is set to true, you should still give the user a unique identifier of some kind.

email is the user’s email address.

fullName is the user’s full name.

firstName is the user’s first or preferred name.

uuid is the identifier of the device the app is running on. This could be used to correlate user accounts over multiple machines.

This will be transmitted with each message. A count of unique users will appear on your Raygun dashboard in the individual error view. If you provide an email address, the user’s Gravatar will be displayed (if they have one). This method is optional; if it is not called, no user tracking will be performed. Note that if the user context changes (such as in an SPA), you should call this method again to update it.

Resetting the user:

Pass in empty strings (or false to isAnonymous) to reset the current user for login/logout scenarios.

Custom data

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 variables (objects, arrays etc) can be added by calling the withCustomData function on the Raygun object:

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

During a send:

You can also pass custom data with manual send calls, with an options object. This lets you add variables that are in scope or global when handled in catch blocks. For example:

rg4js('send', {
  error: e,
  customData: [{ foo: 'bar' }]
});

Providing custom data with a callback

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

var desiredNum = 1;

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

rg4js('withCustomData', getMyData);

getMyData 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.

Version filtering

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.

Offline saving

If errors are caught when there is no network activity, they can be saved in local storage. When an error arrives and connectivity is regained, previously saved errors are then sent. This is useful in environments like WinJS, where a mobile device’s internet connection is not constant.

Offline saving is disabled by default. To set this option, call the following after your init() call:

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. This is confirmed to work on Chrome, Firefox, IE10/11, Opera and WinJS.

Limited support is available for IE 8 and 9 - errors will only be saved if the request times out.

Script Errors

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 with the following code snippet. There is also an option to whitelist domains which are allowed to transmission errors to Raygun, accepting the domains as an array of strings:

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

Sensitive data

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 [removed by filter].

Changing filter scope

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

Source maps

Raygun4JS features sourcemap support through the transmission of column numbers for errors, where available. This is confirmed to work in recent version of Chrome, Safari and Opera, and IE 10 and 11. See the sourcemaps documentation for more information.

Whitelisting

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.

The provider will default to attempt to send errors from subdomains - for instance if the page is loaded from foo.com, and a script is loaded from cdn.foo.com, that error will be transmitted on a best-effort basis.

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).

  • For Chrome 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 (crossOrigin on script tag not needed).

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.