NAME

Log::Log4perl::CommandLine::Cookbook - Recipes for Log::Log4perl::CommandLine

DESCRIPTION

This cookbook has a series of example uses, including sample code, descriptions, and some command line examples with their output.

These always use the :easy mode from Log::Log4perl, since the purpose is to illustrate the use of Log::Log4perl::CommandLine, not Log::Log4perl. Go see it for more advanced usage.

SAMPLE MODULE

The scripts, modules and output can be found in the distribution's eg directory.

A sample module (SampleModule.pm) is used to illustrate the interaction with logging from a module:

package SampleModule;

use Log::Log4perl qw(:easy);

sub test
{
    TRACE "test trace message";
    DEBUG "test debug message";
    INFO  "test info  message";
    WARN  "test warn  message";
    ERROR "test error message";
    FATAL "test fatal message";
}

1;

RECIPES

sample1

sample1.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine qw(:all);

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

Use the :all option to enable all the standard options. By default it will print only messages with ERROR or FATAL, other messages are suppressed. The various command line options affect the output as shown.

Sample Runs:

% perl sample1.pl
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl -q

% perl sample1.pl -v
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl -d
[DEBUG] debug message
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl --quiet

% perl sample1.pl --fatal
[FATAL] fatal message

% perl sample1.pl --error
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl --warn
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl --info
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl --debug
[DEBUG] debug message
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample1.pl --trace
[TRACE] trace message
[DEBUG] debug message
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

sample2

sample2.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine qw(:all);

use SampleModule;

SampleModule::test();

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This script illustrates the interaction with modules.

Sample Runs:

% perl sample2.pl 
[ERROR] test error message
[FATAL] test fatal message
[ERROR] error message
[FATAL] fatal message

% perl sample2.pl -q

% perl sample2.pl -v
[INFO ] test info  message
[WARN ] test warn  message
[ERROR] test error message
[FATAL] test fatal message
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample2.pl -q SampleModule
[ERROR] error message
[FATAL] fatal message

% perl sample2.pl -q -v SampleModule
[INFO ] test info  message
[WARN ] test warn  message
[ERROR] test error message
[FATAL] test fatal message

% perl sample2.pl -q -d SampleModule
[DEBUG] test debug message
[INFO ] test info  message
[WARN ] test warn  message
[ERROR] test error message
[FATAL] test fatal message

% perl sample2.pl -v -d SampleModule
[DEBUG] test debug message
[INFO ] test info  message
[WARN ] test warn  message
[ERROR] test error message
[FATAL] test fatal message
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

sample3

sample3.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine ':all',
                               ':loginit' => { level => $INFO };

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This script overrides the default log level, setting it to INFO. It can still be overridden on the command line.

Sample Runs:

% perl sample3.pl 
[INFO ] info  message
[WARN ] warn  message
[ERROR] error message
[FATAL] fatal message

% perl sample3.pl -q

% perl sample3.pl --error
[ERROR] error message
[FATAL] fatal message

sample4

sample4.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine ':all',
                               ':loginit' => { layout => '%c %m%n' };

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This script overrides the default log layout. For more information on layouts, see Log::Log4perl::Layout::PatternLayout.

Sample Runs:

% perl sample4.pl
main error message
main fatal message

% perl sample4.pl -q

% perl sample4.pl -v
main info  message
main warn  message
main error message
main fatal message

sample5

sample5.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine qw(:all :logconfig log4perl.conf);

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This script specifies a log4perl style configuration file. If the file is present, it will be used, if it is absent, the defaults will be used.

Here is a sample configuration file:

log4perl.logger = WARN,  screen
log4perl.appender.screen=Log::Log4perl::Appender::Screen
log4perl.appender.screen.layout=Log::Log4perl::Layout::PatternLayout
log4perl.appender.screen.layout.ConversionPattern=%c %m%n

Log4perl configurations are extremely flexible, you can build complex logging schemes, including logging to files, databases, sending to another machine, fine tuning the specific messages you want to see, etc. For more information, see Log::Log4perl::Config and Log::Log4perl.

Sample Runs:

% perl sample5.pl 
main warn  message
main error message
main fatal message

% perl sample5.pl -q

% perl sample5.pl -v
main info  message
main warn  message
main error message
main fatal message

sample6

sample6.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine ':all',
':loginit' => q(
    log4perl.logger = WARN,  screen
    log4perl.appender.screen=Log::Log4perl::Appender::Screen
    log4perl.appender.screen.layout=Log::Log4perl::Layout::PatternLayout
    log4perl.appender.screen.layout.ConversionPattern=[%-5p] %c %m%n
);

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

You can also specify a string with a fancy log4perl configuration inline.

Sample Runs:

% perl sample6.pl 
[WARN ] main warn  message
[ERROR] main error message
[FATAL] main fatal message

% perl sample6.pl -v
[INFO ] main info  message
[WARN ] main warn  message
[ERROR] main error message
[FATAL] main fatal message

sample7

sample7.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine ':all',
':loginit' => q(
    log4perl.logger = WARN,  screen
    log4perl.appender.screen=Log::Log4perl::Appender::Screen
    log4perl.appender.screen.layout=Log::Log4perl::Layout::PatternLayout
    log4perl.appender.screen.layout.ConversionPattern=[%-5p] %c %m%n
);

