NAME
    Log::Dispatch::FileRotate - Log to files that archive/rotate themselves

SYNOPSIS
      use Log::Dispatch::FileRotate;

      my $file = Log::Dispatch::FileRotate->new( name      => 'file1',
                                           min_level => 'info',
                                           filename  => 'Somefile.log',
                                           mode      => 'append' ,
                                           size      => 10,
                                           max       => 6,
                                          );
      # or for a time based rotation

      my $file = Log::Dispatch::FileRotate->new( name      => 'file1',
                                           min_level => 'info',
                                           filename  => 'Somefile.log',
                                           mode      => 'append' ,
                                           TZ        => 'AEDT',
                                           DatePattern => 'yyyy-dd-HH',
                                          );

      $file->log( level => 'info', message => "your comment\n" );

DESCRIPTION
    This module provides a simple object for logging to files under the
    Log::Dispatch::* system, and automatically rotating them according to
    different constraints. This is basically a Log::Dispatch::File wrapper
    with additions. To that end the arguments

            name, min_level, filename and  mode

    behave the same as Log::Dispatch::File. So see its man page (perldoc
    Log::Dispatch::File)

    The arguments size and max specify the maximum size and maximum number
    of log files created. The size defaults to 10M and the max number of
    files defaults to 1. If DatePattern is not defined then we default to
    working in size mode. That is, use size values for deciding when to
    rotate.

    Once DatePattern is defined FileRotate will move into time mode. Once
    this happens file rotation ignores size constraints and uses the defined
    date pattern constraints.

    If you setup a config file using Log::Log4perl::init_and_watch() or the
    like, you can switch between modes just by commenting out the
    DatePattern line.

    When using DatePattern make sure TZ is defined correctly and that the TZ
    you use is understood by Date::Manip. We use Date::Manip to generate our
    recurrences. Bad TZ equals bad recurrences equals surprises! Read the
    Date::Manip man page for more details on TZ.

    DatePattern will default to a daily rotate if your entered pattern is
    incorrect. You will also get a warning message.

    If you have multiple writers that were started at different times you
    will find each writer will try to rotate the log file at a recurrence
    calculated from its start time. To sync all the writers just use a
    config file and update it after starting your last writer. This will
    cause Log::Dispatch::FileRotate->new() to be called by each of the
    writers close to the same time, and if your recurrences aren't too close
    together all should sync up just nicely.

    I initially aasumed a long runinng process but it seems people are using
    this module as part of short running CGI programs. So, now we look at
    the last modified time stamp of the log file and compare it to a
    previous occurance of a DatePattern, on startup only. If the file stat
    shows the mtime to be earlier than the previous recurrance then I rotate
    the log file.

    We handle multiple writers using flock().

DatePattern
    As I said earlier we use Date::Manip for generating our recurrence
    events. This means we can understand Date::Manip's recurrence patterns
    and the normal log4j DatePatterns. We don't use DatePattern to define
    the extension of the log file though.

    DatePattern can therefore take forms like:

          Date::Manip style
                0:0:0:0:5:30:0       every 5 hours and 30 minutes
                0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
                3*1:0:2:12:0:0       every 3 years on Jan 2 at noon

          DailyRollingFileAppender log4j style
                yyyy-MM              every month
                yyyy-ww              every week
                yyyy-MM-dd           every day
                yyyy-MM-dd-a         every day at noon
                yyyy-MM-dd-HH        every hour
                yyyy-MM-dd-HH-MM     every minute

    To specify multiple recurrences in a single string separate them with a
    semicolon: yyyy-MM-dd; 0:0:0:2*12:30:0

    This says we want to rotate every day AND every 2 days at 12:30. Put in
    as many as you like.

    A complete description of Date::Manip recurrences is beyond us here
    except to quote (from the man page):

               A recur description is a string of the format
               Y:M:W:D:H:MN:S .  Exactly one of the colons may
               optionally be replaced by an asterisk, or an asterisk
               may be prepended to the string.

               Any value "N" to the left of the asterisk refers to
               the "Nth" one.  Any value to the right of the asterisk
               refers to a value as it appears on a calendar/clock.
               Values to the right can be listed a single values,
               ranges (2 numbers separated by a dash "-"), or a comma
               separated list of values or ranges.  In a few cases,
               negative values are appropriate.

               This is best illustrated by example.

                 0:0:2:1:0:0:0        every 2 weeks and 1 day
                 0:0:0:0:5:30:0       every 5 hours and 30 minutes
                 0:0:0:2*12:30:0      every 2 days at 12:30 (each day)
                 3*1:0:2:12:0:0       every 3 years on Jan 2 at noon
                 0:1*0:2:12,14:0:0    2nd of every month at 12:00 and 14:00
                 1:0:0*45:0:0:0       45th day of every year
                 0:1*4:2:0:0:0        4th tuesday (day 2) of every month
                 0:1*-1:2:0:0:0       last tuesday of every month
                 0:1:0*-2:0:0:0       2nd to last day of every month

METHODS
    * new(%p)
        This method takes a hash of parameters. The following options are
        valid:

    -- name ($)
        The name of the object (not the filename!). Required.

    -- size ($)
        The maxium (or close to) size the log file can grow too.

    -- max ($)
        The maxium number of log files to create.

    -- TZ ($)
        The TimeZone time based calculations should be done in. This should
        match Date::Manip's concept of timezones and of course your machines
        timezone. Date::Manip will normally work everything out for you.
        Except in my case where EST means Eastern Standard Time in Australia
        not the US! I had to use AEST or EADT instead. Here is a list of
        Date::Manip's timezones straight from its man page.

               The following timezone names are currently understood (and
               can be used in parsing dates).  These are zones defined in
               RFC 822.

                   Universal:  GMT, UT
                   US zones :  EST, EDT, CST, CDT, MST, MDT, PST, PDT
                   Military :  A to Z (except J)
                   Other    :  +HHMM or -HHMM
                   ISO 8601 :  +HH:MM, +HH, -HH:MM, -HH

               In addition, the following timezone abbreviations are also
               accepted.

                     IDLW    -1200    International Date Line West
                     NT      -1100    Nome
                     HST     -1000    Hawaii Standard
                     CAT     -1000    Central Alaska
                     AHST    -1000    Alaska-Hawaii Standard
                     AKST    -0900    Alaska Standard
                     YST     -0900    Yukon Standard
                     HDT     -0900    Hawaii Daylight
                     AKDT    -0800    Alaska Daylight
                     YDT     -0800    Yukon Daylight
                     PST     -0800    Pacific Standard
                     PDT     -0700    Pacific Daylight
                     MST     -0700    Mountain Standard
                     MDT     -0600    Mountain Daylight
                     CST     -0600    Central Standard
                     CDT     -0500    Central Daylight
                     EST     -0500    Eastern Standard
                     SAT     -0400    Chile
                     EDT     -0400    Eastern Daylight
                     AST     -0400    Atlantic Standard
                     ADT     -0300    Atlantic Daylight
                     NDT     -0230    Newfoundland Daylight
                     AT      -0200    Azores
                     WAT     -0100    West Africa
                     GMT     +0000    Greenwich Mean
                     UT      +0000    Universal (Coordinated)
                     UTC     +0000    Universal (Coordinated)
                     WET     +0000    Western European
                     WEST    +0000    Alias for Western European
                     CET     +0100    Central European
                     FWT     +0100    French Winter
                     MET     +0100    Middle European
                     MEZ     +0100    Middle European
                     MEWT    +0100    Middle European Winter
                     SWT     +0100    Swedish Winter
                     BST     +0100    British Summer     bst=Brazil standard  -0300
                     GB      +0100    GMT with daylight savings
                     CEST    +0200    Central European Summer
                     EET     +0200    Eastern Europe, USSR Zone 1
                     FST     +0200    French Summer
                     MEST    +0200    Middle European Summer
                     MESZ    +0200    Middle European Summer
                     METDST  +0200    An alias for MEST used by HP-UX
                     SAST    +0200    South African Standard
                     SST     +0200    Swedish Summer       sst=South Sumatra    +0700
                     EEST    +0300    Eastern Europe Summer
                     BT      +0300    Baghdad, USSR Zone 2
                     MSK     +0300    Moscow
                     IT      +0330    Iran
                     ZP4     +0400    USSR Zone 3
                     MSD     +0300    Moscow Daylight
                     ZP5     +0500    USSR Zone 4
                     IST     +0530    Indian Standard
                     ZP6     +0600    USSR Zone 5
                     CCT     +0800    China Coast, USSR Zone 7
                     AWST    +0800    West Australian Standard
                     WST     +0800    West Australian Standard
                     PHT     +0800    Asia Manila
                     JST     +0900    Japan Standard, USSR Zone 8
                     ROK     +0900    Republic of Korea
                     CAST    +0930    Central Australian Standard
                     EAST    +1000    Eastern Australian Standard
                     GST     +1000    Guam Standard, USSR Zone 9  gst=Greenland Std
                     CADT    +1030    Central Australian Daylight
                     EADT    +1100    Eastern Australian Daylight
                     IDLE    +1200    International Date Line East
                     NZST    +1200    New Zealand Standard
                     NZT     +1200    New Zealand
                     NZDT    +1300    New Zealand Daylight

    -- DatePattern ($)
        The DatePattern as defined above.

    -- min_level ($)
        The minimum logging level this object will accept. See the
        Log::Dispatch documentation for more information. Required.

    -- max_level ($)
        The maximum logging level this obejct will accept. See the
        Log::Dispatch documentation for more information. This is not
        required. By default the maximum is the highest possible level
        (which means functionally that the object has no maximum).

    -- filename ($)
        The filename to be opened for writing. This is the base name.
        Rotated log files will be renamed filename.1 thru to filename."max".
        Where max is the paramater defined above.

    -- mode ($)
        The mode the file should be opened with. Valid options are 'write',
        '>', 'append', '>>', or the relevant constants from Fcntl. The
        default is 'write'.

    -- autoflush ($)
        Whether or not the file should be autoflushed. This defaults to
        true.

    -- callbacks( \& or [ \&, \&, ... ] )
        This parameter may be a single subroutine reference or an array
        reference of subroutine references. These callbacks will be called
        in the order they are given and passed a hash containing the
        following keys:

         ( message => $log_message, level => $log_level )

        The callbacks are expected to modify the message and then return a
        single scalar containing that modified message. These callbacks will
        be called when either the "log" or "log_to" methods are called and
        will only be applied to a given message once.

    -- DEBUG ($)
        Turn on lots of warning messages to STDERR about what this module is
        doing if set to 1. Really only useful to me.

    * log_message( message => $ )
        Sends a message to the appropriate output. Generally this shouldn't
        be called directly but should be called through the "log()" method
        (in Log::Dispatch::Output).

    * setDatePattern( $ or [ $, $, ... ] )
        Set a new suite of recurrances for file rotation. You can pass in a
        single string or a reference to an array of strings. Multiple
        recurrences can also be define within a single string by seperating
        them with a semi-colon (;)

        See the discussion above regarding the setDatePattern paramater for
        more details.

TODO
    compression, signal based rotates, proper test suite

    Could possibly use Logfile::Rotate as well/instead.

AUTHOR
    Mark Pfeiffer, <markpf at mlp-consulting dot com dot au> inspired by
    Dave Rolsky's, <autarch at urth dot org>, code :-)

    Kevin Goess <cpan at goess dot org> suggested multiple writers should be
    supported. He also conned me into doing the time based stuff. Thanks
    Kevin! :-)

    Thanks also to Dan Waldheim for helping with some of the locking issues
    in a forked environment.

    And thanks to Stephen Gordon for his more portable code on lockfile
    naming.

Copyright
    Copyright 2005-2006, Mark Pfeiffer

    This code may be copied only under the terms of the Artistic License
    which may be found in the Perl 5 source kit.

    Use 'perldoc perlartistic' to see the Artistic License.

    Complete documentation for Perl, including FAQ lists, should be found on
    this system using `man perl' or `perldoc perl'. If you have access to
    the Internet, point your browser at http://www.perl.org/, the Perl Home
    Page.