NAME

Log::Log4perl::Layout::PatternLayout - Pattern Layout

SYNOPSIS

use Log::Log4perl::Layout::PatternLayout;

my $layout = Log::Log4perl::Layout::PatternLayout->new(
                                                 "%d (%F:%L)> %m");

DESCRIPTION

Creates a pattern layout according to http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html.

The new() method creates a new PatternLayout, specifying its log format. The format string can contain a number of placeholders which will be replaced by the logging engine when it's time to log the message:

%c Category of the logging event.
%C Fully qualified package (or class) name of the caller
%d Current date in yyyy/mm/dd hh:mm:ss format
%F File where the logging event occurred
%H Hostname
%l Fully qualified name of the calling method followed by the
   callers source the file name and line number between 
   parentheses.
%L Line number within the file where the log statement was issued
%m The message to be logged
%M Method or function where the logging request was issued
%n Newline (OS-independent)
%p Priority of the logging event
%P pid of the current process
%r Number of milliseconds elapsed from program start to logging 
   event
%% A literal percent (%) sign

Quantify placeholders

All placeholders can be extended with formatting instructions, just like in printf:

%20c   Reserve 20 chars for the category, left-justify and fill
       with blanks if it is shorter
%-20c  Same as %20c, but right-justify and fill the left side 
       with blanks
%09r   Zero-pad the number of milliseconds to 9 digits
%.8c   Specify the maximum field with and have the formatter
       cut off the rest of the value

Fine-tuning with curlies

Some placeholders have special functions defined if you add curlies with content after them:

%c{1}  Just show the right-most category compontent, useful in large
       class hierarchies (Foo::Baz::Bar -> Bar)
%c{2}  Just show the two right most category components
       (Foo::Baz::Bar -> Baz::Bar)

%f     Display source file including full path
%f{1}  Just display filename
%f{2}  Display filename and last path component (dir/test.log)
%f{3}  Display filename and last two path components (d1/d2/test.log)

In this way, you're able to shrink the displayed category or limit file/path components to save space in your logs.

Fine-tune the date

If you're not happy with the default %d format for the date which looks like

YYYY/MM/DD HH:mm::ss

you're free to fine-tune it in order to display only certain characteristics of a date, according to the SimpleDateFormat in the Java World (http://java.sun.com/j2se/1.3/docs/api/java/text/SimpleDateFormat.html):

%d{HH:mm}     "23:45" -- Just display hours and minutes
%d{yy, EEEE}  "02, Monday" -- Just display two-digit year 
                              and spelled-out weekday
Here's the symbols and their meaning, according to the SimpleDateFormat
specification:

Symbol   Meaning                 Presentation     Example
------   -------                 ------------     -------
G        era designator          (Text)           AD
y        year                    (Number)         1996 
M        month in year           (Text & Number)  July & 07
d        day in month            (Number)         10
h        hour in am/pm (1-12)    (Number)         12
H        hour in day (0-23)      (Number)         0
m        minute in hour          (Number)         30
s        second in minute        (Number)         55
E        day in week             (Text)           Tuesday
D        day in year             (Number)         189
a        am/pm marker            (Text)           PM

(Text): 4 or more pattern letters--use full form, < 4--use short or 
        abbreviated form if one exists. 

(Number): the minimum number of digits. Shorter numbers are 
          zero-padded to this amount. Year is handled 
          specially; that is, if the count of 'y' is 2, the 
          Year will be truncated to 2 digits. 

(Text & Number): 3 or over, use text, otherwise use number. 

There's also a bunch of pre-defined formats:

%d{ABSOLUTE}   "HH:mm:ss,SSS"
%d{DATE}       "dd MMM YYYY HH:mm:ss,SSS"
%d{ISO8601}    "YYYY-mm-dd HH:mm:ss,SSS"

SEE ALSO

AUTHOR

Mike Schilli, <m@perlmeister.com>