A Sentry Transport for Winston@3

A Sentry transport for Wiston@3 using @sentry/node that allows logging context data, such as user, tags, fingerprint, and extra data. Learn more checking the Sentry Documentation.

Installation

# npm
npm install sentry-transport-winston

# yarn
yarn add sentry-transport-winston

Initializing

import { SentryTransport } from 'sentry-transport-winston';

const opts: SentryTransportOpts = {
  sentryOpts: {
    dns: '<sentry-dns>',
  },
};

const sentry = new SentryTransport(opts);

const logger = winston.createLogger({
  transports: [sentry],
});

Transport Options

The SentryTransportOpts interface is extending the TransportStreamOptions so you can pass any options that are handled by the base winston transport stream, such as format. Take a look here to see all the available options.

Sentry Options

The SentryTransportOpts includes the property sentryOpts which is passed directly to the Sentry.init() method, without any changes. All available options can be found on Sentry documentation.

Levels Mapping

SentryTransport is using the npm logging levels by default (just like winston does) and mapping them to Sentry logging levels:

export const DEFAULT_LEVELS_MAP: SentryLevelsMap = {
  error: Severity.Error,
  warn: Severity.Warning,
  info: Severity.Info,
  verbose: Severity.Info,
  debug: Severity.Debug,
  silly: Severity.Debug,
};

If you're using different logging levels, you can pass a custom map using the levelsMap option.

Logging

Simple message

logger.info('Error message.');

Error message

logger.error(new Error('Error message'));

Tags

You can tag an event using the tags property:

const tags = { module: 'users', language: 'english' };

logger.error('Error message.', { tags });

User

You can capture the user using the user property:

const user = { username: 'test-user' };

logger.error('Error message.', { user });

The user object must have at least one of the following properties: id, email, username or ip_address. Otherwise it will be logged as extra data.

Fingerprint

You can set a fingerprint using the fingerprint property.

const fingerprint = ['{{ default }}', 'my-fingerprint'];

logger.error('Error message.', { fingerprint });

If the fingerprint is not an array it will be converted to one.

const fingerprint = 'my-fingerprint'; // it'll be converted to ['my-fingerprint'];

logger.error('Error message.', { fingerprint });

Extra data

Any other data which is not named as tags, user or fingerprint will be logged as extra data.

logger.error('Error message.', { url: '/users', input: 'some-input' });

License

This project is MIT Licensed.