Configuration

To get started, you need to configure Raven.js to use your Sentry DSN:

Raven.config('___PUBLIC_DSN___').install()

At this point, Raven is ready to capture any uncaught exception.

Optional settings

Raven.config() can optionally be passed an additional argument for extra configuration:

Raven.config('___PUBLIC_DSN___', {
    release: '1.3.0'
}).install()

Those configuration options are documented below:

logger

The name of the logger used by Sentry. Default: javascript

{
  logger: 'javascript'
}
release

Track the version of your application in Sentry.

{
  release: '721e41770371db95eee98ca2707686226b993eda'
}

Can also be defined with Raven.setRelease('721e41770371db95eee98ca2707686226b993eda').

environment

Track the environment name inside Sentry.

{
  environment: 'production'
}
serverName

New in version 1.3.0.

Typically this would be the server name, but that doesn’t exist on all platforms. Instead you may use something like the device ID, as it indicates the host which the client is running on.

{
  serverName: device.uuid
}
tags

Additional tags to assign to each event.

{
  tags: {git_commit: 'c0deb10c4'}
}
whitelistUrls

The inverse of ignoreUrls. Only report errors from whole urls matching a regex pattern or an exact string. whitelistUrls should match the url of your actual JavaScript files. It should match the url of your site if and only if you are inlining code inside <script> tags. Not setting this value is equivalent to a catch-all and will not filter out any values.

Does not affect captureMessage or when non-error object is passed in as argument to captureException.

{
  whitelistUrls: [/getsentry\.com/, /cdn\.getsentry\.com/]
}
ignoreErrors

Very often, you will come across specific errors that are a result of something other than your application, or errors that you’re completely not interested in. ignoreErrors is a list of these messages to be filtered out before being sent to Sentry as either regular expressions or strings.

Does not affect captureMessage or when non-error object is passed in as argument to captureException.

{
  ignoreErrors: ['fb_xd_fragment']
}
ignoreUrls

The inverse of whitelistUrls and similar to ignoreErrors, but will ignore errors from whole urls matching a regex pattern or an exact string.

{
  ignoreUrls: [/graph\.facebook\.com/, 'http://example.com/script2.js']
}

Does not affect captureMessage or when non-error object is passed in as argument to captureException.

includePaths

An array of regex patterns to indicate which urls are a part of your app in the stack trace. All other frames will appear collapsed inside Sentry to make it easier to discern between frames that happened in your code vs other code. It’d be suggested to add the current page url, and the host for your CDN.

{
    includePaths: [/https?:\/\/getsentry\.com/, /https?:\/\/cdn\.getsentry\.com/]
}
sampleRate

A sampling rate to apply to events. A value of 0.0 will send no events, and a value of 1.0 will send all events (default).

{
    sampleRate: 0.5 // send 50% of events, drop the other half
}
dataCallback

A function that allows mutation of the data payload right before being sent to Sentry.

{
    dataCallback: function(data) {
      // do something to data
      return data;
    }
}
breadcrumbCallback

A function that allows filtering or mutating breadcrumb payloads. Return false to throw away the breadcrumb.

{
    breadcrumbCallback: function(crumb) {
      if (crumb.type === 'http') {
        return crumb;
      }

      return false;
    }
}
shouldSendCallback

A callback function that allows you to apply your own filters to determine if the message should be sent to Sentry.

{
    shouldSendCallback: function(data) {
      return false;
    }
}
maxMessageLength

By default, Raven does not truncate messages. If you need to truncate characters for whatever reason, you may set this to limit the length.

maxUrlLength

By default, Raven will truncate URLs as they appear in breadcrumbs and other meta interfaces to 250 characters in order to minimize bytes over the wire. This does not affect URLs in stack traces.

autoBreadcrumbs

Enables/disables automatic collection of breadcrumbs. Possible values are:

  • true (default)
  • false - all automatic breadcrumb collection disabled
  • A dictionary of individual breadcrumb types that can be enabled/disabled:
autoBreadcrumbs: {
    'xhr': false,      // XMLHttpRequest
    'console': false,  // console logging
    'dom': true,       // DOM interactions, i.e. clicks/typing
    'location': false  // url changes, including pushState/popState
}
maxBreadcrumbs

By default, Raven captures as many as 100 breadcrumb entries. If you find this too noisy, you can reduce this number by setting maxBreadcrumbs. Note that this number cannot be set higher than the default of 100.

transport

Override the default HTTP data transport handler.

Alternatively, can be specified using Raven.setTransport(myTransportFunction).

{
    transport: function (options) {
        // send data
    }
}

The provided function receives a single argument, options, with the following properties:

url
The target url where the data is sent.
data

The outbound exception data.

For POST requests, this should be JSON-encoded and set as the HTTP body (and transferred as Content-type: application/json).

For GET requests, this should be JSON-encoded and passed over the query string with key sentry_data.

auth

An object representing authentication data. This should be converted to urlencoded key/value pairs and passed as part of the query string, for both GET and POST requests.

The auth object has the following properties:

sentry_version
The API version of the Sentry server.
sentry_client
The name and version of the Sentry client of the form client/version. In this case, raven-js/${Raven.VERSION}.
sentry_key
Your public client key (DSN).
onSuccess
Callback to be invoked upon a successful request.
onError
Callback to be invoked upon a failed request.
allowDuplicates

By default, Raven.js attempts to suppress duplicate captured errors and messages that occur back-to-back. Such events are often triggered by rogue code (e.g. from a setInterval callback in a browser extension), are not actionable, and eat up your event quota.

To disable this behavior (for example, when testing), set allowDuplicates: true during configuration.

allowSecretKey

By default, Raven.js will throw an error if configured with a Sentry DSN that contains a secret key. When using Raven.js with a web application accessed via a browser over the web, you should only use your public DSN. But if you are using Raven.js in an environment like React Native or Electron, where your application is running “natively” on a device and not accessed at a web address, you may need to use your secret DSN string. To do so, set allowSecretKey: true during configuration.

debug

If set to true, Raven.js outputs some light debugging information onto the console.

instrument

Enables/disables instrumentation of globals. Possible values are:

  • true (default)
  • false - all instrumentation disabled
  • A dictionary of individual instrumentation types that can be enabled/disabled:
instrument: {
    'tryCatch': true, // Instruments timers and event targets
}

Putting it all together

<!doctype html>
<html>
<head>
    <title>Awesome stuff happening here</title>
</head>
<body>
    ...
    <script src="jquery.min.js"></script>
    <script src="https://cdn.ravenjs.com/3.16.0/raven.min.js"
        crossorigin="anonymous"></script>
    <script>
        Raven.config('___PUBLIC_DSN___', {
            logger: 'my-logger',
            whitelistUrls: [
                /disqus\.com/,
                /getsentry\.com/
            ],
            ignoreErrors: [
                'fb_xd_fragment',
                /ReferenceError:.*/
            ],
            includePaths: [
                /https?:\/\/(www\.)?getsentry\.com/
            ]
        }).install();
    </script>
    <script src="myapp.js"></script>
</body>
</html>