winston-transport-sentry-node

winston-transport-sentry-node

@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

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

Usage

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

With winston.createLogger:

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:

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)

Transport related options

• 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)

Sentry common options

• 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

Info object (See more)

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

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

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

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

Additional properties of info are sent as Sentry Extra Context.

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.

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

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

Log Level Mapping

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

{
  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