use SampleModule;

SampleModule::test();

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This one is the same as sample6, but includes SampleModule. You can independendently turn up/down the logging on the main program (which gets inherited through the system), and the verbosity of any module in the system. (Actually any 'category' in the system, which by default means module, but you can do fancier fine tuning of categories by specifying them manually, see Log::Log4perl for more information.)

Sample Runs:

% perl sample7.pl 
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message
[WARN ] main warn  message
[ERROR] main error message
[FATAL] main fatal message

% perl sample7.pl -q

% perl sample7.pl -v
[INFO ] SampleModule test info  message
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message
[INFO ] main info  message
[WARN ] main warn  message
[ERROR] main error message
[FATAL] main fatal message

% perl sample7.pl -q -v SampleModule
[INFO ] SampleModule test info  message
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message

% perl sample7.pl -d -q SampleModule
[DEBUG] main debug message
[INFO ] main info  message
[WARN ] main warn  message
[ERROR] main error message
[FATAL] main fatal message

sample8

sample8.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine ':all',
                               ':loginit' => { layout => '[%-5p] %c %m%n' };

use SampleModule;
use SampleModule2;

SampleModule::test();
SampleModule2::test();

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

This script uses two modules (identical except for name), to illustrate the independent verbosity control.

Sample Runs:

% perl sample8.pl 
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message
[ERROR] SampleModule2 test error message
[FATAL] SampleModule2 test fatal message
[ERROR] main error message
[FATAL] main fatal message

% perl sample8.pl -d SampleModule
[DEBUG] SampleModule test debug message
[INFO ] SampleModule test info  message
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message
[ERROR] SampleModule2 test error message
[FATAL] SampleModule2 test fatal message
[ERROR] main error message
[FATAL] main fatal message

% perl sample8.pl -d SampleModule -q SampleModule2
[DEBUG] SampleModule test debug message
[INFO ] SampleModule test info  message
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message
[ERROR] main error message
[FATAL] main fatal message

% perl sample8.pl -q -d SampleModule
[DEBUG] SampleModule test debug message
[INFO ] SampleModule test info  message
[WARN ] SampleModule test warn  message
[ERROR] SampleModule test error message
[FATAL] SampleModule test fatal message

sample9

This script is identical to sample1, but the usages illustrates the --logfile command line option. You can specify a log filename on the command line and it will add a simple file appender (for more complex ones, make a real config file). You can optionally specify a pattern layout with the option.

Sample Runs:

% perl sample9.pl
[ERROR] error message
[FATAL] fatal message

% perl sample9.pl --logfile mylog.output
[ERROR] error message
[FATAL] fatal message

% cat mylog.output && rm mylog.output
2008/08/06 13:37:24 main error message
2008/08/06 13:37:24 main fatal message

% perl sample9.pl --logfile 'mylog.output|%d %m%n'
[ERROR] error message
[FATAL] fatal message

% cat mylog.output && rm mylog.output
2008/08/06 13:41:50 error message
2008/08/06 13:41:50 fatal message

sample10

This script is identical to sample1, but the usage illustrates the --logconfig command line option. You can even specify a more complex log4perl configuration file if one isn't specified in the program. If one is specified on the use line, the one specified on the command line will override it.

Sample Runs:

% perl sample10.pl 
[ERROR] error message
[FATAL] fatal message

% perl sample10.pl --logconfig log4perl.conf
main warn  message
main error message
main fatal message

sample11

sample11.pl:

use Log::Log4perl qw(:easy);
use Log::Log4perl::CommandLine qw(:all :noinit handlelogoptions);

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

handlelogoptions();

TRACE "trace message";
DEBUG "debug message";
INFO  "info  message";
WARN  "warn  message";
ERROR "error message";
FATAL "fatal message";

Log::Log4perl::init('log4perl.conf');

handlelogoptions();

TRACE "trace message 2";
DEBUG "debug message 2";
INFO  "info  message 2";
WARN  "warn  message 2";
ERROR "error message 2";
FATAL "fatal message 2";

This script shows how to use :noinit to disable auto log configuration and explicitly call handlelogoptions() after manually configuring Log4perl.

Sample Runs:

% perl sample11.pl
2008/08/13 22:33:50 fatal message
main warn  message 2
main error message 2
main fatal message 2

% perl sample11.pl -v
2008/08/13 22:33:52 info  message
2008/08/13 22:33:52 warn  message
2008/08/13 22:33:52 error message
2008/08/13 22:33:52 fatal message
main info  message 2
main warn  message 2
main error message 2
main fatal message 2

% perl sample11.pl -d
2008/08/13 22:33:55 debug message
2008/08/13 22:33:55 info  message
2008/08/13 22:33:55 warn  message
2008/08/13 22:33:55 error message
2008/08/13 22:33:55 fatal message
main debug message 2
main info  message 2
main warn  message 2
main error message 2
main fatal message 2

AUTHOR

Curt Tilmes <ctilmes@cpan.org>

COPYRIGHT AND LICENSE

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

To install Log::Log4perl::CommandLine, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Log::Log4perl::CommandLine

CPAN shell

perl -MCPAN -e shell
install Log::Log4perl::CommandLine

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SAMPLE MODULE

RECIPES

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions