dir => STR (required)
Directory to put the files in.
prefix => STR (required)
Name of files. The files will be named like the following:
<period> will only be given if the period argument is set. If period is set to yearly, <period> will be YYYY (4-digit year). If period is monthly, <period> will be YYYY-MM (4-digit year and 2-digit month). If period is daily, <period> will be YYYY-MM-DD (4-digit year, 2-digit month, and 2-digit day).
<rotate_suffix> is either empty string for current file; or .1, .2 and so on for rotated files. .1 is the most recent rotated file, .2 is the next most recent, and so on.
An example, with prefix set to myapp:
With prefix set to myapp, period set to monthly, suffix set to .log:
Like previous, but additionally with size also set (which will also rotate each period file if it exceeds specified size):
All times will use local time, so you probably want to set TZ environment variable or equivalent methods to set time zone.
suffix => STR (default: )
Suffix to give to file names, usually file extension like .log. See prefix for more details.
If you use a yearly period, setting suffix is advised to avoid ambiguity with rotate suffix (for example, is myapp.2012 the current file for year 2012 or file with 2012 rotate suffix?)
size => INT (default: 10*1024*1024)
Maximum file size, in bytes, before rotation is triggered. The default is 10MB (10*1024*1024) if period is not set. If period is set, no default for size is provided, which means files will not be rotated for size (only for period).
period => STR
Can be set to either daily, monthly, or yearly. If set, will automatically rotate after period change. See prefix for more details.
histories => INT (default: 10)
Number of rotated files to keep. After the number of files exceeds this, the oldest one will be deleted. 0 means not to keep any history, 1 means to only keep .1 file, and so on.
buffer_size => INT (default: 0)
Set initial value of buffer. See the buffer_size attribute for more information.
lock_mode => STR (default: write)
Can be set to either none, write, or exclusive. none disables locking and increases write performance, but should only be used when there is only one writer. write acquires and holds the lock for each write. exclusive acquires the lock at object creation and holds it until the the object is destroyed.
Lock file is named <prefix>.lck. Will wait for up to 1 minute to acquire lock, will die if failed to acquire lock.
|o||hook_before_write => CODE|
|o||hook_before_rotate => CODE|
|o||hook_after_rotate => CODE|
hook_after_create => CODE
|o||buffer_size => int|
|o||rotate_probability => float (between 0 < x < 1)|
Returns a string representing the complete pathname to the lock file, based on dir and prefix attributes.
CW$fwr->write(@args)Write to file. Will automatically rotate file if period changes or file size exceeds specified limit. When rotating, will only keep a specified number of histories and delete the older ones.
Does not append newline so youll have to do it yourself.
CW$fwr->compressCompress old rotated files and remove the uncompressed originals. Currently uses IO::Compress::Gzip to do the compression. Extension given to compressed file is .gz.
Will not lock writers, but will create <prefix>-compress.pid PID file to prevent multiple compression processes running and to signal the writers to postpone rotation.
Mainly convenience and low maintenance. You no longer need a separate rotator process like the Unix <B>logrotateB> utility (which when accidentally disabled or misconfigured will cause your logs to stop being rotated and grow indefinitely).
Mainly (significant) performance overhead. At (almost) every write(), FWR needs to check file sizes and/or dates for rotation. Under default configuration (where lock_mode is write), it also performs locking on each write() to make it safe to use with multiple processes. Below is a casual benchmark to give a sense of the overhead, tested on my Core i5-2400 3.1GHz desktop:
Writing lines in the size of ~ 200 bytes, raw writing to disk (SSD) has the speed of around 3.4mil/s, while using FWR it goes down to around ~13k/s. Using lock_mode none or exclusive, the speed is ~52k/s.
However, this is not something youll notice or need to worry about unless youre writing near that speed.
If you need more speed, you can try setting rotate_probability which will cause FWR to only check for rotation probabilistically, e.g. if you set this to 0.1 then checks will only be done in about 1 of 10 writes. This can significantly reduce the overhead and increase write speed several times (e.g. 5-8 times), but understand that this will make the writes overflow a bit, e.g. file sizes will exceed for a bit if you do size-based rotation. More suitable if you only do size-based rotation since it is usually okay to exceed sizes for a bit.
Log::Dispatch::FileRotate, which inspires this module. Differences between File::Write::Rotate (FWR) and Log::Dispatch::FileRotate (LDFR) are as follows:
There is no significant overhead difference between FWR and LDFR (FWR is slightly faster than LDFR on my testing).
o FWR is not part of the Log::Dispatch family.
This makes FWR more general to use.
o Secondly, FWR does not use Date::Manip.
As a consequence of this, FWR does not support DatePattern; instead, FWR replaces it with a simple daily/monthly/yearly period.
o And lastly, FWR supports compressing and rotating compressed old files.
Using separate processes like the Unix <B>logrotateB> utility means having to deal with yet another race condition. FWR takes care of that for you (see the compress() method). You also have the option to do file compression in the same script/process if you want, which is convenient.
Please visit the projects homepage at <https://metacpan.org/release/File-Write-Rotate>.
Source repository is at <https://github.com/perlancar/perl-File-Write-Rotate>.
Please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Write-Rotate>
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
This software is copyright (c) 2015 by email@example.com.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
|perl v5.20.3||FILE::WRITE::ROTATE (3)||2015-10-20|