winston-transport-sentry-node

![node][node-url]
![winston][winston-url]
![license][license-url]

@Sentry/node transport for the winston v3 logger.

Index

* Install
* Usage
* Options
- Transport related options
- Sentry common options
- Info object
- Log Level Mapping
* License

Install

``bash
npm install --save winston winston-transport-sentry-node
`




Usage

You can configure winston-transport-sentry-node in two different ways.

With winston.createLogger:

`js
const winston = require('winston');
const Sentry = require('winston-transport-sentry-node').default;

const options = {
sentry: {
dsn: 'https://@sentry.io/12345',
},
level: 'info'
};

const logger = winston.createLogger({
transports: [
new Sentry(options)
]
});
`

Or with winston's add method:

`js
const winston = require('winston');
const Sentry = require('winston-transport-sentry-node').default;

const logger = winston.createLogger();

logger.add(new Sentry(options));
`

See Options below for custom configuration.

Options (options)

$3

* sentry (Object) - a Sentry configuration object (see Sentry Common Options)
* silent (Boolean) - suppress logging (defaults to false)
* level (String) - transport's level of messages to log (defaults to info)
* format (Object) - custom log format (see Winston Formats)
* levelsMap (Object) - optional custom mapping between Winston's log levels and Sentry's log levels (default)

$3

* dsn (String) - your Sentry DSN or Data Source Name (defaults to process.env.SENTRY_DSN)
* environment (String) - (defaults to process.env.SENTRY_ENVIRONMENT || process.env.NODE_ENV || 'production')
* serverName (String) - transport's name (defaults to winston-transport-sentry-node)
* debug (Boolean) - turns debug mode on or off (default to process.env.SENTRY_DEBUG || false)
* sampleRate (Number) - sample rate as a percentage of events to be sent in the range of 0.0 to 1.0 (default to 1.0)
* maxBreadcrumbs (Number) - total amount of breadcrumbs that should be captured (default to 100)
* ... Other options

$3

If info.tags is an object, it will be sent as Sentry Tags.

`js
logger.error("some error", { tags: { tag1: "yo", tag2: "123" } });
`

If info.user is an object, it will be sent as Sentry User.

`js
logger.error("some error", { user: { username: "somebody", id: "123" } });
`

Additional properties of info are sent as Sentry Extra Context.

`js
logger.error("some error", { whatever: "is sent as extra" });
`

Tip! If you already have logging in place and want to use Sentry tags but don’t want to update all places where you log something, use a format function.

`js
const sentryFormat = format(info => {
const {path, label, ...extra} = info;
return {
...extra,
tags: {
path: path || '',
request_id: label
}
}
});

new SentryTransport({
format: sentryFormat()
// ...
});
`

$3

Winston logging levels are mapped by default to Sentry's acceptable levels.

`js
{
silly: 'debug',
verbose: 'debug',
info: 'info',
debug: 'debug',
warn: 'warning',
error: 'error'
}
`

See available Sentry's levels.
Matching is done with Sentry.Severity.fromString() method and will defaults to log`

License

[MIT License][license-url]

[license-url]: LICENSE
[node-url]: https://nodejs.org
[winston-url]: https://github.com/winstonjs/winston