Raven
Node v0.12/iojs compatible
Log errors and stack traces in Sentry from within your Node.js applications. Includes middleware support for Connect/Express.
All processing and sending happens asynchronously to not slow things down if/when Sentry is down or slow.
Compatibility
Raven 0.7+ requires Sentry 6.4+
Installation
$ npm install raven
Methods
new raven.Client(String dsn[, Object options])
client.captureMessage(String message[[, Object options], Function callback])
client.captureError(Error error[[, Object options], Function callback])
client.captureQuery(String query[[, String type], Function callback])
Basic Usage
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}');
client.captureMessage('Hello, world!');
You can specify a level in the second optional parameter. Default level is error
Sentry is aware of five different levels:
- debug (the least serious)
- info
- warning
- error
- fatal (the most serious)
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}', {level: 'warning'});
client.captureMessage("Another message")
Adding extra info an event
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}');
client.captureMessage("Another message", {extra: {'key': 'value'}})
Adding tags to an event
var raven = require('raven');
var client = new raven.Client('{{ SENTRY_DSN }}');
client.captureMessage("Another message", {tags: {'key': 'value'}})
Logging an error
client.captureError(new Error('Broke!'));
Logging a query
client.captureQuery('SELECT * FROM `awesome`', 'mysql');
Sentry Identifier
client.captureMessage('Hello, world!', function(result) {
console.log(client.getIdent(result));
});
client.captureError(new Error('Broke!'), function(result) {
console.log(client.getIdent(result));
});
Note: client.captureMessage
will also return the result directly without the need for a callback, such as: var result = client.captureMessage('Hello, world!');
Events
If you really care if the event was logged or errored out, Client emits two events, logged
and error
:
client.on('logged', function(){
console.log('Yay, it worked!');
});
client.on('error', function(e){
console.log('oh well, Sentry is broke.');
})
client.captureMessage('Boom');
Error Event
The event error is augmented with the original Sentry response object as well as the response body and statusCode for easier debugging.
client.on('error', function(e){
console.log(e.reason);
console.log(e.statusCode);
console.log(e.response);
});
Environment variables
SENTRY_DSN
Optionally declare the DSN to use for the client through the environment. Initializing the client in your app won't require setting the DSN.
SENTRY_NAME
Optionally set the name for the client to use. What is name?
SENTRY_RELEASE
Optionally set the application release version for the client to use, this is usually a Git SHA hash.
Catching global errors
For those times when you don't catch all errors in your application. ;)
client.patchGlobal();
raven.patchGlobal(client);
raven.patchGlobal('{{ SENTRY_DSN }}');
It is recommended that you don't leave the process running after receiving an uncaughtException
(http://nodejs.org/api/process.html#process_event_uncaughtexception), so an optional callback is provided to allow you to hook in something like:
client.patchGlobal(function() {
console.log('Bye, bye, world.');
process.exit(1);
});
The callback is called after the event has been sent to the Sentry server.
Integrations
Connect/Express middleware
The Raven middleware can be used as-is with either Connect or Express in the same way.
Connect and Express
var connect = require('connect');
function mainHandler(req, res) {
throw new Error('Broke!');
}
function onError(err, req, res, next) {
res.statusCode = 500;
res.end(res.sentry+'\n');
}
connect(
raven.middleware.connect.requestHandler('{{ SENTRY_DSN }}'),
connect.bodyParser(),
connect.cookieParser(),
mainHandler,
raven.middleware.connect.errorHandler('{{ SENTRY_DSN }}'),
onError,
).listen(3000);
Express
var app = require('express')();
app.get('/', function mainHandler(req, res) {
throw new Error('Broke!');
});
app.use(raven.middleware.express.requestHandler('{{ SENTRY_DSN }}'));
app.use(raven.middleware.express.errorHandler('{{ SENTRY_DSN }}'));
app.use(onError);
app.listen(3000);
Note: raven.middleware.express
or raven.middleware.connect
must be added to the middleware stack before any other error handling middlewares or there's a chance that the error will never get to Sentry.
Coffeescript
In order to use raven-node with coffee-script or another library which overwrites
Error.prepareStackTrace you might run into the exception "Traceback does not support Error.prepareStackTrace being defined already."
In order to not have raven-node (and the underlying raw-stacktrace library) require
Traceback you can pass your own stackFunction in the options. For example:
client = new raven.Client('{{ SENTRY_DSN }}', { stackFunction: {{ Your stack function }}});
So for example:
client = new raven.Client('{{ SENTRY_DSN }}', {
stackFunction: Error.prepareStackTrace
});
Pre-processing data
Pass the dataCallback
configuration value:
client = new raven.Client('{{ SENTRY_DSN }}', {
dataCallback: function(data) {
delete data.request.env;
return data;
}
});
Disable Raven
Pass false
as the DSN (or any falsey value).
client = new raven.Client(process.env.NODE_ENV === 'production' && '{{ SENTRY_DSN }}')
Note: We don't infer this from NODE_ENV
automatically anymore. It's up to you to implement whatever logic you'd like.
Support
You can find me on IRC. I troll in #sentry
on freenode
.