1Layout::PatternLayout(3U)ser Contributed Perl DocumentatiLoanyout::PatternLayout(3)
2
6 Log::Log4perl::Layout::PatternLayout - Pattern Layout
7
9 use Log::Log4perl::Layout::PatternLayout;
10 my $layout = Log::Log4perl::Layout::PatternLayout->new(
12 "%d (%F:%L)> %m");
13
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 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 %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 NDC and MDC are explained in "Nested Diagnostic Context (NDC)" in
45 Log::Log4perl and "Mapped Diagnostic Context (MDC)" in Log::Log4perl.
46 The granularity of time values is milliseconds if Time::HiRes is avail‐
48 able. If not, only full seconds are used.
49 Quantify placeholders
51 All placeholders can be extended with formatting instructions, just
53 like in printf:
54 %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 Fine-tuning with curlies
64 Some placeholders have special functions defined if you add curlies
66 with content after them:
67 %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 %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 %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 In this way, you're able to shrink the displayed category or limit
83 file/path components to save space in your logs.
84 Fine-tune the date
86 If you're not happy with the default %d format for the date which looks
88 like
89 yyyy/MM/DD HH:mm:ss
91 (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 %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 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 (Text): 4 or more pattern letters--use full form, < 4--use short or
119 abbreviated form if one exists.
120 (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 (Text & Number): 3 or over, use text, otherwise use number.
127 There's also a bunch of pre-defined formats:
129 %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 Custom cspecs
135 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 If the existing corpus of placeholders/cspecs isn't good enough for
143 you, you can easily roll your own:
144 #'U' a global user-defined cspec
146 log4j.PatternLayout.cspec.U = sub { return "UID: $< "}
147 #'K' cspec local to appndr1 (pid in hex)
149 log4j.appender.appndr1.layout.cspec.K = sub { return sprintf "%1x", $$}
150 #and now you can use them
152 log4j.appender.appndr1.layout.ConversionPattern = %K %U %m%n
153 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 If you're an API kind of person, there's also this call:
158 Log::Log4perl::Layout::PatternLayout::
160 add_global_cspec('Z', sub {'zzzzzzzz'}); #snooze?
161 When the log messages is being put together, your anonymous sub will be
163 called with these arguments:
164 ($layout, $message, $category, $priority, $caller_level);
166 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 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 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 SECURITY NOTE
182 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 $Log::Log4perl::Config->allow_code(0);
189 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 Advanced Options
195 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 my $layout = Log::Log4perl::Layout::PatternLayout->new(
201 { time_function => \&my_time_func,
202 },
203 "%d (%F:%L)> %m");
204 Here's a list of parameters:
206 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
215 Mike Schilli, <m@perlmeister.com>
216perl v5.8.8 2002-07-10 Layout::PatternLayout(3)