Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Dispatch::Config(User Contributed Perl DocumentatLog::Dispatch::Config(3)

NAME
       Log::Dispatch::Config - Log4j for Perl

SYNOPSIS
	 use Log::Dispatch::Config;
	 Log::Dispatch::Config->configure('/path/to/log.conf');

	 my $dispatcher	= Log::Dispatch::Config->instance;
	 $dispatcher->debug('this is debug message');
	 $dispatcher->emergency('something *bad* happened!');

	 # automatic reloading conf file, when modified
	 Log::Dispatch::Config->configure_and_watch('/path/to/log.conf');

	 # or if you write your	own config parser:
	 use Log::Dispatch::Configurator::XMLSimple;

	 my $config = Log::Dispatch::Configurator::XMLSimple->new('log.xml');
	 Log::Dispatch::Config->configure($config);

DESCRIPTION
       Log::Dispatch::Config is	a subclass of Log::Dispatch and	provides a way
       to configure Log::Dispatch object with configulation file (default, in
       AppConfig format). I mean, this is log4j	for Perl, not with all API
       compatibility though.

METHOD
       This module has a class method "configure" which	parses config file for
       later creation of the Log::Dispatch::Config singleton instance.
       (Actual construction of the object is done in the first "instance"
       call).

       So, what	you should do is call "configure" method once in somewhere
       (like "startup.pl" in mod_perl),	then you can get configured dispatcher
       instance	via "Log::Dispatch::Config->instance".

CONFIGURATION
       Here is an example of the config	file:

	 dispatchers = file screen

	 file.class = Log::Dispatch::File
	 file.min_level	= debug
	 file.filename = /path/to/log
	 file.mode = append
	 file.format = [%d] [%p] %m at %F line %L%n

	 screen.class =	Log::Dispatch::Screen
	 screen.min_level = info
	 screen.stderr = 1
	 screen.format = %m

       In this example,	config file is written in AppConfig format. See
       Log::Dispatch::Configurator::AppConfig for details.

       See "PLUGGABLE CONFIGURATOR" for	other config parsing scheme.

   GLOBAL PARAMETERS
       dispatchers
	     dispatchers = file	screen

	   "dispatchers" defines logger	names, which will be splitted by
	   spaces.  If this parameter is unset,	no logging is done.

       format
	     format = [%d] [%p]	%m at %F line %L%n

	   "format" defines log	format.	Possible conversions format are

	     %d	   datetime string (ctime(3))
	     %p	   priority (debug, info, warning ...)
	     %m	   message string
	     %F	   filename
	     %L	   line	number
	     %P	   package
	     %n	   newline (\n)
	     %%	   % itself

	   Note	that datetime (%d) format is configurable by passing
	   "strftime" fmt in braket after %d. (I know it looks quite messy,
	   but its compatible with Java	Log4j ;)

	     format = [%d{%Y%m%d}] %m  # datetime is now strftime "%Y%m%d"

	   If you have Time::Piece, this module	uses its "strftime"
	   implementation, otherwise POSIX.

	   "format" defined here would apply to	all the	log messages to
	   dispatchers.	This parameter is optional.

	   See "CALLER STACK" for details about	package, line number and
	   filename.

   PARAMETERS FOR EACH DISPATCHER
       Parameters for each dispatcher should be	prefixed with "name.", where
       "name" is the name of each one, defined in global "dispatchers"
       parameter.

       You can also use	".ini" style grouping like:

	 [foo]
	 class = Log::Dispatch::File
	 min_level = debug

       See Log::Dispatch::Configurator::AppConfig for details.

       class
	     screen.class = Log::Dispatch::Screen

	   "class" defines class name of Log::Dispatch subclasses. This
	   parameter is	essential.

       format
	     screen.format = --	%m --

	   "format" defines log	format which would be applied only to the
	   dispatcher. Note that if you	define global "format" also, %m	is
	   double formated (first global one, next each	dispatcher one). This
	   parameter is	optional.

       (others)
	     screen.min_level =	info
	     screen.stderr = 1

	   Other parameters would be passed to the each	dispatcher
	   construction. See Log::Dispatch::* manpage for the details.

SINGLETON
       Declared	"instance" method would	make "Log::Dispatch::Config" class
       singleton, so multiple calls of "instance" will all result in returning
       same object.

	 my $one = Log::Dispatch::Config->instance;
	 my $two = Log::Dispatch::Config->instance; # same as $one

       See GoF Design Pattern book for Singleton Pattern.

       But in practice,	in persistent environment like mod_perl, lifetime of
       Singleton instance becomes sometimes messy. If you want to reload
       singleton object	manually, call "reload"	method.

	 Log::Dispatch::Config->reload;

       And, if you want	to reload object on the	fly, as	you edit "log.conf" or
       something like that, what you should do is to call
       "configure_and_watch" method on Log::Dispatch::Config instead of
       "configure". Then "instance" call will check mtime of configuration
       file, and compares it with instanciation	time of	singleton object. If
       config file is newer than last instanciation, it	will automatically
       reload object.

NAMESPACE COLLISION
       If you use Log::Dispatch::Config	in multiple projects on	the same perl
       interpreter (like mod_perl), namespace collision	would be a problem.
       Bizzare thing will happen when you call
       "Log::Dispatch::Config->configure" multiple times with differenct
       argument.

       In such cases, what you should do is to define your own logger class.

	 package My::Logger;
	 use Log::Dispatch::Config;
	 use base qw(Log::Dispatch::Config);

       Or make wrapper for it. See POE::Component::Logger implementation by
       Matt Sergeant.

PLUGGABLE CONFIGURATOR
       If you pass filename to "configure" method call,	this module handles
       the config file with AppConfig. You can change config parsing scheme by
       passing another pluggable configurator object.

       Here is a way to	declare	new configurator class.	The example below is
       hardwired version equivalent to the one above in	"CONFIGURATION".

       o   Inherit from	Log::Dispatch::Configurator.

	     package Log::Dispatch::Configurator::Hardwired;
	     use base qw(Log::Dispatch::Configurator);

	   Declare your	own "new" constructor. Stub "new" method is defined in
	   Configurator	base class, but	you want to put	parsing	method in your
	   own constructor. In this example, we	just bless reference. Note
	   that	your object should be blessed hash.

	     sub new { bless {}, shift }

       o   Implement two required object methods "get_attrs_global" and
	   "get_attrs".

	   "get_attrs_global" should return hash reference of global
	   parameters.	"dispatchers" should be	an array reference of names of
	   dispatchers.

	     sub get_attrs_global {
		 my $self = shift;
		 return	{
		     format => undef,
		     dispatchers => [ qw(file screen) ],
		 };
	     }

	   "get_attrs" accepts name of a dispatcher and	should return hash
	   reference of	parameters associated with the dispatcher.

	     sub get_attrs {
		 my($self, $name) = @_;
		 if ($name eq 'file') {
		     return {
			 class	   => 'Log::Dispatch::File',
			 min_level => 'debug',
			 filename  => '/path/to/log',
			 mode	   => 'append',
			 format	 => '[%d] [%p] %m at %F	line %L%n',
		     };
		 }
		 elsif ($name eq 'screen') {
		     return {
			 class	   => 'Log::Dispatch::Screen',
			 min_level => 'info',
			 stderr	   => 1,
			 format	 => '%m',
		     };
		 }
		 else {
		     die "invalid dispatcher name: $name";
		 }
	     }

       o   Implement optional "needs_reload" and "reload" methods.
	   "needs_reload" should return	boolean	value if the object is stale
	   and needs reloading itself. This method will	be triggered when you
	   configure logging object with "configure_and_watch" method.

	   Stub	config file mtime based	"needs_reload" method is declared in
	   Log::Dispatch::Configurator,	so if your config class	is based on
	   filesystem files, you do not	need to	reimplement this.

	   If you do not need singleton-ness at	all, always return true.

	     sub needs_reload {	1 }

	   "reload" method should redo parsing of the config file.
	   Configurator	base class has a stub null "reload" method, so you
	   should better override it.

	   See Log::Dispatch::Configurator::AppConfig source code for details.

       o   That's all. Now you can plug	your own configurator (Hardwired) into
	   Log::Dispatch::Config. What you should do is	to pass	configurator
	   object to "configure" method	call instead of	config file name.

	     use Log::Dispatch::Config;
	     use Log::Dispatch::Configurator::Hardwired;

	     my	$config	= Log::Dispatch::Configurator::Hardwired->new;
	     Log::Dispatch::Config->configure($config);

CALLER STACK
       When you	call logging method from your subroutines / methods, caller
       stack would increase and	thus you can't see where the log really	comes
       from.

	 package Logger;
	 my $Logger = Log::Dispatch::Config->instance;

	 sub logit {
	     my($class,	$level,	$msg) =	@_;
	     $Logger->$level($msg);
	 }

	 package main;
	 Logger->logit('debug',	'foobar');

       You can adjust package variable $Log::Dispatch::Config::CallerDepth to
       increase	the caller stack depth.	The default value is 0.

	 sub logit {
	     my($class,	$level,	$msg) =	@_;
	     local $Log::Dispatch::Config::CallerDepth = 1;
	     $Logger->$level($msg);
	 }

       Note that your log caller's namespace should not	match against
       "/^Log::Dispatch/", which makes this module confusing.

AUTHOR
       Tatsuhiko Miyagawa <miyagawa@bulknews.net> with much help from Matt
       Sergeant	<matt@sergeant.org>.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

SEE ALSO
       Log::Dispatch::Configurator::AppConfig, Log::Dispatch, AppConfig,
       POE::Component::Logger

perl v5.32.0			  2011-04-14	      Log::Dispatch::Config(3)

NAME | SYNOPSIS | DESCRIPTION | METHOD | CONFIGURATION | SINGLETON | NAMESPACE COLLISION | PLUGGABLE CONFIGURATOR | CALLER STACK | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatch::Config&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help