new(%p)

This method takes a hash of parameters. The following options are valid:

• name ($)

  The name of the object (not the dirname!). Required.

• min_level ($)

  The minimum logging level this object will accept. See the Log::Dispatch documentation on Log Levels for more information. Required.

• max_level ($)

  The maximum logging level this obejct will accept. See the Log::Dispatch documentation on Log Levels 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).

• dirname ($)

  The directory to write to.

• permissions ($)

  If the directory does not already exist, the permissions that it should be created with. Optional. The argument passed must be a valid octal value, such as 0700 or the constants available from Fcntl, like S_IRUSR|S_IWUSR|S_IXUSR.

  See "chmod" in perlfunc for more on potential traps when passing octal values around. Most importantly, remember that if you pass a string that looks like an octal value, like this:

   my $mode = '0644';
      

  Then the resulting directory will end up with permissions like this:

   --w----r-T
      

  which is probably not what you want.

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

• filename_pattern ($)

  Names to give to each file, expressed in pattern a la strftime()'s. Optional. Default is '%Y-%m-%d-%H%M%S.pid-%{pid}.%{ext}'. Time is expressed in local time.

  If file of the same name already exists, a suffix ".1", ".2", and so on will be appended.

  Available pattern:

• filename_sub (\&)

  A more generic mechanism for filename_pattern. If filename_sub is given, filename_pattern will be ignored. The code will be called with the same arguments as log_message() and is expected to return a filename. Will die if code returns undef.

• max_size ($)

  Maximum total size of files, in bytes. After the size is surpassed, oldest files (based on ctime) will be deleted. Optional. Default is undefined, which means unlimited.

• max_files ($)

  Maximum number of files. After this number is surpassed, oldest files (based on ctime) will be deleted. Optional. Default is undefined, which means unlimited.

• max_age ($)

  Maximum age of files (based on ctime), in seconds. After the age is surpassed, files older than this age will be deleted. Optional. Default is undefined, which means unlimited.

• rotate_probability ($)

  A number between 0 and 1 which specifies the probability that rotate() will be called after each log_message(). This is a balance between performance and rotate size accuracy. 1 means always rotate, 0 means never rotate. Optional. Default is 0.25.

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