Winston

In winston, log messages are handled as info objects within an objectMode stream. Every info object must contain at least a level and a message property.

Any additional properties provided are treated as meta (metadata).

Important Note on Message Concatenation: If you provide a message property inside a metadata object, winston will automatically concatenate it to the primary message. For example: logger.info('hello', { message: 'world' }); results in a message of 'hello world'.

Commonly added properties by formats:

• splat: Used by splat() for string interpolation (%d, %s).
• timestamp: Added by timestamp().
• label: Added by label().
• ms: Added by ms() (milliseconds since last log).

// The structure of an info object
const info = {
  level: 'info',                 // Level of the logging message
  message: 'Hey! Log something?', // Descriptive message
  requestId: '123'               // Custom metadata
};

In winston@3.x.x, the concepts of filters and rewriters from winston@2 have been unified into the formats API. Because info objects are mutable in winston@3, you can implement both filtering (returning a modified or original object) and rewriting (changing property values) using custom formats.

Example: Implementing a Filter

To filter or mask sensitive information, create a custom format that modifies the info.message and return the info object.

Example: Implementing a Rewriter

To rewrite data (e.g., masking credit card numbers), create a custom format that modifies existing properties on the info object.

Use format.combine() to chain your custom logic with standard formats like format.json() or format.printf().

const { createLogger, format, transports } = require('winston');

// Custom filter/rewriter format
const maskFormat = format((info) => {
  if (info.creditCard) {
    info.creditCard = maskCardNumbers(info.creditCard);
  }
  info.hasCreditCard = !!info.creditCard;
  return info;
});

const logger = createLogger({
  format: format.combine(
    maskFormat(),
    format.json()
  ),
  transports: [new transports.Console()]
});

logger.info('transaction ok', { creditCard: 123456789012345 });

You can create a custom format to filter out specific log entries. If a format's transform function returns a falsey value, the info object is ignored, and subsequent formats in a combine chain will not be executed for that entry.

const { createLogger, format, transports } = require('winston');

// Ignore log messages if they have { private: true }
const ignorePrivate = format((info, opts) => {
  if (info.private) { return false; }
  return info;
});

const logger = createLogger({
  format: format.combine(
    ignorePrivate(),
    format.json()
  ),
  transports: [new transports.Console()]
});

// Outputs: {"level":"error","message":"Public error to share"}
logger.log({
  level: 'error',
  message: 'Public error to share'
});

// Messages with { private: true } will not be written when logged.
logger.log({
  private: true,
  level: 'error',
  message: 'This is super secret - hide it.'
});

For complex applications, you can manage multiple logger instances with different configurations (formats, transports, levels) using a Container.

winston.loggers is a predefined instance of winston.Container that allows you to define named loggers that can be retrieved anywhere in your application by their name.

Alternatively, you can instantiate your own new winston.Container() to manage a private set of loggers.

const winston = require('winston');
const { format } = winston;
const { combine, label, json } = format;

// 1. Configure named loggers in the global container
winston.loggers.add('category1', {
  format: combine(
    label({ label: 'category one' }),
    json()
  ),
  transports: [
    new winston.transports.Console({ level: 'silly' }),
    new winston.transports.File({ filename: 'somefile.log' })
  ]
});

winston.loggers.add('category2', {
  format: combine(
    label({ label: 'category two' }),
    json()
  ),
  transports: [
    new winston.transports.Http({ host: 'localhost', port:8080 })
  ]
});

// 2. Retrieve them anywhere in your app
const category1 = winston.loggers.get('category1');
const category2 = winston.loggers.get('category2');

category1.info('logging to file and console transports');
category2.info('logging to http transport');

Winston can catch and log uncaughtException events. You can enable this in three ways:

1. During logger creation: Use the exceptionHandlers array.
2. After creation: Use logger.exceptions.handle(transport).
3. On a per-transport basis: Set handleExceptions: true on a specific transport.

If you want to prevent the process from exiting after an exception is logged, set exitOnError: false (or provide a function to determine if the error should trigger an exit).

const { createLogger, transports } = require('winston');

// 1. Enable via exceptionHandlers
const logger = createLogger({
  transports: [
    new transports.File({ filename: 'combined.log' })
  ],
  exceptionHandlers: [
    new transports.File({ filename: 'exceptions.log' })
  ]
});

// 2. Enable via .exceptions.handle()
logger.exceptions.handle(
  new transports.File({ filename: 'exceptions.log' })
);

// 3. Enable via transport option
winston.add(new winston.transports.File({
  filename: 'path/to/combined.log',
  handleExceptions: true
}));

// Control exit behavior
const loggerWithNoExit = winston.createLogger({ exitOnError: false });

// Control exit behavior with a predicate function
function ignoreEpipe(err) {
  return err.code !== 'EPIPE';
}
const loggerWithCustomExit = winston.createLogger({ exitOnError: ignoreEpipe });