winston-daily-rotate-file

What is winston-daily-rotate-file?

The winston-daily-rotate-file npm package is a transport plugin for the winston logger that outputs log messages to a file, rotating the file automatically based on time, size, or both. It is commonly used to manage log files, ensuring they are kept to a manageable size and are rotated out over time for archival purposes.

What are winston-daily-rotate-file's main functionalities?

Time-based log rotation

This feature allows logs to be rotated daily. The '%DATE%' pattern in the filename is replaced with the current date in the 'YYYY-MM-DD' format. Logs older than 14 days are deleted, and logs are zipped when they are rotated.

const winston = require('winston');
const DailyRotateFile = require('winston-daily-rotate-file');

const logger = winston.createLogger({
  transports: [
    new DailyRotateFile({
      filename: 'application-%DATE%.log',
      datePattern: 'YYYY-MM-DD',
      zippedArchive: true,
      maxSize: '20m',
      maxFiles: '14d'
    })
  ]
});

Size-based log rotation

This feature allows logs to be rotated when they reach a certain size. In this example, the log file is rotated when it reaches 20 megabytes. The 'maxFiles' option is set to 5, which means that a maximum of 5 rotated log files will be kept.

const winston = require('winston');
const DailyRotateFile = require('winston-daily-rotate-file');

const logger = winston.createLogger({
  transports: [
    new DailyRotateFile({
      filename: 'application-%DATE%.log',
      datePattern: 'YYYY-MM-DD',
      zippedArchive: true,
      maxSize: '20m',
      maxFiles: '5'
    })
  ]
});

Customizable file compression

This feature allows the rotated log files to be compressed using gzip. The 'zippedArchive' option is set to true, enabling this functionality.

const winston = require('winston');
const DailyRotateFile = require('winston-daily-rotate-file');

const logger = winston.createLogger({
  transports: [
    new DailyRotateFile({
      filename: 'application-%DATE%.log',
      datePattern: 'YYYY-MM-DD',
      zippedArchive: true
    })
  ]
});

Other packages similar to winston-daily-rotate-file

rotating-file-stream

This package provides a stream that writes logs to a file and rotates it based on time or size, similar to winston-daily-rotate-file. It is not tied to any specific logging library and can be used with any Node.js stream-compatible logging tool.

file-stream-rotator

Similar to winston-daily-rotate-file, this package is used to rotate logs on a time basis. It does not depend on winston and can be used independently to manage log file rotation in any Node.js application.

bunyan-rotating-file-stream

This package is a rotating file stream for the Bunyan logging library. It offers functionality similar to winston-daily-rotate-file but is specifically designed to work with Bunyan instead of winston.

README

winston-daily-rotate-file

A transport for winston which logs to a rotating file. Logs can be rotated based on a date, size limit, and old logs can be removed based on count or elapsed days.

Starting with version 2.0.0, the transport has been refactored to leverage the file-stream-rotator module. Some of the options in the 1.x versions of the transport have changed. Please review the options below to identify any changes needed.

Compatibility

Please note that if you are using winston@2, you will need to use winston-daily-rotate-file@3. winston-daily-rotate-file@4 removed support for winston@2.

Starting with version 5.0.0 this module also emits an "error" event for all low level filesystem error cases. Make sure to listen for this event to prevent crashes in your application.

This library should work starting with Node.js 8.x, but tests are only executed for Node.js 14+. Use on your own risk in lower Node.js versions.

Install

npm install winston-daily-rotate-file

Options

The DailyRotateFile transport can rotate files by minute, hour, day, month, year or weekday. In addition to the options accepted by the logger, winston-daily-rotate-file also accepts the following options:

