rotating-file-stream
Advanced tools
Opens a stream.Writable to a file rotated by interval and/or size. A logrotate alternative.
var rfs = require('rotating-file-stream');
var stream = rfs('file.log', {
size: '10M', // rotate every 10 MegaBytes written
interval: '1d', // rotate daily
compress: 'gzip' // compress rotated files
});
With npm:
npm install rotating-file-stream
require('rotating-file-stream');
Returns RotatingFileStream constructor.
Extends stream.Writable.
Returns a new RotatingFileStream to filename as fs.createWriteStream does. 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.
An example of a complex rotated file name generator function could be:
function pad(num) {
return (num > 9 ? "" : "0") + num;
}
function 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 "/storage/" + month + "/" +
month + day + "-" + hour + minute + "-" + index + "-" + filename;
}
var rfs = require('rotating-file-stream');
var stream = rfs(generator, {
size: '10M',
interval: '1d'
});
Note: If part of returned destination path does not exists, the rotation job will try to create it.
If present, it is prepended to generated file names.
Accepts a positive integer followed by one of these possible letters:
size: '300B', // rotates the file when its size exceeds 300 Bytes
// useful for tests
size: '300K', // rotates the file when its size exceeds 300 KiloBytes
size: '100M', // rotates the file when its size exceeds 100 MegaBytes
size: '1G', // rotates the file when its size exceeds a GigaByte
Accepts a positive integer followed by one of these possible letters:
interval: '5s', // rotates the file at seconds 0, 5, 10, 15 and so on
// useful for tests
interval: '5m', // rotates the file at minutes 0, 5, 10, 15 and so on
interval: '2h', // rotates the file at midnight, 02:00, 04:00 and so on
interval: '1d', // rotates the file at every midnight
Due the nature of Node.js compression may be done with an external command (to use other CPUs than the one used by Node.js) or with internal code (to use the CPU used by Node.js). This decision is left to you.
Following fixed strings are allowed to compress the files with internal libraries:
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('file.log', {
size: '10M',
compress: true
});
var rfs = require('rotating-file-stream');
var stream = rfs('file.log', {
size: '10M',
compress: function(source, dest) {
return "cat " + source + " | gzip -c9 > " + dest;
}
});
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.
Custom Events are emitted by the stream.
var rfs = require('rotating-file-stream');
var stream = rfs(...);
stream.on('error', function(err) {
// here are reported blocking errors
// once this event is fired, the stream will be closed as well
});
stream.on('open', function() {
// no rotated file is open (fired after each rotation as well)
});
stream.on('rotation', function() {
// rotation job started
});
stream.on('rotated', function(filename) {
// rotation job completed with success and produced given filename
});
stream.on('warning', function(err) {
// here are reported non blocking errors
});
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 may be called several times for each rotation job.
Once an error event is emitted, nothing more can be done: the stream is closed as well.
This package is written following Node.js 4.0 specifications always taking care about backward compatibility. The package it tested under following versions:
Required: Node.js 0.11
Do not hesitate to report any bug or inconsistency @github.
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 66,534 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.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.