@storyous/winston-raven-sentry
v2.1.0
Published
The maintained and well-documented Raven/Sentry transport for the winston logger with support for Koa/Express/Passport
Downloads
6
Readme
winston-raven-sentry
The maintained and well-documented Raven/Sentry transport for the winston logger with support for Koa/Express/Passport.
This was designed as a complete and feature-packed drop-in replacement for 15+ unmaintained and poorly documented packages on NPM for sentry and raven winston loggers... such as
winston-sentry
,winston-raven
,sentry-logger
, etc.
Index
- Install
- Usage
- How to use with Koa/Express/Passport?
- Options
- Automatic Extra Error Object
- Recommended Logging Approach
- License
Install
npm install --save winston winston-raven-sentry
Usage
You can configure winston-raven-sentry
in two different ways.
With new winston.Logger
:
const winston = require('winston');
const Sentry = require('winston-raven-sentry');
const options = {
dsn: 'https://******@sentry.io/12345',
level: 'info'
};
const logger = new winston.Logger({
transports: [
new Sentry(options)
]
});
Or with winston's add
method:
const winston = require('winston');
const Sentry = require('winston-raven-sentry');
const logger = new winston.Logger();
logger.add(Sentry, options);
See Options below for custom configuration.
How to use with Koa/Express/Passport?
Do you want to log your user objects along with every log automatically?
If so, we can simply use custom middleware to bind a logger
method on the ctx
object in Koa, or the req
object in Express.
This example implementation assumes that you're using the standard Passport implementation and that the logged-in user
object is set to ctx.state.user
for Koa or req.user
for Express. This is the standard usage, so you should have nothing to worry about!
If you need to whitelist only certain fields from ctx.state.user
or req.user
(e.g. don't send your passwords to it) then you need to specify the option parseUser
through options.config.parseUser
as documented here https://docs.sentry.io/clients/node/config/. The default fields whitelisted are [ 'id', 'username', 'email' ]
. If you specify options.config.parseUser: true
then all keys will be collected. If you specify false
then none will be collected.
Koa Example
const winston = require('winston');
const Sentry = require('winston-raven-sentry');
const Koa = require('koa');
const passport = require('koa-passport');
const _ = require('lodash');
const app = new Koa();
const logger = new winston.Logger();
logger.add(Sentry, {
// ...
});
app.use(passport.initialize());
app.use(logger.transports.sentry.raven.requestHandler(true));
app.on('error', function(err, ctx) {
logger.error(err);
});
app.listen(3000);
Log an error or info message with
req.logger
:
app.use(async function(ctx, next) {
try {
const post = await Post.create({ message: 'hello world' });
logger.info('post created', { extra: post });
ctx.body = post;
} catch (err) {
ctx.throw(err);
// or you could also do `logger.error(err);`,
// but it's redundant since `app.emit('error')`
// will get invoked when `ctx.throw` occurs in the app
}
});
Express Example
const winston = require('winston');
const Sentry = require('winston-raven-sentry');
const express = require('express');
const passport = require('passport');
const _ = require('lodash');
const app = new express();
const logger = new winston.Logger();
logger.add(Sentry, {
// ...
});
// define this first before all else
app.use(logger.transports.sentry.raven.requestHandler());
app.use(passport.initialize());
app.get('/', function(req, res, next) {
throw new Error('oops!');
});
// keep this before all other error handlers
app.use(logger.transports.sentry.raven.errorHandler());
app.listen(3000);
Log an error or info message with
req.logger
:
app.use(async function(req, res, next) {
try {
const post = await Post.create({ message: 'hello world' });
logger.info('post created', { extra: post });
res.send(post);
} catch (err) {
logger.error(err);
next(err);
}
});
Options (options
)
Per options
variable above, here are the default options provided:
Default Sentry options:
dsn
(String) - your Sentry DSN or Data Source Name (defaults toprocess.env.SENTRY_DSN
)config
(Object) - a Raven configuration object (see Default Raven Options below)install
(Boolean) - automatically catches uncaught exceptions throughRaven.install
if set to true (defaults tofalse
)errorHandler
(Function) - a callback function to use for logging Raven errors (e.g. an invalid DSN key). This defaults to logging theerr.message
, see Default Error Handler below... but if you wish to disable this just passerrorHandler: false
. If there is already anerror
listener then this function will not get bound.raven
(Object) - an optional instance ofRaven
that is already configured viaRaven.config
(if provided this will be used instead of theconfig
option
Transport related options:
name
(String) - transport's name (defaults tosentry
)silent
(Boolean) - suppress logging (defaults tofalse
)level
(String) - transport's level of messages to log (defaults toinfo
)levelsMap
(Object) - log level mapping to Sentry (see Log Level Mapping below)
Default Raven Options (options.config
)
logger
(String) - defaults towinston-raven-sentry
captureUnhandledRejections
(Boolean) - defaults tofalse
culprit
(String) - defaults to the module or function nameserver_name
(String) - defaults toprocess.env.SENTRY_NAME
oros.hostname()
release
(String) - defaults toprocess.env.SENTRY_RELEASE
(see #343 if you'd like to have the git hash or package version as the default)tags
(Array or Object) - no default valueenvironment
(String) - defaults toprocess.env.SENTRY_ENVIRONMENT
(see #345 if you'd like to have this default toprocess.env.NODE_ENV
instead)modules
(Object) - defaults topackage.json
dependenciesextra
(Object) - no default valuefingerprint
(Array) - no default value
For a full list of Raven options, please visit https://docs.sentry.io/clients/node/config/.
Default Error Handler (options.errorHandler
)
The default error handler is a function that is simply:
function errorHandler(err) {
console.error(err.message);
}
... and it is binded to the event emitter:
Raven.on('error', this.options.errorHandler);
Therefore if you have specified an invalid DSN key, then you will see its output on the command line.
For example:
[email protected] alert: failed to send exception to sentry: HTTP Error (401): Invalid api key
HTTP Error (401): Invalid api key
If you pass options.errorHandler: false
then no error handler will be binded.
Uncaught Exceptions
If you want to log uncaught exceptions with Sentry, then specify install: true
in options:
new Sentry({
install: true
});
Unhandled Promise Rejections
If you want to log unhandled promise rejections with Sentry, then specify captureUnhandledRejections: true
in options.config
:
new Sentry({
config: {
captureUnhandledRejections: true
}
});
Log Level Mapping
Winston logging levels are mapped by default to Sentry's acceptable levels.
These defaults are set as `options.levelsMap' and are:
{
silly: 'debug',
verbose: 'debug',
info: 'info',
debug: 'debug',
warn: 'warning',
error: 'error'
}
You can customize how log levels are mapped using the levelsMap
option:
new Sentry({
levelsMap: {
verbose: 'info'
}
});
If no log level mapping was found for the given level
passed, then it will not log anything.
Custom Attributes
If you need to log custom attributes, such as extra
, user
, or tags
attributes, specify them in the meta
object.
For example:
logger.info('Something happened', {
user: {
id: '123'
},
extra: {
foo: 'bar'
},
tags: {
git_commit: 'c0deb10c4'
}
});
Automatic Extra Error Object
By default, if you provide an Error
instance to either the msg
or meta
arguments to logger[level](msg, meta)
, then this package will automatically set meta.extra.err
for you as follows:
meta.extra.err = {
stack: err.stack,
message: err.message
}
This ensures that your stack trace and error message are visible and saved to Sentry.
Furthermore, if msg
was an Error object, then we will automatically set msg = msg.message
.
This will prevent you from receiving the following message in Sentry:
Recommended Logging Approach
Compared to packages such as winston-sentry
and winston-raven
, we log messages to Sentry more accurately using captureMessage
and captureException
(and take into consideration Error
instances). There was a core bug in all other similar packages on NPM that did not pass along the log level properly, therefore it was refactored and also built to the standards of raven
itself (e.g. we utilize the defaults that they also do, see above options).
Here are a few examples provided below for how we recommend logging:
Log an error with stack trace (uses
Raven.captureException
):
logger.error(new Error('something happened'));
Note that this will automatically set extra.err.message = "something happened"
and provide the stack trace as extra.err.stack
.
Log an error message (uses
Raven.captureException
- don't worry as this method automatically turns the message below into anError
instance for us):
logger.error('something happened');
Note that this will automatically set extra.err.message = "something happened"
and provide the stack trace as extra.err.stack
.
Log an error with stack trace and extra data (uses
Raven.captureException
):
logger.error(new Error('something happened'), {
extra: {
foo: 'bar'
}
});
Note that this will automatically set extra.err.message = "something happened"
and provide the stack trace as extra.err.stack
.
Log an error with stack trace, extra data, and the user that it occurred to (uses
Raven.captureException
):
logger.error(new Error('something happened'), {
user: {
id: '123',
email: '[email protected]',
username: 'niftylettuce'
},
extra: {
foo: 'bar'
}
});
Note that this will automatically set extra.err.message = "something happened"
and provide the stack trace as extra.err.stack
.
Log a message (uses
Raven.captureMessage
):
logger.info('hello world');
Log a message and extra data (uses
Raven.captureMessage
):
logger.info('hello world', {
extra: {
foo: 'bar'
}
});
Log a message and tags (uses
Raven.captureMessage
):
logger.info('hello world', {
tags: {
component: 'api'
}
});