Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/polettix/dancer-logger-log4perl

Dancer adapter for Log::Log4perl
https://github.com/polettix/dancer-logger-log4perl

Last synced: about 1 month ago
JSON representation

Dancer adapter for Log::Log4perl

Awesome Lists containing this project

README 

        
SYNOPSIS

    In your config.yml



       logger: log4perl

       log: core

       log4perl:

          config_file: log4perl.conf



    In your log4perl.conf



       log4perl.rootLogger              = DEBUG, LOG1

       log4perl.appender.LOG1           = Log::Log4perl::Appender::File

       log4perl.appender.LOG1.filename  = /var/log/mylog.log

       log4perl.appender.LOG1.mode      = append

       log4perl.appender.LOG1.layout    = Log::Log4perl::Layout::PatternLayout

       log4perl.appender.LOG1.layout.ConversionPattern = %d %p %m %n



DESCRIPTION

    This class is an interface between Dancer's logging engine abstraction

    layer and the Log::Log4perl library. In order to use it, you have to set

    the `logger' engine to `log4perl'.



    You can use either Log::Log4perl or Log::Log4perl::Tiny. If you want to

    use the latter, just specify the `tiny' option in the specific

    configuration.



    You can decide to let the module perform the initialisation of the

    logging system, or you can do it by yourself. In the latter case, you

    can pass the `no_init' parameter, which instructs the module not to

    perform the initialisation.



    After initialisation, you can decide to use Dancer's functions or the

    ones provided by either Log::Log4perl or Log::Log4perl::Tiny, e.g. the

    stealth loggers in case of a simplified interface.



    Note that Dancer's `log' and `logger_format' options are still honored,

    which means you need to be aware of the following:



    `logger_format' is still processed and becomes `%m' in Log4perl's format

    placeholders. This allows you to pass Dancer placeholders that aren't

    available as Log4perl placeholders.



    Dancer's `core' level messages are passed to Log4perl as level `trace'

    but will not be passed unless Dancer's `log' config is `core'.



    `log' should be set a lower priority than the lowest priority as set in

    your Log4perl configuration. If it isn't, Dancer::Logger::Abstract will

    not pass the message to Log4perl.



CONFIGURATION

    The configuration capabilities vary depending on the underlying library

    you have, even though the following configurations are common:



    no_init

        skip the initialisation phase of the logging module, assuming that

        it is performed elsewhere.



    tiny

        allows you to decide whether Log::Log4perl (when set to a false

        value) or Log::Log4perl::Tiny (when set to a true value) should be

        used.



  Log::Log4perl

    If you're using standard Log::Log4perl, then you have two alternatives

    to pass a configuration:



    config_file

        via a configuration file, using the `config_file' option:



           logger: log4perl

           log4perl:

              config_file: log4perl.conf



    config

        via a straight configuration text, using the `config' option:



           logger: log4perl

           log4perl:

              config: |

                 log4perl.rootLogger              = DEBUG, LOG1

                 log4perl.appender.LOG1           = Log::Log4perl::Appender::File

                 log4perl.appender.LOG1.filename  = /var/log/mylog.log

                 log4perl.appender.LOG1.mode      = append

                 log4perl.appender.LOG1.layout    = Log::Log4perl::Layout::PatternLayout

                 log4perl.appender.LOG1.layout.ConversionPattern = %d %p %m %n



  Log::Log4perl::Tiny

    If all you have is Log::Log4perl::Tiny, you can set some parameters:



    level

        the log `level'



           logger: log4perl

           log4perl:

              tiny: 1

              level: INFO



    format

        the log `format' (aliased to `layout' as well)



           logger: log4perl

           log4perl:

              tiny: 1

              format: [%p] %m%n



