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

var Raven = require('raven');

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

Note that the install method can optionally take a callback function that is invoked if a fatal, non-recoverable error occurs. You can use this callback to perform any cleanup that should occur before the Node process exits.

Raven.config('___PUBLIC_DSN___').install(function (err, initialErr, eventId) {

Optional settings

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

Raven.config('___PUBLIC_DSN___', {
  release: '1.3.0'

Those configuration options are documented below:


The name of the logger used by Sentry.

  logger: 'default'

Set the server name for the client to use. Default: require('os').hostname() Optionally, use SENTRY_NAME environment variable.

  name: 'primary'

Track the version of your application in Sentry. Optionally, use SENTRY_RELEASE environment variable.

  release: '721e41770371db95eee98ca2707686226b993eda'

This is usually a Git SHA hash, which can be obtained using various npm packages, e.g.

var git = require('git-rev-sync');

  // this will return 40 characters long hash
  // eg. '75bf4eea9aa1a7fd6505d0d0aa43105feafa92ef'
  release: git.long()

Track the environment name inside Sentry. Optionally, use SENTRY_ENVIRONMENT environment variable.

  environment: 'staging'

Additional tags to assign to each event.

  tags: {git_commit: 'c0deb10c4'}

Arbitrary data to associate with the event.

    extra: {planet: {name: 'Earth'}}

Controls how Raven tries to parse user context when parsing a request object.

An array of strings will serve as a whitelist for fields to grab from req.user. true will collect all keys from req.user. false will collect nothing.

Defaults to ['id', 'username', 'email'].

Alternatively, a function can be provided for fully custom parsing:

    parseUser: function (req) {
        // custom user parsing logic
        return {
            username: req.specialUserField.username,
            id: req.specialUserField.getId()

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

The time to wait to connect to the server or receive a response when capturing an exception, in seconds.

If it takes longer, the transport considers it a failed request and will pass back a timeout error.

Defaults to 1 second. Make it longer if you run into timeout problems when sending exceptions to Sentry.

    sendTimeout: 5 // wait 5 seconds before considering the capture to have failed

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

    dataCallback: function(data) {
        // add a user context
        data.user = {
            id: 1337,
            name: 'janedoe',
            email: ''
        return data;

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

    shouldSendCallback: function (data) {
        // randomly omit half of events
        return Math.random() > 0.5;

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

  • false - all automatic breadcrumb collection disabled (default)
  • true - all automatic breadcrumb collection enabled
  • A dictionary of individual breadcrumb types that can be enabled/disabled:
autoBreadcrumbs: {
    'console': false,  // console logging
    'http': true,     // http and https requests

Raven captures up to 30 breadcrumb entries by default. You can increase this to be as high as 100, or reduce it if you find 30 is too noisy, by setting maxBreadcrumbs.

Note that in very high-concurrency situations where you might have a large number of long-lived contexts each with a large number of associated breadcrumbs, there is potential for significant memory usage. 10,000 contexts with 10kB of breadcrumb data each will use around 120mB of memory. Most applications will be nowhere close to either of these numbers, but if yours might be, you can use the maxBreadcrumbs parameter to limit the amount of breadcrumb data each context will keep around.


Override the default HTTP data transport handler.

    transport: function (options) {
        // send data

Please see the raven-node source code to see how transports are implemented.


Controls how many requests can be maximally queued before bailing out and emitting an error. Defaults to 100.


Attach stack trace to captureMessage calls by generatic “synthetic” error object and extracting all frames.

Environment Variables


Optionally declare the DSN to use for the client through the environment. Initializing the client in your app won’t require setting the DSN.


Optionally set the server name for the client to use.


Optionally set the application release version for the client to use, this is usually a Git SHA hash.


Optionally set the environment name, e.g. “staging”, “production”. Sentry will default to the value of NODE_ENV, if present.