NAME
    File::Write::Rotate - Write to files that archive/rotate themselves

VERSION
    This document describes version 0.16 of File::Write::Rotate (from Perl
    distribution File-Write-Rotate), released on 2014-07-10.

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).

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 pigz or gzip program to do
    the compression. Extension given to compressed file is ".gz".

    Normally, should be done using a separate process so as to avoid
    blocking the writers.

    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.

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 log 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.

FAQ
  Why use autorotating log?
    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 log 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 logging near that speed.

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

SOURCE
    Source repository is at
    <https://github.com/sharyanto/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
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.