EXAMPLES

    All examples below assume that you have your Log::Log4perl

    initialisation stuff inside a file called log4perl.conf, e.g. something

    along the following lines:



       log4perl.logger = INFO, Screen

       log4perl.appender.Screen = Log::Log4perl::Appender::Screen

       log4perl.appender.Screen.stderr = 1

       log4perl.appender.Screen.stdout = 0

       log4perl.appender.Screen.layout = Log::Log4perl::Layout::PatternLayout

       log4perl.appender.Screen.layout.ConversionPattern = [%d] [%-5p] %m%n



    The above initialisation text is actually what you get by default.



  Log::Log4perl, Automatic Initialisation, Dancer Logging Interface

    In this case you'll probably want to let the module handle the

    initialisation and forget about Log::Log4perl in your code. In the

    Dancer configuration file:



       # config.yml

       logger: log4perl

       log: info

       log4perl:

          config_file: log4perl.conf



    In your code:



       # somewhere...

       get '/please/warn' => sub {

          warning "ouch!"; # good ol' Dancer warning

          return ':-)';

       };



  Log::Log4perl, Manual Initialisation, Log::Log4perl Stealth Interface

    If you want to use Log::Log4perl's stealth interface, chances are you

    also want to avoid a full configuration file and rely upon

    `easy_init()'. In this case, you will probably want to perform the

    initialisation by your own, so your configuration file will be bare

    bones:



       # config.yml

       logger: log4perl

       log: info

       log4perl:

          no_init: 1



    and your code will contain all the meat:



       use Log::Log4perl qw( :easy );

       Log::Log4perl->easy_init($INFO);

       get '/please/warn' => sub {

          WARN 'ouch!'; # Log::Log4perl way of warning

          return ';-)';

       };



  Log::Log4perl, Whatever Initialisation, Whatever Interface

    Whatever the method you use to initialise the logger (but take care to

    initialise it once and only once, see Log::Log4perl), you can always use

    both Dancer and Log::Log4perl functions:



       use Log::Log4perl qw( :easy );

       get '/please/warn/2/times' => sub {

          warning 'ouch!'; # Dancer style

          WARN    'OUCH!'; # Log::Log4perl style

          return ':-D';

       };



    If you don't like either functional interface, and prefer to stick to

    Log::Log4perl's object-oriented interface to avoid collisions in

    function names:



       use Log::Log4perl ();

       get '/please/warn/2/times' => sub {

          get_logger()->warn('ouch!'); # Log::Log4perl, OO way

          return 'B-)';

       };



    Well, you get the idea... just peruse Log::Log4perl documentation for

    more!



  Log::Log4perl::Tiny, Automatic Initialisation, Any Interface

    If you prefer to use Log::Log4perl::Tiny you can put the relevant

    options directly inside the configuration file:



       # config.yml

       logger: log4perl

       log: debug

       log4perl:

          tiny: 1

          level: DEBUG

          format:  [%p] %m%n



    At this point, you can import the relevant methods in your code and use

    them as you would with Log::Log4perl:



       use Log::Log4perl::Tiny qw( :easy );

       get '/please/warn' => sub {

          WARN 'ouch!'; # Log::Log4perl(::Tiny) way of warning

          # you can also use Dancer's warning here...

          warning 'OUCH!';

          return ';-)';

       };



  Log::Log4perl::Tiny, Any Initialisation, Any Interface

    As an alternative to the previous example, you can also limit the

    configuration file to a minimum:



       # config.yml

       logger: log4perl

       log: info

       log4perl:

          tiny: 1



    and initialise the logging library inside the code:



       use Log::Log4perl::Tiny qw( :easy );

       Log::Log4perl->easy_init($INFO);

       get '/please/warn' => sub {

          WARN 'ouch!'; # Log::Log4perl(::Tiny) way of warning

          # you can also use Dancer's warning here...

          warning 'OUCH!';

          return ';-)';

       };



SUPPORT

    If you find a bug, have a comment or (constructive) criticism you have

    different options:



    -   just write to the AUTHOR



    -   open a bug request on the relevant RT queue at

        https://rt.cpan.org/Public/Dist/Display.html?Name=Dancer-Logger-Log4

        perl



    -   open an issue or propose a patch on GitHub at

        https://github.com/polettix/Dancer-Logger-Log4perl