Dancer::Logger::Log4perl - Dancer adapter for Log::Log4perl

version 0.8.0

   # In your config.yml
   logger: log4perl
   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

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.

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.

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

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

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.

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
   log4perl:
      config_file: log4perl.conf

In your code:

   # somewhere...
   get '/please/warn' => sub {
      warning "ouch!"; # good ol' Dancer warning
      return ':-)';
   };

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, chances are that you'll perform initialisation by your own, so your configuration file will be bare bones:

   # config.yml
   logger: log4perl
   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 ';-)';
   };

Whatever the method you use to initialise the logger (but take care to initialis 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!

If you prefer to use Log::Log4perl::Tiny you can put the relevant options directly inside the configuration file:

   # config.yml
   logger: log4perl
   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 ';-)';
   };

As an alternative to the previous example, you can also limit the configuration file to a minimum:

   # config.yml
   logger: log4perl
   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 ';-)';
   };

Flavio Poletti <polettix@cpan.org>

Copyright (C) 2011 by Flavio Poletti polettix@cpan.org.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.