The best winston logger transport for Sentry / Raven 😁
npm i the-best-winston-sentry
Follow this sample configuration to use:
const winston = require('winston')
const SentryTransport = require('the-best-winston-sentry')
const sentryTransport = new SentryTransport({
level: 'warn',
dsn: '{{ YOUR SENTRY DSN }}',
tags: { key: 'value' },
extra: { key: 'value' },
})
const logger = new winston.Logger({
transports: [
new winston.transports.Console({level: 'silly'}),
sentryTransport,
],
})
// raven can be accessed from the transport object:
sentryTransport.raven
// or
logger.transports.sentry.raven
To catch and report all uncaught errors to Sentry with, simply set the
patchGlobal
option to true
and it will call Raven.install()
:
new SentryTransport({ patchGlobal: true })
Winston logging levels are mapped to the default sentry levels like this:
{
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',
},
})
{
user, // user object
req, // http request object
tags, // sentry tags, must be mapping of string -> string
extra, // sentry extra, can be arbitrary JSON
fingerprint, // used by sentry to group errors
// ...
// unknown props are merged with extra
}
When logging an error, there are three ways to pass the error and metadata:
- By assigning known properties directly to the error object
const err = new Error('some error')
err.user = user
err.req = req
err.tags = { foo: 'bar' }
logger.error('oops!', err)
- By passing the error as the message (this might break other transports)
const err = new Error('some error')
logger.error(err, { user, req, tags: { foo: 'bar' } })
- Recommended: by passing the error as an
err
property on the metadata
const err = new Error('some error')
logger.error('oops!', {
err,
user,
req,
tags: { foo: 'bar' },
})
When logging an error, the error's message will be concatenated with the
message passed to the Winston logger, following the following format:
{msg} cause: {err.message}
, e.g.:
logger.error('Oops!', new Error('some error'))
will show the following error message in sentry:
Oops! cause: some error
The sentry event ID is added as a sentryId
on the error object:
const testErr = new Error('some error')
logger.error('Oops!', testErr, () => {
console.log(testErr.sentryId)
// => 21479ebd4eec4afaaf9426617196a10a
})