rotating-file-stream

If a simple string is insufficient for your naming requirements, you can provide a function as the filename argument. This function is called to determine the name of the rotated files.

Function Signature: filename(time[, index])

• time (Date):
  • By default: the time when the rotation job started.
  • If both options.interval and options.intervalBoundary are enabled: the start time of the rotation period.
  • If you return null, the generator indicates that the not-rotated file name should be used.
• index (number): The progressive index of rotation by size within the same rotation period.

Important: If both options.interval and options.size are used, the returned file name must be a function of both time and index.

If options.rotate (classical UNIX logrotate behavior) is enabled, the file name is only a function of index.

const pad = num => (num > 9 ? "" : "0") + num;
const generator = (time, index) => {
  if (!time) return "file.log";

  var month = time.getFullYear() + "" + pad(time.getMonth() + 1);
  var day = pad(time.getDate());
  var hour = pad(time.getHours());
  var minute = pad(time.getMinutes());

  return `${month}/${month}${day}-${hour}${minute}-${index}-file.log`;
};

const rfs = require("rotating-file-stream");
const stream = rfs.createStream(generator, {
  size: "10M",
  interval: "30m"
});

The package is designed to avoid overwriting existing log files.

Rotation Logic

• Initial Rotation: If the active log file already exists and exceeds the configured rotation size at stream creation, an initial rotation is triggered.
• Collision Avoidance: During rotation, the package checks if the destination rotated file name already exists. If it does, it generates a new name and repeats the check until a unique name is found.
• Limit Enforcement: If options.maxFiles or options.maxSize are configured, limits are checked at the end of a rotation job. This means limits might be temporarily exceeded while a rotation job is actively running.
• Cleanup Order: The package first checks options.maxFiles and removes files if necessary, then checks options.maxSize and removes additional files to satisfy the size constraint.
• History File: When maxFiles or maxSize are enabled for the first time, an history file may be created containing one rotated filename per line.

Error Handling

Once an error event is emitted, the stream is automatically closed and no further operations will occur.

The compress option specifies the compression method for rotated files.

• Internal Gzip: Set compress: 'gzip' to use the Node.js internal compression library.
• External Compression: Set compress: true to use default external compression, or provide a function. The function must accept (source, dest) as arguments and return a shell command string that executes the compression.

Important Notes:

• This option is ignored if options.immutable is used.
• The shell command should not remove the source file; the package handles source removal upon successful rotation.
• In v3, .gz is added to compressed files by default. Use omitExtension: true to prevent this.

var rfs = require("rotating-file-stream");
var stream = rfs.createStream("file.log", {
  size: "10M",
  compress: true
});

// Or with a custom command:
var stream = rfs.createStream("file.log", {
  size: "10M",
  compress: (source, dest) => `cat ${source} | gzip -c9 > ${dest}`
});