Raven.js (public beta)

Raven.js v1.0 and above requires Sentry v5.2 or later. If you're using getsentry.com, you're already up to date!

Migration Guide

First and foremost, "What is different when using Raven 1.0?" The new method is:

Raven.config(...).install()

This replaces the old window.onerror = Raven.process.

Install

Simply include the minified distribution file on your page:

<script type="text/javascript" src="//d3nslu0hdya83q.cloudfront.net/build/master/raven.min.js"></script>

Configuration

First, you will need to configure Sentry to allow requests from the domain name that is hosting your JavaScript. Go to Account → Projects and select the project you want to configure. Under "Client Security", list the domains you want to access Sentry from.

Next, configure the client by passing the DSN as the first argument:

Raven.config('http://[email protected]/project-id');

Or if you need to specify additional options:

Raven.config('http://[email protected]/project-id', {
    logger: "yoursite.errors.javascript"
});

logger - The logger name you wish to send with the message. Defaults to 'javascript'.

site - An optional site name to include with the message.

ignoreErrors - An array of error messages that should not get passed to Sentry.

ignoreUrls - An array of regular expressions matching urls which will not get passed to Sentry. For example, you could set it to [/ajax\.googleapis\.com\/ajax\/libs\/jquery/i] to ignore errors from the Google Hosted jQuery library.

Logging Errors

You can manually log errors like this:

try {
    errorThrowingCode();
} catch(err) {
    Raven.captureException(err);
    // Handle error...
}

To install error capturing globally, you need to install Raven.

Raven.install();
// or
Raven.config(...).install();

Capturing authenticated users

Raven.setUser({
    email: '[email protected]',
    id: '123'
})

setUser accepts an arbitrary object of data. The data is passed as-is.

If you need to unset the user object, you can just call setUser without an argument. This would be useful in a web app where the user is logging in/out without refreshing the page.

Raven.setUser();

Passing additional data

The captureException and captureMessage functions allow an additional options argument which you can use to pass various data (such as tags):

Raven.captureMessage('My error', {
    tags: {key: "value"}
});

Security

Raven requires you to set up the CORS headers within Sentry. These headers should include the base URI of which you plan to send events from.

For example, if you are using raven-js on http://example.com, you should list http://example.com in your origins configuration. If you only wanted to allow events from /foo, set the value to http://example.com/foo.

Support

Bug Tracker
IRC (chat.freenode.net, #sentry)

mattrobenolt/README.md