NAME¶
File::Write::Rotate - Write to files that archive/rotate themselves
VERSION¶
This document describes version 0.22 of File::Write::Rotate (from Perl
distribution File-Write-Rotate), released on 2014-09-01.
SYNOPSIS¶
use File::Write::Rotate;
my $fwr = File::Write::Rotate->new(
dir => '/var/log', # required
prefix => 'myapp', # required
#suffix => '.log', # default is ''
size => 25*1024*1024, # default is 10MB, unless period is set
histories => 12, # default is 10
#buffer_size => 100, # default is none
);
# write, will write to /var/log/myapp.log, automatically rotate old log files
# to myapp.log.1 when myapp.log reaches 25MB. will keep old log files up to
# myapp.log.12.
$fwr->write("This is a line\n");
$fwr->write("This is", " another line\n");
# compress old log files
$fwr->compress;
DESCRIPTION¶
This module can be used to write to file, usually for logging, that can rotate
itself. File will be opened in append mode. Locking will be done to avoid
conflict when there are multiple writers. Rotation can be done by size (after
a certain size is reached), by time (daily/monthly/yearly), or both.
I first wrote this module for logging script STDERR output to files (see
Tie::Handle::FileWriteRotate).
ATTRIBUTES¶
buffer_size => int¶
Get or set buffer size. If set to a value larger than 0, then when a
write() failed, instead of dying, the message will be stored in an
internal buffer first (a regular Perl array). When the number of items in the
buffer exceeds this size, then
write() will die upon failure.
Otherwise, every
write() will try to flush the buffer.
Can be used for example when a program runs as superuser/root then temporarily
drops privilege to a normal user. During this period, logging can fail because
the program cannot lock the lock file or write to the logging directory.
Before dropping privilege, the program can set buffer_size to some
larger-than-zero value to hold the messages emitted during dropping privilege.
The next
write() as the superuser/root will succeed and flush the
buffer to disk (provided there is no other error condition, of course).
path => str (ro)¶
Current file's path.
handle => (ro)¶
Current file handle. You should not use this directly, but use
write()
instead. This attribute is provided for special circumstances (e.g. in hooks,
see example in the hook section).
hook_before_write => code¶
Will be called by
write() before actually writing to filehandle (but
after locking is done). Code will be passed ($self, \@msgs, $fh) where @msgs
is an array of strings to be written (the contents of buffer, if any, plus
arguments passed to
write()) and $fh is the filehandle.
hook_before_rotate => code¶
Will be called by the rotating routine before actually doing rotating. Code will
be passed ($self).
This can be used to write a footer to the end of each file, e.g.:
# hook_before_rotate
my ($self) = @_;
my $fh = $self->handle;
print $fh "Some footer\n";
Since this hook is indirectly called by
write(), locking is already done.
hook_after_rotate => code¶
Will be called by the rotating routine after the rotating process. Code will be
passed ($self, \@renamed, \@deleted) where @renamed is array of new filenames
that have been renamed, @deleted is array of new filenames that have been
deleted.
hook_after_create => code¶
Will be called by after a new file is created. Code will be passed ($self).
This hook can be used to write a header to each file, e.g.:
# hook_after_create
my ($self) = @_;
my $fh $self->handle;
print $fh "header\n";
Since this is called indirectly by
write(), locking is also already done.
METHODS¶
$obj = File::Write::Rotate->new(%args)¶
Create new object. Known arguments:
- •
- dir => STR (required)
Directory to put the files in.
- •
- prefix => STR (required)
Name of files. The files will be named like the following:
<prefix><period><suffix><rotate_suffix>
"<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":
myapp # current file
myapp.1 # most recently rotated
myapp.2 # the next most recently rotated
With "prefix" set to "myapp", "period" set to
"monthly", "suffix" set to ".log":
myapp.2012-12.log # file name for december 2012
myapp.2013-01.log # file name for january 2013
Like previous, but additionally with "size" also set (which will
also rotate each period file if it exceeds specified size):
myapp.2012-12.log # file(s) for december 2012
myapp.2012-12.log.1
myapp.2012-12.log.2
myapp.2013-01.log # file(s) for january 2013
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.
$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. Uses locking, so multiple writers do not
clobber one another. Lock file is named
"<prefix>"".lck". Will wait for up to 1 minute to
acquire lock, will die if failed to acquire lock.
Does not append newline so you'll have to do it yourself.
$fwr->compress¶
Compress old rotated files. 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.
After compression is finished, will remove the PID file, so rotation can be done
again on the next "write()" if necessary.
FAQ¶
Why use autorotating file?¶
Mainly convenience and low maintenance. You no longer need a separate rotator
like the Unix
logrotate utility (which when accidentally disabled or
misconfigured will cause your logs to stop being rotated and grow
indefinitely).
What is the downside of using FWR (and LDFR)?¶
Mainly performance overhead, as every
write() involves locking to make it
safe to use with multiple processes. Tested on my Core i5 3.1 GHz 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 comes down to around 19.5k/s.
However, this is not something you'll notice or need to worry about unless
you're writing near that speed.
TODO¶
Perhaps an option to disable locking.
SEE ALSO¶
Log::Dispatch::FileRotate, which inspires this module. Differences between
File::Write::Rotate (FWR) and Log::Dispatch::FileRotate (LDFR) are as follows:
- •
- FWR is not part of the Log::Dispatch family.
This makes FWR more general to use.
For using together with Log::Dispatch/Log4perl, I have also written
Log::Dispatch::FileWriteRotate which is a direct (although not a perfect
drop-in) replacement for Log::Dispatch::FileRotate.
- •
- Secondly, FWR does not use Date::Manip.
Date::Manip is relatively large (loading Date::Manip 6.37 equals to loading
34 files and ~ 22k lines; while FWR itself is only < 1k lines!)
As a consequence of this, FWR does not support DatePattern; instead, FWR
replaces it with a simple daily/monthly/yearly period.
- •
- And lastly, FWR supports compressing and rotating compressed old files.
Using separate processes like the Unix logrotate 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.
There is no significant overhead difference between FWR and LDFR (FWR is
slightly faster than LDFR on my testing).
Tie::Handle::FileWriteRotate and Log::Dispatch::FileWriteRotate, which use this
module.
HOMEPAGE¶
Please visit the project's homepage at
<
https://metacpan.org/release/File-Write-Rotate>.
SOURCE¶
Source repository is at
<
https://github.com/perlancar/perl-File-Write-Rotate>.
BUGS¶
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.
AUTHOR¶
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.