rotating-file-stream
Advanced tools
Opens a stream.Writable to a file rotated by interval and/or size. A logrotate alternative.
Creates a stream.Writable to a file which is rotated. Rotation behavior can be deeply customized; optionally, classical UNIX logrotate behavior can be used.
const rfs = require("rotating-file-stream");
const stream = rfs.createStream("file.log", {
size: "10M", // rotate every 10 MegaBytes written
interval: "1d", // rotate daily
compress: "gzip" // compress rotated files
});
With npm:
$ npm install --save rotating-file-stream
In v3 the package was completely refactored using async / await.
TypeScript types for events and the external event were added.
Breaking change: by default the .gz extension is added to the rotated compressed files.
Breaking change: the way the external compression command is executed was slightly changed; possible breaking change.
To maintain back compatibility upgrading from v2 to v3, just follow this rules:
options.compress: nothing to dooptions.compress: use options.omitExtension or check
how rotated files are treated.There are two main changes in package interface.
In v1 the default export of the package was directly the RotatingFileStream constructor and the caller have to use it; while in v2 there is no default export and the caller should use the createStream exported function and should not directly use RotatingFileStream class. This is quite easy to discover: if this change is not applied, nothing than a runtime error can happen.
The other important change is the removal of option rotationTime and the introduction of intervalBoundary.
In v1 the time argument passed to the filename generator function, by default, is the time when rotation job
started, while if options.interval option is used, it is the lower boundary of the time interval within
rotation job started. Later I was asked to add the possibility to restore the default value for this argument so I
introduced options.rotationTime option with this purpose. At the end the result was something a bit confusing,
something I never liked.
In v2 the time argument passed to the filename generator function is always the time when rotation job
started, unless options.intervalBoundary option is used. In a few words, to maintain back
compatibility upgrading from v1 to v2, just follow this rules:
options.rotation: nothing to dooptions.rotation:
options.interval: nothing to dooptions.interval:
options.rotationTime: to remove itoptions.rotationTime: then use options.intervalBoundary.const rfs = require("rotating-file-stream");
filename <string> |
<Function> The name
of the file or the function to generate it, called file name generator. See below for
details.options <Object>
Rotation options, See below for details.This interface is inspired to fs.createWriteStream one. The file is rotated following options rules.
The most complex problem about file name is: how to call the rotated file name?
The answer to this question may vary in many forms depending on application requirements and/or specifications.
If there are no requirements, a string can be used and default rotated file name generator will be used;
otherwise a Function which returns the rotated file name can be used.
Note: if part of returned destination path does not exists, the rotation job will try to create it.
time <Date>
options.interval and intervalBoundary options are enabled: the start
time of rotation period.If null, the not-rotated file name must be returned.
index <number> The
progressive index of rotation by size in the same rotation period.
An example of a complex rotated file name generator function could be:
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"
});
Note:
if both of options.interval options.size are used, returned rotated file name must be
function of both arguments time and index.
index <number> The
progressive index of rotation. If null, the not-rotated file name must be returned.If classical logrotate behavior is enabled (by options.rotate), rotated file name is only a
function of index.
Extends stream.Writable. It should not be directly
used. Exported only to be used with instanceof operator and similar.
stdout <string> The
standard output of the external compression command.stderr <string> The
standard error of the external compression command.The external event is emitted once an external compression command completes its execution to give access to the
command output streams.
The history event is emitted once the history check job is completed.
filename <string> Is
constant unless options.immutable is true.The open event is emitted once the not-rotated file is opened.
filename <string> The
name of the removed file.number <boolean>
true if the file was removed due to options.maxFilesfalse if the file was removed due to options.maxSizeThe removed event is emitted once a rotated file is removed due to options.maxFiles or
options.maxSize.
The rotation event is emitted once the rotation job is started.
filename <string> The
rotated file name produced.The rotated event is emitted once the rotation job is completed.
error <Error> The
non blocking error.The warning event is emitted once a non blocking error happens.
compress:
<boolean> |
<string> |
<Function>
Specifies compression method of rotated files. Default: null.encoding:
<string>
Specifies the default encoding. Default: 'utf8'.history:
<string>
Specifies the history filename. Default: null.immutable:
<boolean>
Never mutate file names. Default: null.initialRotation:
<boolean>
Initial rotation based on not-rotated file timestamp. Default: null.interval:
<string>
Specifies the time interval to rotate the file. Default: null.intervalBoundary:
<boolean>
Makes rotated file name with lower boundary of rotation period. Default: null.intervalUTC:
<boolean>
Boundaries for rotation are computed in UTC. Default: null.maxFiles:
<number>
Specifies the maximum number of rotated files to keep. Default: null.maxSize:
<string>
Specifies the maximum size of rotated files to keep. Default: null.mode:
<number>
Forwarded to fs.createWriteStream.
Default: 0o666.omitExtension:
<boolean>
Omits the .gz extension from compressed rotated files. Default: null.path:
<string>
Specifies the base path for files. Default: null.rotate:
<number>
Enables the classical UNIX logrotate behavior. Default: null.size:
<string>
Specifies the file size to rotate the file. Default: null.teeToStdout:
<boolean>
Writes file content to stdout as well. Default: null.Specifies the default encoding that is used when no encoding is specified as an argument to stream.write().
Forwarded to fs.createWriteStream.
If present, it is prepended to generated file names as well as for history file.
If true, it makes the file content to be written to stdout as well. Useful for debugging purposes.
Accepts a positive integer followed by one of these possible letters:
size: '300B', // rotates the file when size exceeds 300 Bytes
// useful for tests
size: '300K', // rotates the file when size exceeds 300 KiloBytes
size: '100M', // rotates the file when size exceeds 100 MegaBytes
size: '1G', // rotates the file when size exceeds a GigaByte
Accepts a positive integer followed by one of these possible letters:
interval: '5s', // rotates at seconds 0, 5, 10, 15 and so on
// useful for tests
interval: '5m', // rotates at minutes 0, 5, 10, 15 and so on
interval: '2h', // rotates at midnight, 02:00, 04:00 and so on
interval: '1d', // rotates at every midnight
interval: '1M', // rotates at every midnight between two distinct months
If set to true, the argument time of filename generator is no longer the time when rotation job started, but
the lower boundary of rotation interval.
Note:
this option has effect only if options.interval is used.
If set to true, the boundaries of the rotation interval are computed against UTC time rather than against system time
zone.
Note:
this option has effect only if options.intervalBoundary is used.
The best choice here is to use the value "gzip" to use Node.js internal compression library.
For historical reasons external compression can be used.
To enable external compression, a function can be used or simply the boolean true value to use default
external compression.
The function should accept source and dest file names and must return the shell command to be executed to
compress the file.
The two following code snippets have exactly the same effect:
var rfs = require("rotating-file-stream");
var stream = rfs.createStream("file.log", {
size: "10M",
compress: true
});
var rfs = require("rotating-file-stream");
var stream = rfs.createStream("file.log", {
size: "10M",
compress: (source, dest) => `cat ${source} | gzip -c9 > ${dest}`
});
Note:
this option is ignored if options.immutable is used.
Note: the shell command to compress the rotated file should not remove the source file, it will be removed by the package if rotation job complete with success.
From v3 the package adds by default the .gz extension to the rotated compressed files. Simultaneously this option
was added: set this option to true to not add the extension, i.e. to keep backward compatibility.
When program stops in a rotation period then restarts in a new rotation period, logs of different rotation period will
go in the next rotated file; in a few words: a rotation job is lost. If this option is set to true an initial check
is performed against the not-rotated file timestamp and, if it falls in a previous rotation period, an initial
rotation job is done as well.
Note:
this option has effect only if both options.interval and options.intervalBoundary
are used.
Note:
this option is ignored if options.rotate is used.
If specified, classical UNIX logrotate behavior is enabled and the value of this option has same effect in logrotate.conf file.
Note:
if this option is used following ones take no effect: options.history, options.immutable,
options.initialRotation, options.intervalBoundary,
options.maxFiles, options.maxSize.
If set to true, names of generated files never changes. New files are immediately generated with their rotated
name. In other words the rotated file name generator is never called with a null time argument unless to
determinate the history file name; this can happen if options.history is not used while
options.maxFiles or options.maxSize are used.
The filename argument passed to 'open' event evaluates now as the newly created file name.
Useful to send logs to logstash through filebeat.
Note:
if this option is used, options.compress is ignored.
Note:
this option is ignored if options.interval is not used.
Due to the complexity that rotated file names can have because of the filename generator function, if number or
size of rotated files should not exceed a given limit, the package needs a file where to store this information. This
option specifies the name history file. This option takes effect only if at least one of
options.maxFiles or options.maxSize is used. If null, the not rotated filename with
the '.txt' suffix is used.
If specified, it's value is the maximum number of rotated files to be kept.
If specified, it's value must respect same syntax of option.size and is the maximum size of rotated files to be kept.
Regardless of when and why rotation happens, the content of a single stream.write will never be split among two files.
Once the not-rotated file is opened first time, its size is checked and if it is greater or equal to size limit, a first rotation happens. After each stream.write, the same check is performed.
The package sets a Timeout to start a rotation job at the right moment.
Logs should be handled so carefully, so this package tries to never overwrite files.
At stream creation, if the not-rotated log file already exists and its size exceeds the rotation size, an initial rotation attempt is done.
At each rotation attempt a check is done to verify that destination rotated file does not exists yet; if this is not the case a new destination rotated file name is generated and the same check is performed before going on. This is repeated until a not existing destination file name is found or the package is exhausted. For this reason the rotated file name generator function could be called several times for each rotation job.
If requested through options.maxFiles or options.maxSize, at the end of a rotation job, a
check is performed to ensure that given limits are respected. This means that
while rotation job is running both the limits could be not respected. The same can happen till the end of first
rotation job if options.maxFiles or options.maxSize are changed between two runs.
The first check performed is the one against options.maxFiles, in case some files are removed, then the
check against options.maxSize is performed, finally other files can be removed. When
options.maxFiles or options.maxSize are enabled for first time, an history file can be
created with one rotated filename (as returned by filename generator function) at each line.
Once an error event is emitted, nothing more can be done: the stream is closed as well.
Requires Node.js v14.
The package is tested under all Node.js versions currently supported accordingly to Node.js Release.
To work with the package under Windows, be sure to configure bash.exe as your script-shell.
> npm config set script-shell bash.exe
TypeScript types are distributed with the package itself.
Do not hesitate to report any bug or inconsistency @github.
If you find useful this package, please consider the opportunity to donate some satoshis to this bitcoin address: 12p1p5q7sK75tPyuesZmssiMYr4TKzpSCN
The winston-daily-rotate-file package is a transport for the winston logging library that allows you to rotate log files based on a time interval. It is similar to rotating-file-stream in that it supports time-based rotation and compression, but it is specifically designed to work with the winston logging library.
The logrotate-stream package provides a writable stream that rotates log files based on size or time. It is similar to rotating-file-stream in terms of functionality, but it offers a simpler API and fewer configuration options.
The file-stream-rotator package is another option for rotating log files based on size or time. It offers similar features to rotating-file-stream, including time-based and size-based rotation, as well as compression. However, it is less actively maintained compared to rotating-file-stream.
FAQs
Opens a stream.Writable to a file rotated by interval and/or size. A logrotate alternative.
The npm package rotating-file-stream receives a total of 125,587 weekly downloads. As such, rotating-file-stream popularity was classified as popular.
We found that rotating-file-stream demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket researchers discovered nine malicious NuGet packages that use time-delayed payloads to crash applications and corrupt industrial control systems.
Security News
Socket CTO Ahmad Nassri discusses why supply chain attacks now target developer machines and what AI means for the future of enterprise security.
Security News
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.