winston-transport-sentry-node

3.0.0 verified Sat Apr 25 auth: no javascript

Winston v3 transport for sending logs to Sentry using @sentry/node. Version 3.0.0 requires @sentry/node >= 8.13.0. It integrates Sentry's error tracking and context (tags, user, extras) into the winston logging pipeline. Supports log level mapping, custom formats, and silent mode. Ships TypeScript types. Released under MIT license.

Common errors

error TypeError: winston_transport_sentry_node_1.default is not a constructor ↓

cause CommonJS require without .default

fix

const SentryTransport = require('winston-transport-sentry-node').default;

error Error: @sentry/node has not been initialized. Please call Sentry.init() first. ↓

cause Forgetting to call Sentry.init() before using the transport

fix

Add Sentry.init({ dsn: 'https://...@...' }); before creating the transport

error TypeError: Cannot destructure property 'Sentry' of 'undefined' or 'null' ↓

cause Older versions expected Sentry as an option in sentry object

fix

Remove 'Sentry' property from sentry options and import/require @sentry/node separately

error AggregateError: The transport is not a valid transport, expected a Transport instance or a function returning a Transport ↓

cause Importing wrong export (named instead of default) in winston.add

fix

Ensure you use default import: new (require('winston-transport-sentry-node').default)({...})

Warnings

breaking Version 3.0.0 requires @sentry/node >= 8.13.0 (breaking change from earlier versions) ↓

fix Upgrade @sentry/node to ^8.13.0 or downgrade winston-transport-sentry-node to 2.x

breaking Version 3.0.0 drops support for Node.js < 8.10.0 ↓

fix Upgrade Node.js to 8.10.0 or later

deprecated Deprecated: winston-transport-sentry-node now uses @sentry/node v8 which has breaking API changes. Sentry.init() is now required before using the transport. ↓

fix Initialize Sentry globally with Sentry.init() and pass empty sentry option object to the transport

gotcha Default import requires .default in CommonJS. Many users mistakenly use named import or omit .default. ↓

fix Use const SentryTransport = require('winston-transport-sentry-node').default;

gotcha Transport expects sentry option object. If omitted, it will default to reading from process.env, which may cause silent failures. ↓

fix Always provide a sentry option object (can be empty) to avoid unexpected behavior

Install

npm install winston-transport-sentry-node

yarn add winston-transport-sentry-node

pnpm add winston-transport-sentry-node

Imports

default
wrong
```
import { default } from 'winston-transport-sentry-node'
```
correct
```
import SentryTransport from 'winston-transport-sentry-node'
```
The package exports a default class. Use default import in ESM. CommonJS: const SentryTransport = require('winston-transport-sentry-node').default;

SentryTransport

wrong

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

correct

import SentryTransport from 'winston-transport-sentry-node'

No named export; always use default import.

Transport

wrong

const Transport = require('winston-transport-sentry-node')

correct

import Transport from 'winston-transport-sentry-node'

CommonJS users must call .default on require result.

Quickstart

Initialize Sentry globally, create a winston logger with the Sentry transport, and log an error with tags sent to Sentry.

import winston from 'winston';
import SentryTransport from 'winston-transport-sentry-node';
import * as Sentry from '@sentry/node';

Sentry.init({
  dsn: process.env.SENTRY_DSN || '',
});

const logger = winston.createLogger({
  transports: [
    new SentryTransport({
      sentry: {},
      level: 'error',
    }),
  ],
});

logger.info('This will not be sent to Sentry (level info)');
logger.error('This will be sent to Sentry', { tags: { route: '/api' } });