• frequency: A string representing the frequency of rotation. This is useful if you want to have timed rotations, as opposed to rotations that happen at specific moments in time. Valid values are '#m' or '#h' (e.g., '5m' or '3h'). Leaving this null relies on datePattern for the rotation times. (default: null)
• datePattern: A string representing the moment.js date format to be used for rotating. The meta characters used in this string will dictate the frequency of the file rotation. For example, if your datePattern is simply 'HH' you will end up with 24 log files that are picked up and appended to every day. (default: 'YYYY-MM-DD')
• zippedArchive: A boolean to define whether or not to gzip archived log files. (default: 'false')
• filename: Filename to be used to log to. This filename can include the %DATE% placeholder which will include the formatted datePattern at that point in the filename. (default: 'winston.log.%DATE%')
• dirname: The directory name to save log files to. (default: '.')
• stream: Write directly to a custom stream and bypass the rotation capabilities. (default: null)
• maxSize: Maximum size of the file after which it will rotate. This can be a number of bytes, or units of kb, mb, and gb. If using the units, add 'k', 'm', or 'g' as the suffix. The units need to directly follow the number. (default: null)
• maxFiles: Maximum number of logs to keep. If not set, no logs will be removed. This can be a number of files or number of days. If using days, add 'd' as the suffix. It uses auditFile to keep track of the log files in a json format. It won't delete any file not contained in it. It can be a number of files or number of days (default: null)
• options: An object resembling https://nodejs.org/api/fs.html#fs_fs_createwritestream_path_options indicating additional options that should be passed to the file stream. (default: { flags: 'a' })
• auditFile: A string representing the path of the audit file, passed directly to file-stream-rotator as audit_file. If not specified, a file name is generated that includes a hash computed from the options object, and uses the dirname option value as the directory. (default: <dirname>/.<optionsHash>-audit.json)
• utc: Use UTC time for date in filename. (default: false)
• extension: File extension to be appended to the filename. (default: '')
• createSymlink: Create a tailable symlink to the current active log file. (default: false)
• symlinkName: The name of the tailable symlink. (default: 'current.log')
• auditHashType: Use specified hashing algorithm for audit. (default: 'sha256')
• level: Name of the logging level that will be used for the transport, if not specified option from createLogger method will be used

Usage

  var winston = require('winston');
  require('winston-daily-rotate-file');

  var transport = new winston.transports.DailyRotateFile({
    level: 'info',
    filename: 'application-%DATE%.log',
    datePattern: 'YYYY-MM-DD-HH',
    zippedArchive: true,
    maxSize: '20m',
    maxFiles: '14d'
  });
  
  transport.on('error', error => {
    // log or handle errors here
  });

  transport.on('rotate', (oldFilename, newFilename) => {
    // do something fun
  });

  var logger = winston.createLogger({
    transports: [
      transport
    ]
  });

  logger.info('Hello World!');

using multiple transports

  var winston = require('winston');
  require('winston-daily-rotate-file');

  var transport1 = new winston.transports.DailyRotateFile({
    filename: 'application-%DATE%.log',
    datePattern: 'YYYY-MM-DD-HH',
    zippedArchive: true,
    maxSize: '20m',
    maxFiles: '14d'
  });

  var transport2 = new winston.transports.DailyRotateFile({
    level: 'error',
    filename: 'application-error-%DATE%.log',
    datePattern: 'YYYY-MM-DD-HH',
    zippedArchive: true,
    maxSize: '20m',
    maxFiles: '14d'
  });

  transport1.on('error', error => {
    // log or handle errors here
  });

  transport2.on('error', error => {
    // log or handle errors here
  });

  transport1.on('rotate', function(oldFilename, newFilename) {
    // do something fun
  });

  transport2.on('rotate', function(oldFilename, newFilename) {
    // do something fun
  });

  var logger = winston.createLogger({
    level: 'info'
    transports: [
      transport1, // will be used on info level
      transport2  // will be used on error level
    ]
  });

  logger.info('Hello World!');
  logger.error('Hello Error!');

ES6

import  *  as  winston  from  'winston';
import  'winston-daily-rotate-file';


const transport = new winston.transports.DailyRotateFile({
  filename: 'application-%DATE%.log',
  datePattern: 'YYYY-MM-DD-HH',
  zippedArchive: true,
  maxSize: '20m',
  maxFiles: '14d'
});

transport.on('error', error => {
  // log or handle errors here
});

transport.on('rotate', (oldFilename, newFilename) => {
  // do something fun
});

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

logger.info('Hello World!');

Typescript

import * as winston from 'winston';
import DailyRotateFile from 'winston-daily-rotate-file';

const transport: DailyRotateFile = new DailyRotateFile({
    filename: 'application-%DATE%.log',
    datePattern: 'YYYY-MM-DD-HH',
    zippedArchive: true,
    maxSize: '20m',
    maxFiles: '14d'
});

transport.on('error', error => {
    // log or handle errors here
});


transport.on('rotate', (oldFilename, newFilename) => {
    // do something fun
});

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

logger.info('Hello World!');

This transport emits the following custom events:

• new: fired when a new log file is created. This event will pass one parameter to the callback (newFilename).
• rotate: fired when the log file is rotated. This event will pass two parameters to the callback (oldFilename, newFilename).
• archive: fired when the log file is archived. This event will pass one parameter to the callback (zipFilename).
• logRemoved: fired when a log file is removed from the file system. This event will pass one parameter to the callback (removedFilename).
• • error: fired when a low level filesystem error happens (e.g. EACCESS)

LICENSE

MIT

AUTHOR: Charlie Robbins

MAINTAINER: Matt Berther

Changelog

5.0.0 (2024-02-09)

• Converted partially to ES6
• Emit "error" event on lwo level filesystem errors to allow logging and handling of them