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

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/]
}

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

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.

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.

onFailure

Callback to be invoked upon a failed request.

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 allowPrivateKey: true during configuration.

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.4.0/raven.min.js"></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>