NAME

MojoX::Log::Rotate - Makes mojolicious log file rotation easy

VERSION

version 1.222670

SYNOPSIS

  use MojoX::Log::Rotate;
  my $log = MojoX::Log::Rotate->new( path => 'test.log', frequency => 3600 );
  $app->log($log); #replace the application logger

  # implement a custom rotation behaviour
  my $log = MojoX::Log::Rotate->new( path => 'test.log', how => \&how_to, when => \&when_to);

  sub when_to ($log) {
    # rotate log every 1Mb
    if($log->handle->tell > 1_000_000) {
      return {
        size => $log->handle->tell
      }
    }
    return 0;
  }

  sub how_to ($log, $when_res) {
    # implement your custom log rotation here, or just let's use the default callback
    # you don't even need to specify "how" parameter in the "new"> constructor.
    $log->default_rotation_cb($when_res);
  }

DESCRIPTION

MojoX::Log::Rotate is a simple extension to Mojo::Log that make file log rotation easy. The default rotation handlers rotate log file based on a "frequency" parameter. It does not create empty rotated file.

NAME

MojoX::Log::Rotate - Easy log rotation for Mojolicious

EVENTS

MojoX::Log::Rotate inherites all events from Mojo::Log and can emit the following one.

rotate

  $log->on(rotate => sub ($log, $params) {
    $log->info("log file $params->{how}{rotated_file} created");
  });

ATTRIBUTES

MojoX::Log::Rotate implements the following attributes.

need_rotate_cb

  my $cb = $log->need_rotate_cb;
  $log->need_rotate_cb(sub ($log){ ... });

A callback called on message event, if it returns a true value the "rotate_cb" will be called with the return value. It's role is provide the rules to trigger a log rotation.

rotate_cb

  my $cb = $log->rotate_cb;
  $log->rotate_cb(sub ($log, $need_rotate_result){ ... });

It's role is to provide the log rotation mechanism. It receives at second argument the value returned by "need_rotate_cb".

last_rotate

  my $last = $log->last_rotate;
  $log->last_rotate( time );

With the default behaviour it represent the last time a rotation was done.

frequency

  my $frequency = $log->frequency;
  #set log rotation frequency to 1 hour
  $log->frequency(3600); 

The frequency used in the default behaviour to rotate log, exprimed in seconds.

METHODS

MojoX::Log::Rotate inherits all methods from Mojo::Log and implements the following new one.

new

  my $log = MojoX::Log::Rotate->new;
  my $log = MojoX::Log::Rotate->new(path => 'app.log');

  my $log = MojoX::Log::Rotate->new(frequency => 3600);

  my $log = MojoX::Log::Rotate->new(when => sub($log){...}, how => sub($log,$r){...});

The constructor inherits from Mojo::Log constructor and accepts the following additional parameters.

when

  Specify the L</"need_rotate_cb"> attribute callback.

how

  Specify the L</"rotate_cb"> attribute callback.

frequency

  Set the L</"frequency"> attribute.

threaded

  Initialize a main thread to centralize mesage and patch L<Mojo::Log/"append"> to redirect
messages into a L<Threaded::Queue> object.

on_rotate

  Allow to register the C<rotate> event just before create the thread that will process messages.

stop

  Stop the internal queue and call L<threads/"join"> the main thread.

DEFAULT BEHAVIOUR

The default behaviour is to rotate the log file based on the node creation time attribute (stat() 10th returned value) of the filename returned by "path" in Mojo::Log. It append the suffix pattern _YYYYMMDD_hhmmss just before the extension.

LIMITATION

Does not works with call to "append" in Mojo::Log method or any direct access to the underlying file handle. In threaded mode you cannot register additonal message to the logger, that must be done just before cloning the logger objet in the thread that will process messages.

SEE ALSO

Mojo::Log, Mojolicious, Mojolicious::Guides, https://mojolicious.org.

AUTHOR

Nicolas Georges xlat@cpan.org ( see fork https://github.com/xlat/mojox-log-rotate)

COPYRIGHT

Copyright 2022, Nicolas Georges.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

DISCLAIMER OF WARRANTY

Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the software "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.

AUTHOR

Nicolas Georges <xlat@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2022 by Nicolas Georges.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm MojoX::Log::Rotate

perl -MCPAN -e shell
install MojoX::Log::Rotate