view release on metacpan or  search on metacpan

lib/File/Write/Rotate.pm  view on Meta::CPAN

=item * hook_before_write => CODE

=item * hook_before_rotate => CODE

=item * hook_after_rotate => CODE

=item * hook_after_create => CODE

See L</ATTRIBUTES>.

=item * buffer_size => int

=item * rotate_probability => float (between 0 < x < 1)

If set, instruct to only check for rotation under a certain probability, for
example if value is set to 0.1 then will only check for rotation 10% of the
time.

=back

=head2 lock_file_path => STR

Returns a string representing the complete pathname to the lock file, based
on C<dir> and C<prefix> attributes.

=head2 $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 you'll have to do it yourself.

=head2 $fwr->compress

Compress old rotated files and remove the uncompressed originals. Currently uses
L<IO::Compress::Gzip> to do the compression. Extension given to compressed file
is C<.gz>.

Will not lock writers, but will create C<< <prefix> >>C<-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 C<write()> if necessary.

=head1 FAQ

=head2 Why use autorotating file?

Mainly convenience and low maintenance. You no longer need a separate rotator
process like the Unix B<logrotate> utility (which when accidentally disabled or
misconfigured will cause your logs to stop being rotated and grow indefinitely).

=head2 What is the downside of using FWR (and LDFR)?

Mainly (significant) performance overhead. At (almost) every C<write()>, FWR
needs to check file sizes and/or dates for rotation. Under default configuration
(where C<lock_mode> is C<write>), it also performs locking on each C<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
C<lock_mode> C<none> or C<exclusive>, the speed is ~52k/s.

However, this is not something you'll notice or need to worry about unless
you're writing near that speed.

If you need more speed, you can try setting C<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.

=head2 I want a filehandle instead of a File::Write::Rotate object!

Use L<Tie::Handle::FileWriteRotate>.

=head1 HOMEPAGE

Please visit the project's homepage at L<https://metacpan.org/release/File-Write-Rotate>.

=head1 SOURCE

Source repository is at L<https://github.com/perlancar/perl-File-Write-Rotate>.

=head1 BUGS

Please report any bugs or feature requests on the bugtracker website L<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.

=head1 SEE ALSO

L<Log::Dispatch::FileRotate>, which inspires this module. Differences between
File::Write::Rotate (FWR) and Log::Dispatch::FileRotate (LDFR) are as follows:

=over

=item * FWR is not part of the L<Log::Dispatch> family.

This makes FWR more general to use.

For using together with Log::Dispatch/Log4perl, I have also written
L<Log::Dispatch::FileWriteRotate> which is a direct (although not a perfect
drop-in) replacement for Log::Dispatch::FileRotate.

=item * Secondly, FWR does not use L<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.