1Layout::PatternLayout(3U)ser Contributed Perl DocumentatiLoanyout::PatternLayout(3)
2
3
4

NAME

6       Log::Log4perl::Layout::PatternLayout - Pattern Layout
7

SYNOPSIS

9         use Log::Log4perl::Layout::PatternLayout;
10
11         my $layout = Log::Log4perl::Layout::PatternLayout->new(
12                                                          "%d (%F:%L)> %m");
13

DESCRIPTION

15       Creates a pattern layout according to
16       http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/PatternLay
17       out.html and a couple of Log::Log4perl-specific extensions.
18
19       The "new()" method creates a new PatternLayout, specifying its log for‐
20       mat. The format string can contain a number of placeholders which will
21       be replaced by the logging engine when it's time to log the message:
22
23           %c Category of the logging event.
24           %C Fully qualified package (or class) name of the caller
25           %d Current date in yyyy/MM/dd hh:mm:ss format
26           %F File where the logging event occurred
27           %H Hostname (if Sys::Hostname is available)
28           %l Fully qualified name of the calling method followed by the
29              callers source the file name and line number between
30              parentheses.
31           %L Line number within the file where the log statement was issued
32           %m The message to be logged
33           %M Method or function where the logging request was issued
34           %n Newline (OS-independent)
35           %p Priority of the logging event
36           %P pid of the current process
37           %r Number of milliseconds elapsed from program start to logging
38              event
39           %T A stack trace of functions called
40           %x The topmost NDC (see below)
41           %X{key} The entry 'key' of the MDC (see below)
42           %% A literal percent (%) sign
43
44       NDC and MDC are explained in "Nested Diagnostic Context (NDC)" in
45       Log::Log4perl and "Mapped Diagnostic Context (MDC)" in Log::Log4perl.
46
47       The granularity of time values is milliseconds if Time::HiRes is avail‐
48       able.  If not, only full seconds are used.
49
50       Quantify placeholders
51
52       All placeholders can be extended with formatting instructions, just
53       like in printf:
54
55           %20c   Reserve 20 chars for the category, right-justify and fill
56                  with blanks if it is shorter
57           %-20c  Same as %20c, but left-justify and fill the right side
58                  with blanks
59           %09r   Zero-pad the number of milliseconds to 9 digits
60           %.8c   Specify the maximum field with and have the formatter
61                  cut off the rest of the value
62
63       Fine-tuning with curlies
64
65       Some placeholders have special functions defined if you add curlies
66       with content after them:
67
68           %c{1}  Just show the right-most category compontent, useful in large
69                  class hierarchies (Foo::Baz::Bar -> Bar)
70           %c{2}  Just show the two right most category components
71                  (Foo::Baz::Bar -> Baz::Bar)
72
73           %F     Display source file including full path
74           %F{1}  Just display filename
75           %F{2}  Display filename and last path component (dir/test.log)
76           %F{3}  Display filename and last two path components (d1/d2/test.log)
77
78           %m     Display fully qualified method/function name
79           %m{1}  Just display method name (foo)
80           %m{2}  Display method name and last path component (main::foo)
81
82       In this way, you're able to shrink the displayed category or limit
83       file/path components to save space in your logs.
84
85       Fine-tune the date
86
87       If you're not happy with the default %d format for the date which looks
88       like
89
90           yyyy/MM/DD HH:mm:ss
91
92       (which is slightly different from Log4j which uses "yyyy-MM-dd
93       HH:mm:ss,SSS") you're free to fine-tune it in order to display only
94       certain characteristics of a date, according to the SimpleDateFormat in
95       the Java World (http://java.sun.com/j2se/1.3/docs/api/java/text/Simple
96       DateFormat.html):
97
98           %d{HH:mm}     "23:45" -- Just display hours and minutes
99           %d{yy, EEEE}  "02, Monday" -- Just display two-digit year
100                                         and spelled-out weekday
101       Here's the symbols and their meaning, according to the SimpleDateFormat
102       specification:
103
104           Symbol   Meaning                 Presentation     Example
105           ------   -------                 ------------     -------
106           G        era designator          (Text)           AD
107           y        year                    (Number)         1996
108           M        month in year           (Text & Number)  July & 07
109           d        day in month            (Number)         10
110           h        hour in am/pm (1-12)    (Number)         12
111           H        hour in day (0-23)      (Number)         0
112           m        minute in hour          (Number)         30
113           s        second in minute        (Number)         55
114           E        day in week             (Text)           Tuesday
115           D        day in year             (Number)         189
116           a        am/pm marker            (Text)           PM
117
118           (Text): 4 or more pattern letters--use full form, < 4--use short or
119                   abbreviated form if one exists.
120
121           (Number): the minimum number of digits. Shorter numbers are
122                     zero-padded to this amount. Year is handled
123                     specially; that is, if the count of 'y' is 2, the
124                     Year will be truncated to 2 digits.
125
126           (Text & Number): 3 or over, use text, otherwise use number.
127
128       There's also a bunch of pre-defined formats:
129
130           %d{ABSOLUTE}   "HH:mm:ss,SSS"
131           %d{DATE}       "dd MMM yyyy HH:mm:ss,SSS"
132           %d{ISO8601}    "yyyy-MM-dd HH:mm:ss,SSS"
133
134       Custom cspecs
135
136       First of all, "cspecs" is short for "conversion specifiers", which is
137       the log4j and the printf(3) term for what Mike is calling "placehold‐
138       ers."  I suggested "cspecs" for this part of the api before I saw that
139       Mike was using "placeholders" consistently in the log4perl documenta‐
140       tion.  Ah, the joys of collaboration ;=) --kg
141
142       If the existing corpus of placeholders/cspecs isn't good enough for
143       you, you can easily roll your own:
144
145           #'U' a global user-defined cspec
146           log4j.PatternLayout.cspec.U = sub { return "UID: $< "}
147
148           #'K' cspec local to appndr1                 (pid in hex)
149           log4j.appender.appndr1.layout.cspec.K = sub { return sprintf "%1x", $$}
150
151           #and now you can use them
152           log4j.appender.appndr1.layout.ConversionPattern = %K %U %m%n
153
154       The benefit of this approach is that you can define and use the cspecs
155       right next to each other in the config file.
156
157       If you're an API kind of person, there's also this call:
158
159           Log::Log4perl::Layout::PatternLayout::
160                           add_global_cspec('Z', sub {'zzzzzzzz'}); #snooze?
161
162       When the log messages is being put together, your anonymous sub will be
163       called with these arguments:
164
165           ($layout, $message, $category, $priority, $caller_level);
166
167           layout: the PatternLayout object that called it
168           message: the logging message (%m)
169           category: e.g. groceries.beverages.adult.beer.schlitz
170           priority: e.g. DEBUG⎪WARN⎪INFO⎪ERROR⎪FATAL
171           caller_level: how many levels back up the call stack you have
172               to go to find the caller
173
174       There are currently some issues around providing API access to an
175       appender-specific cspec, but let us know if this is something you want.
176
177       Please note that the subroutines you're defining in this way are going
178       to be run in the "main" namespace, so be sure to fully qualify func‐
179       tions and variables if they're located in different packages.
180
181       SECURITY NOTE
182
183       This feature means arbitrary perl code can be embedded in the config
184       file.  In the rare case where the people who have access to your config
185       file are different from the people who write your code and shouldn't
186       have execute rights, you might want to set
187
188           $Log::Log4perl::Config->allow_code(0);
189
190       before you call init().  Alternatively you can supply a restricted set
191       of Perl opcodes that can be embedded in the config file as described in
192       "Restricting what Opcodes can be in a Perl Hook" in Log::Log4perl.
193
194       Advanced Options
195
196       The constructor of the "Log::Log4perl::Layout::PatternLayout" class
197       takes an optional hash reference as a first argument to specify addi‐
198       tional options in order to (ab)use it in creative ways:
199
200         my $layout = Log::Log4perl::Layout::PatternLayout->new(
201           { time_function       => \&my_time_func,
202           },
203           "%d (%F:%L)> %m");
204
205       Here's a list of parameters:
206
207       time_function
208           Takes a reference to a function returning the time for the
209           time/date fields, either in seconds since the epoch or as a refer‐
210           ence to an array, carrying seconds and microseconds, just like
211           "Time::HiRes::gettimeofday" does.
212

SEE ALSO

AUTHOR

215       Mike Schilli, <m@perlmeister.com>
216
217
218
219perl v5.8.8                       2002-07-10          Layout::PatternLayout(3)
Impressum