Breadcrumbs

Overview

Using the breadcrumbs feature, you can attach an accurate trail of the events through your system leading up to the moment a crash report was generated. You’ll gain more insight into why the application crashed when it did, making prioritization of fixes much easier.

There are two ways Raygun reports Breadcrumbs:

  1. You can choose specific portions of your code you deem important and manually leave breadcrumbs there with information about the state of the system.

  2. Certain providers will automatically create Breadcrumbs for some specific important events (e.g. network requests, element clicks, and database queries)

You will be able to find the trail of events inside the ‘Breadcrumbs’ tab on an error or crash instance.

Any crash report that comes in with Breadcrumbs attached will have this tab available, otherwise it will not show.

JavaScript breadcrumbs feature in Raygun

Inside this tab, you can see all the ‘crumbs’ attached to the error. These are in order from oldest to newest. Each crumb has an associated icon (i.e. how it was logged, a network request, or a DOM element click). The icon’s color is representative of a user supplied severity, and important events will stand out making prioritization even faster.

  • Blue = debug
  • Teal = info
  • Yellow = warning
  • Red = error

Severities are handled similarly to logging frameworks, with the available options being debug, info, warning and, error. In each of the Raygun language providers, you can set a minimum level of breadcrumb to report. This way you can add detailed debug breadcrumbs, but only enable them in the situations you need to avoid cluttering your breadcrumb trails with excessive information.

A quick mouse-over the icon will reveal the origin of the problem:

Some of the key uses for the Breadcrumbs feature can be tagging key service object calls, along with their return values. Another is your interactions with third party APIs and their responses to give you a better understanding of where problems may have occurred in your external integrations.

Setting up breadcrumbs

Raygun4JS automatically records a number of things; console messages, network requests, navigation events and element clicks. With this information, breadcrumbs make it easier to understand how your user interacted with the application, and exactly what caused them to experience an error.

If you wish to customize the information collected with breadcrumbs configure the Raygun provider with one of the following options in your code.

<script type="text/javascript">
  rg4js('apiKey', 'paste_your_api_key_here');
  rg4js('enableCrashReporting', true);
  rg4js('one-of-the-options-below');
</script>

rg4js('disableAutoBreadcrumbs') - Disable all the automatic breadcrumb integrations (clicks, requests, console logs and navigation events). This has an inverse enableAutoBreadcrumbs which is the default

rg4js('disableAutoBreadcrumbsConsole') - Disable just automatic breadcrumb creation from console messages

rg4js('disableAutoBreadcrumbsNavigation') - Disable just automatic breadcrumb creation from navigation events

rg4js('disableAutoBreadcrumbsClicks') - Disable just automatic breadcrumb creation from element clicks

rg4js('disableAutoBreadcrumbsXHR') - Disable just automatic breadcrumb creation XMLHttpRequests

All of the above have an inverse enableAutoBreadcrumbs which is the default

rg4js('setAutoBreadcrumbsXHRIgnoredHosts', []) - This can be set to an array of hostnames to not create a breadcrumb for requests/responses to. The values inside the array can either be strings that an indexOf check against the host is made, or regexes which is matched against the host.

rg4js('setBreadcrumbLevel', 'warning') - Set the minimum level of breadcrumb to record. This works the same as log levels, you may set it to debug, info, warning and error and it will only keep breadcrumbs with a level equal or above what this is set to. Valid values are one of ['debug', 'info', 'warning', 'error'] defaults to info

rg4js('logContentsOfXhrCalls', true) - If set to true will include the body contents of XHR request and responses in Breadcrumb metadata, defaults to false

Manual logging

Breadcrumbs can be manually logged via rg4js('recordBreadcrumb', ...)

There are two argument formats:

rg4js('recordBreadcrumb', 'breadcrumb-message', {object: 'that will be attached to the breadcrumb custom data'})

This is the quickest way to log basic breadcrumbs, requiring only a message and optionally an object to attach some metadata

If you wish to have further control of the breadcrumb and configure the level (debug, info, warning, error) or set the class/method the breadcrumb was logged from

rg4js('recordBreadcrumb', {message: 'breadcrumb-message', metadata: {goes: 'here'}, level: 'info', location: 'class:method'})

You may use the above argument format

Restrictions

To help ensure your payload does not become too large only the most recent 32 breadcrumbs are kept, as well as limiting the size of recorded network request/response texts to 500 characters.