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

FreeBSD Manual Pages

  
 
  

home | help
Config(3)	      User Contributed Perl Documentation	     Config(3)

NAME
       Log::Log4perl::Config - Log4perl	configuration file syntax

DESCRIPTION
       In "Log::Log4perl", configuration files are used	to describe how	the
       system's	loggers	ought to behave.

       The format is the same as the one as used for "log4j", just with	a few
       perl-specific extensions, like enabling the "Bar::Twix" syntax instead
       of insisting on the Java-specific "Bar.Twix".

       Comment lines and blank lines (all whitespace or	empty) are ignored.

       Comment lines may start with arbitrary whitespace followed by one of:

       # - Common comment delimiter
       ! - Java	.properties file comment delimiter accepted by log4j
       ; - Common .ini file comment delimiter

       Comments	at the end of a	line are not supported.	So if you write

	   log4perl.appender.A1.filename=error.log #in current dir

       you will	find your messages in a	file called "error.log #in current
       dir".

       Also, blanks between syntactical	entities are ignored, it doesn't
       matter if you write

	   log4perl.logger.Bar.Twix=WARN,Screen

       or

	   log4perl.logger.Bar.Twix = WARN, Screen

       "Log::Log4perl" will strip the blanks while parsing your	input.

       Assignments need	to be on a single line.	However, you can break the
       line if you want	to by using a continuation character at	the end	of the
       line. Instead of	writing

	   log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout

       you can break the line at any point by putting a	backslash at the very
       (!)  end	of the line to be continued:

	   log4perl.appender.A1.layout=\
	       Log::Log4perl::Layout::SimpleLayout

       Watch out for trailing blanks after the backslash, which	would prevent
       the line	from being properly concatenated.

   Loggers
       Loggers are addressed by	category:

	   log4perl.logger.Bar.Twix	 = WARN, Screen

       This sets all loggers under the "Bar::Twix" hierarchy on	priority
       "WARN" and attaches a later-to-be-defined "Screen" appender to them.
       Settings	for the	root appender (which doesn't have a name) can be
       accomplished by simply omitting the name:

	   log4perl.logger = FATAL, Database, Mailer

       This sets the root appender's level to "FATAL" and also attaches	the
       later-to-be-defined appenders "Database"	and "Mailer" to	it.
       Alternatively, the root logger can be addressed as "rootLogger":

	   log4perl.rootLogger = FATAL,	Database, Mailer

       The additivity flag of a	logger is set or cleared via the "additivity"
       keyword:

	   log4perl.additivity.Bar.Twix	= 0|1

       (Note the reversed order	of keyword and logger name, resulting from the
       dilemma that a logger name could	end in ".additivity" according to the
       log4j documentation).

   Appenders and Layouts
       Appender	names used in Log4perl configuration file lines	need to	be
       resolved	later on, in order to define the appender's properties and its
       layout. To specify properties of	an appender, just use the "appender"
       keyword after the "log4perl" intro and the appender's name:

	       # The Bar::Twix logger and its appender
	   log4perl.logger.Bar.Twix = DEBUG, A1
	   log4perl.appender.A1=Log::Log4perl::Appender::File
	   log4perl.appender.A1.filename=test.log
	   log4perl.appender.A1.mode=append
	   log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout

       This sets a priority of "DEBUG" for loggers in the "Bar::Twix"
       hierarchy and assigns the "A1" appender to it, which is later on
       resolved	to be an appender of type "Log::Log4perl::Appender::File",
       simply appending	to a log file. According to the
       "Log::Log4perl::Appender::File" manpage,	the "filename" parameter
       specifies the name of the log file and the "mode" parameter can be set
       to "append" or "write" (the former will append to the logfile if	one
       with the	specified name already exists while the	latter would clobber
       and overwrite it).

       The order of the	entries	in the configuration file is not important,
       "Log::Log4perl" will read in the	entire file first and try to make
       sense of	the lines after	it knows the entire context.

       You can very well define	all loggers first and then their appenders
       (you could even define your appenders first and then your loggers, but
       let's not go there):

	   log4perl.logger.Bar.Twix = DEBUG, A1
	   log4perl.logger.Bar.Snickers	= FATAL, A2

	   log4perl.appender.A1=Log::Log4perl::Appender::File
	   log4perl.appender.A1.filename=test.log
	   log4perl.appender.A1.mode=append
	   log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout

	   log4perl.appender.A2=Log::Log4perl::Appender::Screen
	   log4perl.appender.A2.stderr=0
	   log4perl.appender.A2.layout=Log::Log4perl::Layout::PatternLayout
	   log4perl.appender.A2.layout.ConversionPattern = %d %m %n

       Note that you have to specify the full path to the layout class and
       that "ConversionPattern"	is the keyword to specify the printf-style
       formatting instructions.

Configuration File Cookbook
       Here's some examples of often-used Log4perl configuration files:

   Append to STDERR
	   log4perl.category.Bar.Twix	   = WARN, Screen
	   log4perl.appender.Screen	   = Log::Log4perl::Appender::Screen
	   log4perl.appender.Screen.layout = \
	       Log::Log4perl::Layout::PatternLayout
	   log4perl.appender.Screen.layout.ConversionPattern = %d %m %n

   Append to STDOUT
	   log4perl.category.Bar.Twix	   = WARN, Screen
	   log4perl.appender.Screen	   = Log::Log4perl::Appender::Screen
	   log4perl.appender.Screen.stderr = 0
	   log4perl.appender.Screen.layout = \
	       Log::Log4perl::Layout::PatternLayout
	   log4perl.appender.Screen.layout.ConversionPattern = %d %m %n

   Append to a log file
	   log4perl.logger.Bar.Twix = DEBUG, A1
	   log4perl.appender.A1=Log::Log4perl::Appender::File
	   log4perl.appender.A1.filename=test.log
	   log4perl.appender.A1.mode=append
	   log4perl.appender.A1.layout = \
	       Log::Log4perl::Layout::PatternLayout
	   log4perl.appender.A1.layout.ConversionPattern = %d %m %n

       Note that you could even	leave out

	   log4perl.appender.A1.mode=append

       and still have the logger append	to the logfile by default, although
       the "Log::Log4perl::Appender::File" module does exactly the opposite.
       This is due to some nasty trickery "Log::Log4perl" performs behind the
       scenes to make sure that	beginner's CGI applications don't clobber the
       log file	every time they're called.

   Write a log file from scratch
       If you loathe the Log::Log4perl's append-by-default strategy, you can
       certainly override it:

	   log4perl.logger.Bar.Twix = DEBUG, A1
	   log4perl.appender.A1=Log::Log4perl::Appender::File
	   log4perl.appender.A1.filename=test.log
	   log4perl.appender.A1.mode=write
	   log4perl.appender.A1.layout=Log::Log4perl::Layout::SimpleLayout

       "write" is the "mode" that has "Log::Log4perl::Appender::File"
       explicitly clobber the log file if it exists.

   Configuration files encoded in utf-8
       If your configuration file is encoded in	utf-8 (which matters if	you
       e.g. specify utf8-encoded appender filenames in it), then you need to
       tell Log4perl before running init():

	   use Log::Log4perl::Config;
	   Log::Log4perl::Config->utf( 1 );

	   Log::Log4perl->init(	... );

       This makes sure Log4perl	interprets utf8-encoded	config files
       correctly.  This	setting	might become the default at some point.

SEE ALSO
       Log::Log4perl::Config::PropertyConfigurator

       Log::Log4perl::Config::DOMConfigurator

       Log::Log4perl::Config::LDAPConfigurator (coming soon!)

LICENSE
       Copyright 2002-2013 by Mike Schilli <m@perlmeister.com> and Kevin Goess
       <cpan@goess.org>.

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

AUTHOR
       Please contribute patches to the	project	on Github:

	   http://github.com/mschilli/log4perl

       Send bug	reports	or requests for	enhancements to	the authors via	our

       MAILING LIST (questions,	bug reports, suggestions/patches):
       log4perl-devel@lists.sourceforge.net

       Authors (please contact them via	the list above,	not directly): Mike
       Schilli <m@perlmeister.com>, Kevin Goess	<cpan@goess.org>

       Contributors (in	alphabetical order): Ateeq Altaf, Cory Bennett,	Jens
       Berthold, Jeremy	Bopp, Hutton Davidson, Chris R.	Donnelly, Matisse
       Enzer, Hugh Esco, Anthony Foiani, James FitzGibbon, Carl	Franks,	Dennis
       Gregorovic, Andy	Grundman, Paul Harrington, Alexander Hartmaier	David
       Hull, Robert Jacobson, Jason Kohles, Jeff Macdonald, Markus Peter,
       Brett Rann, Peter Rabbitson, Erik Selberg, Aaron	Straup Cope, Lars
       Thegler,	David Viner, Mac Yang.

perl v5.32.0			  2020-07-22			     Config(3)

NAME | DESCRIPTION | Configuration File Cookbook | SEE ALSO | LICENSE | AUTHOR

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

home | help