Debian Codegraph @

logback-site/src/site/pages/manual/configuration.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
7 <title>Chapter 3: Configuration</title>
8
9 <link rel="stylesheet" type="text/css" href="../css/common.css" />
10 <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
11 <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
12 <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" />
13
14 </head>
15 <body onload="prettyPrint(); decorate();">
16
17 <script type="text/javascript">prefix='../'</script>
18 <script type="text/javascript" src="../js/prettify.js"></script>
19 <script src="../templates/header.js" type="text/javascript"></script>
20 <script type="text/javascript" src="../js/dsl.js"></script>
21 <script type="text/javascript" src="../js/jquery-min.js"></script>
22 <script type="text/javascript" src="../js/decorator.js"></script>
23
24 <div id="left">
25 <noscript>Please turn on Javascript to view this menu</noscript>
26 <script src="../templates/left.js" type="text/javascript"></script>
27 </div>
28 <div id="right">
29 <script src="menu.js" type="text/javascript"></script>
30 </div>
31 <div id="content" class="chapter">
32
33 <h1>Chapter 3: Logback configuration</h1>
34
35 <a href="configuration_ja.html">&#x548C;&#x8A33; (Japanese translation)</a>
36
37
38 <div class="quote">
39 <p><em>In symbols one observes an advantage in discovery which
40 is greatest when they express the exact nature of a thing
41 briefly and, as it were, picture it; then indeed the labor of
42 thought is wonderfully diminished.</em>
43 </p>
44 <p>&mdash;GOTTFRIED WILHELM LEIBNIZ</p>
45 </div>
46
47
48 <script src="../templates/creative.js" type="text/javascript"></script>
49
50
51 <p>We start by presenting ways for configuring logback, with many
52 example configuration scripts. Joran, the configuration framework
53 upon which logback relies will be presented in <a
54 href="onJoran.html">a later chapter</a>.
55 </p>
56
57
58 <h2 class="doAnchor" name="auto_configuration">Configuration in
59 logback</h2>
60
61 <p>Inserting log requests into the application code requires a
62 fair amount of planning and effort. Observation shows that
63 approximately four percent of code is dedicated to
64 logging. Consequently, even a moderately sized application will
65 contain thousands of logging statements embedded within its
66 code. Given their number, we need tools to manage these log
67 statements.
68 </p>
69
70 <p>Logback can be configured either programmatically or with a
71 configuration script expressed in XML or Groovy format. By the
72 way, existing log4j users can convert their
73 <em>log4j.properties</em> files to <em>logback.xml</em> using our
74 <a
75 href="http://logback.qos.ch/translator/">PropertiesTranslator</a>
76 web-application.
77 </p>
78
79 <p>Let us begin by discussing the initialization steps that
80 logback follows to try to configure itself:
81 </p>
82
83 <ol>
84
85 <li>
86 <p>Logback tries to find a file called
87 <em>logback-test.xml</em> <a
88 href="../faq.html#configFileLocation">in the
89 classpath</a>.</p> </li>
90
91 <li>
92 <p>If no such file is found, logback tries to find a file called
93 <em>logback.groovy</em> <a
94 href="../faq.html#configFileLocation">in the
95 classpath</a>.</p>
96 </li>
97
98
99 <li><p>If no such file is found, it checks for the file
100 <em>logback.xml</em> <a
101 href="../faq.html#configFileLocation">in the
102 classpath</a>..</p>
103 </li>
104
105 <li><p>If no such file is found, <a
106 href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">
107 service-provider loading facility</a> (introduced in JDK 1.6) is
108 used to resolve the implementation of <a
109 href="../xref/ch/qos/logback/classic/spi/Configurator.html">
110 <code>com.qos.logback.classic.spi.Configurator</code></a>
111 interface by looking up the file
112 <em>META-INF\services\ch.qos.logback.classic.spi.Configurator</em>
113 in the class path. Its contents should specify the fully
114 qualified class name of the desired <code>Configurator</code>
115 implementation.
116 </p>
117 </li>
118
119 <li><p>If none of the above succeeds, logback configures itself
120 automatically using the <a
121 href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code></a>
122 which will cause logging output to be directed to the console.
123 </p>
124 </li>
125
126 </ol>
127
128 <p>The last step is meant as last-ditch effort to provide a
129 default (but very basic) logging functionality in the absence of a
130 configuration file.
131 </p>
132
133
134 <p>If you are using Maven and if you place the
135 <em>logback-test.xml</em> under the <em>src/test/resources</em>
136 folder, Maven will ensure that it won't be included in the
137 artifact produced. Thus, you can use a different configuration
138 file, namely <em>logback-test.xml</em> during testing, and another
139 file, namely, <em>logback.xml</em>, in production.
140 </p>
141
142 <p><span class="label">Fast start-up</span> It takes about 100
143 miliseconds for Joran to parse a given logback configuration
144 file. To shave off those miliseconds at aplication start up, you
145 can use the service-provider loading facility (item 4 above) to
146 load your own custom <code>Configurator</code> class with <a
147 href="../xref/ch/qos/logback/classic/BasicConfigurator.html">BasicConfigrator</a>
148 serving as a good starting point.</p>
149
150
151 <h3 class="doAnchor" name="automaticConf">Automatically
152 configuring logback</h3>
153
154 <p>The simplest way to configure logback is by letting logback
155 fall back to its default configuration. Let us give a taste of how
156 this is done in an imaginary application called
157 <code>MyApp1</code>.
158 </p>
159
160 <p class="example">Example: Simple example of
161 <code>BasicConfigurator</code> usage <a
162 href="../xref/chapters/configuration/MyApp1.html">(logback-examples/src/main/java/chapters/configuration/MyApp1.java)</a></p>
163
164 <pre class="prettyprint source">package chapters.configuration;
165
166 import org.slf4j.Logger;
167 import org.slf4j.LoggerFactory;
168
169 public class MyApp1 {
170 final static Logger logger = LoggerFactory.getLogger(MyApp1.class);
171
172 public static void main(String[] args) {
173 logger.info("Entering application.");
174
175 Foo foo = new Foo();
176 foo.doIt();
177 logger.info("Exiting application.");
178 }
179 }</pre>
180
181 <p>This class defines a static logger variable. It then instantiates
182 a <code>Foo</code> object. The <code>Foo</code> class is listed
183 below:
184 </p>
185
186 <p class="example">Example: Small class doing logging
187 <a href="../xref/chapters/configuration/Foo.html">(logback-examples/src/main/java/chapters/configuration/Foo.java)</a>
188 </p>
189
190 <pre class="prettyprint source">package chapters.configuration;
191
192 import org.slf4j.Logger;
193 import org.slf4j.LoggerFactory;
194
195 public class Foo {
196 static final Logger logger = LoggerFactory.getLogger(Foo.class);
197
198 public void doIt() {
199 logger.debug("Did it again!");
200 }
201 }</pre>
202
203
204 <p>In order to run the examples in this chapter, you need to make
205 sure that certain jar files are present on the class path. Please
206 refer to the <a href="../setup.html">setup page</a> for further
207 details.
208 </p>
209
210 <p>Assuming the configuration files <em>logback-test.xml</em> or
211 <em>logback.xml</em> are not present, logback will default to
212 invoking <a
213 href="../xref/ch/qos/logback/classic/BasicConfigurator.html"><code>BasicConfigurator</code></a>
214 which will set up a minimal configuration. This minimal
215 configuration consists of a <code>ConsoleAppender</code> attached
216 to the root logger. The output is formatted using a
217 <code>PatternLayoutEncoder</code> set to the pattern
218 <em>%d{HH:mm:ss.SSS}&nbsp;[%thread]&nbsp;%-5level&nbsp;%logger{36}&nbsp;-&nbsp;%msg%n</em>. Moreover,
219 by default the root logger is assigned the <code>DEBUG</code>
220 level.
221 </p>
222
223 <p>Thus, the output of the command <em>java chapters.configuration.MyApp1</em>
224 should be similar to:
225 </p>
226
227 <p class="source">16:06:09.031 [main] INFO chapters.configuration.MyApp1 - Entering application.
228 16:06:09.046 [main] DEBUG chapters.configuration.Foo - Did it again!
229 16:06:09.046 [main] INFO chapters.configuration.MyApp1 - Exiting application.</p>
230
231
232 <p class="highlight">Except code that configures logback (if such
233 code exists) client code does not need to depend on
234 logback. Applications that use logback as their logging framework
235 will have a compile-time dependency on SLF4J but not logback.
236 </p>
237
238 <p>The <code>MyApp1</code> application links to logback via calls
239 to <code>org.slf4j.LoggerFactory</code> and
240 <code>org.slf4j.Logger</code> classes, retrieve the loggers it
241 wishes to use, and chugs on. Note that the only dependencies of
242 the <code>Foo</code> class on logback are through
243 <code>org.slf4j.LoggerFactory</code> and
244 <code>org.slf4j.Logger</code> imports. Except code that configures
245 logback (if such code exists) client code does not need to depend
246 on logback. Since SLF4J permits the use of any logging
247 framework under its abstraction layer, it is easy to migrate
248 large bodies of code from one logging framework to another.
249 </p>
250
251 <h3>Automatic configuration with <em>logback-test.xml</em> or
252 <em>logback.xml</em></h3>
253
254 <p>As mentioned earlier, logback will try to configure itself using
255 the files <em>logback-test.xml</em> or <em>logback.xml</em> if
256 found on the class path. Here is a configuration file equivalent to
257 the one established by <code>BasicConfigurator</code> we've just
258 seen.
259 </p>
260
261 <p class="example">Example: Basic configuration file
262 (logback-examples/src/main/resources/chapters/configuration/sample0.xml)</p>
263 <span class="asGroovy" onclick="return asGroovy('sample0');">View as .groovy</span>
264
265
266 <pre id="sample0" class="prettyprint source">&lt;configuration>
267
268 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
269 &lt;!-- encoders are assigned the type
270 ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
271 &lt;encoder>
272 &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern>
273 &lt;/encoder>
274 &lt;/appender>
275
276 &lt;root level="debug">
277 &lt;appender-ref ref="STDOUT" />
278 &lt;/root>
279 &lt;/configuration></pre>
280
281 <p>After you have renamed <em>sample0.xml</em> as
282 <em>logback.xml</em> (or <em>logback-test.xml</em>) place it into a
283 directory accessible from the class path. Running the <em>MyApp1</em>
284 application should give identical results to its previous run.</p>
285
286 <h4 class="doAnchor" name="automaticStatusPrinting">Automatic
287 printing of status messages in case of warning or errors</h4>
288
289 <p class="highlight">If warning or errors occur during the parsing
290 of the configuration file, logback will automatically print its
291 internal status messages on the console.</p>
292
293 <p>If warnings or errors occur during the parsing of the
294 configuration file, logback will automatically print its internal
295 status data on the console. Note that to avoid duplication,
296 automatic status printing is disabled if the user explicitly
297 registers a status listener (defined below).</p>
298
299 <p>In the absence of warnings or errors, if you still wish to
300 inspect logback's internal status, then you can instruct logback to
301 print status data by invoking the <code>print()</code> of the
302 <code>StatusPrinter</code> class. The <em>MyApp2</em> application
303 shown below is identical to <em>MyApp1</em> except for the addition
304 of two lines of code for printing internal status data.</p>
305
306 <p class="example">Example: Print logback's internal status
307 information <a
308 href="../xref/chapters/configuration/MyApp2.html">(logback-examples/src/main/java/chapters/configuration/MyApp2.java)</a></p>
309
310
311 <pre class="prettyprint lang-java source">
312 public static void main(String[] args) {
313 // assume SLF4J is bound to logback in the current environment
314 <b>LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();</b>
315 // print logback's internal status
316 <b>StatusPrinter.print(lc);</b>
317 ...
318 }</pre>
319
320 <p>If everything goes well, you should see the following output on the console</p>
321
322 <div class="source longline"><pre>17:44:58,578 |-INFO in ch.qos.logback.classic.LoggerContext[default] - Found resource [logback-test.xml]
323 17:44:58,671 |-INFO in ch.qos.logback.classic.joran.action.ConfigurationAction - debug attribute not set
324 17:44:58,671 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - About to instantiate appender of type [ch.qos.logback.core.ConsoleAppender]
325 17:44:58,687 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - Naming appender as [STDOUT]
326 17:44:58,812 |-INFO in ch.qos.logback.core.joran.action.AppenderAction - Popping appender named [STDOUT] from the object stack
327 17:44:58,812 |-INFO in ch.qos.logback.classic.joran.action.LevelAction - root level set to DEBUG
328 17:44:58,812 |-INFO in ch.qos.logback.core.joran.action.AppenderRefAction - Attaching appender named [STDOUT] to Logger[root]
329
330 17:44:58.828 [main] INFO chapters.configuration.MyApp2 - Entering application.
331 17:44:58.828 [main] DEBUG chapters.configuration.Foo - Did it again!
332 17:44:58.828 [main] INFO chapters.configuration.MyApp2 - Exiting application.
333 </pre></div>
334
335 <p>At the end of this output, you can recognize the lines that were
336 printed in the previous example. You should also notice the
337 logback's internal messages, a.k.a. <code>Status</code> objects,
338 which allow convenient access to logback's internal state.
339 </p>
340
341 <h4 class="doAnchor" name="dumpingStatusData">Status data</h4>
342
343 <p class="highlight">Enabling output of status data usually goes a
344 long way in the diagnosis of issues with logback. As such, it is
345 highly recommended and should be considered as a recourse of
346 <b>first</b> resort.</p>
347
348 <p>Instead of invoking <code>StatusPrinter</code> programmatically
349 from your code, you can instruct the configuration file to dump
350 status data, even in the absence of errors. To achieve this, you
351 need to set the <span class="attr">debug</span> attribute of the
352 <em>configuration</em> element, i.e. the top-most element in the
353 configuration file, as shown below. Please note that this <span
354 class="attr">debug</span> attribute relates only to the status
355 data. It does <em>not</em> affect logback's configuration
356 otherwise, in particular with respect to logger levels. (If you are
357 asking, no, the root logger will <em>not</em> be set to
358 <code>DEBUG</code>.)
359 </p>
360
361 <p class="example">Example: Basic configuration file using debug
362 mode
363 (logback-examples/src/main/resources/chapters/configuration/sample1.xml)</p>
364 <span class="asGroovy" onclick="return asGroovy('sample1');">View as .groovy</span>
365
366 <pre id="sample1" class="prettyprint source">
367 &lt;configuration <span class="big bold">debug="true"</span>>
368
369 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
370 &lt;!-- encoders are by default assigned the type
371 ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
372 &lt;encoder>
373 &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern>
374 &lt;/encoder>
375 &lt;/appender>
376
377 &lt;root level="debug">
378 &lt;appender-ref ref="STDOUT" />
379 &lt;/root>
380 &lt;/configuration></pre>
381
382 <p>Setting <code>debug="true"</code> within the
383 &lt;configuration&gt; element will output status information,
384 assuming that:
385 </p>
386 <ol>
387 <li>the configuration file is found</li>
388 <li>the configuration file is well-formed XML.</li>
389 </ol>
390
391 <p>If any of these two conditions is not fulfilled, Joran cannot
392 interpret the <span class="attr">debug</span> attribute since the
393 configuration file cannot be read. If the configuration file is
394 found but is malformed, then logback will detect the error
395 condition and automatically print its internal status on the
396 console. However, if the configuration file cannot be found,
397 logback will not automatically print its status data, since this is
398 not necessarily an error condition. Programmatically invoking
399 <code>StatusPrinter.print()</code> as shown in the <a
400 href="../xref/chapters/configuration/MyApp2.html"><em>MyApp2</em></a>
401 application above ensures that status information is printed in
402 every case.</p>
403
404
405
406 <p><span class="label">Forcing status output</span> In the absence
407 of status messages, tracking down a rogue <em>logback.xml</em>
408 configuration file can be difficult, especially in production where
409 the application source cannot be easily modified. To help identify
410 the location of a rogue configuration file, you can set a
411 <code>StatusListener</code> via the "logback.statusListenerClass"
412 system property (<a href="#logback.statusLC">defined below</a>) to
413 force output of status messages. The "logback.statusListenerClass"
414 system property can also be used to silence output automatically
415 generated in case of errors.
416 </p>
417
418 <p>By the way, setting <code>debug="true"</code> is strictly
419 equivalent to installing an
420 <code>OnConsoleStatusListener</code>. Status listeners are
421 disccussed further below. The installation of
422 <code>OnConsoleStatusListener</code> is shown next. </p>
423
424 <p class="example">Example: Registering a status listener
425 (logback-examples/src/main/resources/chapters/configuration/onConsoleStatusListener.xml)</p>
426 <span class="asGroovy" onclick="return asGroovy('onConsoleStatusListener');">View as .groovy</span>
427 <pre id="onConsoleStatusListener" class="prettyprint source">&lt;configuration>
428 <b>&lt;statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /></b>
429
430 ... the rest of the configuration file
431 &lt;/configuration></pre>
432
433
434 <p>Enabling output of status data, either via the debug attribute
435 or equivalently by installing <code>OnConsoleStatusListener</code>,
436 will go a long way in helping you diagnose logback issues. As such,
437 enabling logback status data is very highly recommended and should
438 be considered as a recourse of <b>first</b> resort.
439 </p>
440
441 <h3 class="doAnchor" name="configFileProperty">Specifying the
442 location of the default configuration file as a system
443 property</h3>
444
445 <p>You may specify the location of the default configuration file
446 with a system property named
447 <code>"logback.configurationFile"</code>. The value of this
448 property can be a URL, a resource on the class path or a path to a
449 file external to the application.
450 </p>
451
452 <p class="source">java <b>-Dlogback.configurationFile=/path/to/config.xml</b> chapters.configuration.MyApp1</p>
453
454 <p>Note that the file extension must be ".xml" or ".groovy". Other
455 extensions are ignored. <a href="#logback.statusLC">Explicitly
456 registering a status listener</a> may help debugging issues
457 locating the configuration file.</p>
458
459
460 <h3 class="doAnchor" name="autoScan">Automatically reloading
461 configuration file upon modification</h3>
462
463 <p class="highlight">Logback-classic can scan for changes in its
464 configuration file and automatically reconfigure itself when the
465 configuration file changes.</p>
466
467 <p>If instructed to do so, logback-classic will scan for changes in
468 its configuration file and automatically reconfigure itself when
469 the configuration file changes. In order to instruct
470 logback-classic to scan for changes in its configuration file and
471 to automatically re-configure itself set the <span
472 class="attr">scan</span> attribute of the
473 <code>&lt;configuration></code> element to true, as shown next.
474
475 </p>
476
477 <p class="example">Example: Scanning for changes in configuration
478 file and automatic re-configuration
479 (logback-examples/src/main/resources/chapters/configuration/scan1.xml)</p>
480
481 <span class="asGroovy" onclick="return asGroovy('scan1');">View as .groovy</span>
482 <pre id="scan1" class="prettyprint source">
483 &lt;configuration <b>scan="true"</b>>
484 ...
485 &lt;/configuration> </pre>
486
487
488 <p>By default, the configuration file will be scanned for changes
489 once every minute. You can specify a different scanning period by
490 setting the <span class="attr">scanPeriod</span> attribute of the
491 <code>&lt;configuration></code> element. Values can be specified in
492 units of milliseconds, seconds, minutes or hours. Here is an
493 example:</p>
494
495 <p class="example">Example: Specifying a different scanning period
496 (logback-examples/src/main/resources/chapters/configuration/scan2.xml)</p>
497 <span class="asGroovy" onclick="return asGroovy('scan2');">View as .groovy</span>
498 <pre id="scan2" class="prettyprint source">
499 &lt;configuration scan="true" <b>scanPeriod="30 seconds"</b> >
500 ...
501 &lt;/configuration> </pre>
502
503 <p><span class="label">Note</span> If no unit of time is specified,
504 then the unit of time is assumed to be milliseconds, which is
505 usually inappropriate. If you change the default scanning period,
506 do not forget to specify a time unit.
507 </p>
508
509 <p>Behind the scenes, when you set the scan attribute to true, a
510 <code>TurboFilter</code> called <a
511 href="../xref/ch/qos/logback/classic/turbo/ReconfigureOnChangeFilter.html">ReconfigureOnChangeFilter</a>
512 will be installed. TurboFilters are described in a <a
513 href="filters.html#TurboFilter">later chapter</a>. As a
514 consequence, scanning is done "in-thread", that is any time a
515 printing method of logger is invoked. For example, for a logger
516 named <code>myLogger</code>, when you write
517 "myLogger.debug("hello");", and if the scan attribute is set to
518 true, then <code>ReconfigureOnChangeFilter</code> will be
519 invoked. Moreover, the said filter will be invoked even if
520 <code>myLogger</code> is disabled for the DEBUG level.
521 </p>
522
523 <p class="highlight">When a configuration file changes, it will be
524 automatically reloaded but only after several logger invocations
525 and after a delay determined by the scanning period.
526 </p>
527
528 <p>Given that <code>ReconfigureOnChangeFilter</code> is invoked
529 every time <em>any</em> logger is invoked, regardless of logger
530 level, <code>ReconfigureOnChangeFilter</code> is absolutely
531 performance critical. So much so that in fact, the check whether
532 the scan period has elapsed or not, is too costly in itself. In
533 order to improve performance,
534 <code>ReconfigureOnChangeFilter</code> is in reality "alive" only
535 once every <em>N</em> logging operations. Depending on how often
536 your application logs, the value of <em>N</em> can be modified on
537 the fly by logback. By default N is 16, although it can go as high
538 as 2^16 (=&nbsp;65536) for CPU-intensive applications.
539 </p>
540
541 <p>In short, when a configuration file changes, it will be
542 automatically reloaded but only after several logger invocations
543 <em>and</em> after a delay determined by the scanning period.
544 </p>
545
546
547 <h4 class="doAnchor" name="packagingData">Enabling packaging data in stack traces</h4>
548
549 <p class="highlight">While useful, packaging data is expensive to
550 compute, especially in applications with frequent exceptions.</p>
551
552 <p><span class="label notice">NOTE</span> As of version 1.1.4,
553 packaging data is disabled by default. </p>
554
555 <p>If instructed to do so, logback can include packaging data for
556 each line of the stack trace lines it outputs. Packaging data
557 consists of the name and version of the jar file whence the class
558 of the stack trace line originated. Packaging data can be very
559 useful in identifying software versioning issues. However, it is
560 rather expensive to compute, especially in application where
561 exceptions are thrown frequently. Here is a sample output:</p>
562
563 <pre>14:28:48.835 [btpool0-7] INFO c.q.l.demo.prime.PrimeAction - 99 is not a valid value
564 java.lang.Exception: 99 is invalid
565 at ch.qos.logback.demo.prime.PrimeAction.execute(PrimeAction.java:28) [classes/:na]
566 at org.apache.struts.action.RequestProcessor.processActionPerform(RequestProcessor.java:431) <b>[struts-1.2.9.jar:1.2.9]</b>
567 at org.apache.struts.action.RequestProcessor.process(RequestProcessor.java:236) [struts-1.2.9.jar:1.2.9]
568 at org.apache.struts.action.ActionServlet.doPost(ActionServlet.java:432) [struts-1.2.9.jar:1.2.9]
569 at javax.servlet.http.HttpServlet.service(HttpServlet.java:820) <b>[servlet-api-2.5-6.1.12.jar:6.1.12]</b>
570 at org.mortbay.jetty.servlet.ServletHolder.handle(ServletHolder.java:502) [jetty-6.1.12.jar:6.1.12]
571 at ch.qos.logback.demo.UserServletFilter.doFilter(UserServletFilter.java:44) [classes/:na]
572 at org.mortbay.jetty.servlet.ServletHandler$CachedChain.doFilter(ServletHandler.java:1115) <b>[jetty-6.1.12.jar:6.1.12]</b>
573 at org.mortbay.jetty.servlet.ServletHandler.handle(ServletHandler.java:361) [jetty-6.1.12.jar:6.1.12]
574 at org.mortbay.jetty.webapp.WebAppContext.handle(WebAppContext.java:417) [jetty-6.1.12.jar:6.1.12]
575 at org.mortbay.jetty.handler.ContextHandlerCollection.handle(ContextHandlerCollection.java:230) [jetty-6.1.12.jar:6.1.12]</pre>
576
577
578 <p>Packaging data is disabled by default but can be enabled by
579 configuration:</p>
580
581 <pre class="prettyprint source">
582 &lt;configuration <span class="big bold">packagingData="true"</span>>
583 ...
584 &lt;/configuration></pre>
585
586 <p>Alternatively, packaging data can be enabled/disabled
587 programmatically by invoking the <a
588 href="../apidocs/ch/qos/logback/classic/LoggerContext.html#setPackagingDataEnabled(boolean)">setPackagingDataEnabled(boolean)</a>
589 method in <code>LoggerContext</code>, as shown next:</p>
590
591
592 <pre class="prettyprint lang-java source">
593 LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
594 <b>lc.setPackagingDataEnabled(true);</b>
595 </pre>
596
597 <h3 class="doAnchor" name="joranDirectly">Invoking
598 <code>JoranConfigurator</code> directly</h3>
599
600 <p>Logback relies on a configuration library called Joran, part of
601 logback-core. Logback's default configuration mechanism invokes
602 <code>JoranConfigurator</code> on the default configuration file it
603 finds on the class path. If you wish to override logback's default
604 configuration mechanism for whatever reason, you can do so by
605 invoking <code>JoranConfigurator</code> directly. The next
606 application, <em>MyApp3</em>, invokes JoranConfigurator on a
607 configuration file passed as a parameter.</p>
608
609 <p class="example">Example: Invoking <code>JoranConfigurator</code>
610 directly <a
611 href="../xref/chapters/configuration/MyApp3.html">(logback-examples/src/main/java/chapters/configuration/MyApp3.java)</a></p>
612
613 <pre class="prettyprint source">package chapters.configuration;
614
615 import org.slf4j.Logger;
616 import org.slf4j.LoggerFactory;
617
618 import ch.qos.logback.classic.LoggerContext;
619 import ch.qos.logback.classic.joran.JoranConfigurator;
620 import ch.qos.logback.core.joran.spi.JoranException;
621 import ch.qos.logback.core.util.StatusPrinter;
622
623 public class MyApp3 {
624 final static Logger logger = LoggerFactory.getLogger(MyApp3.class);
625
626 public static void main(String[] args) {
627 // assume SLF4J is bound to logback in the current environment
628 <b>LoggerContext context = (LoggerContext) LoggerFactory.getILoggerFactory();</b>
629
630 <b>try {
631 JoranConfigurator configurator = new JoranConfigurator();
632 configurator.setContext(context);
633 // Call context.reset() to clear any previous configuration, e.g. default
634 // configuration. For multi-step configuration, omit calling context.reset().
635 context.reset();
636 configurator.doConfigure(args[0]);
637 } catch (JoranException je) {
638 // StatusPrinter will handle this
639 }
640 StatusPrinter.printInCaseOfErrorsOrWarnings(context);</b>
641
642 logger.info("Entering application.");
643
644 Foo foo = new Foo();
645 foo.doIt();
646 logger.info("Exiting application.");
647 }
648 }</pre>
649
650 <p>This application fetches the <code>LoggerContext</code>
651 currently in effect, creates a new <code>JoranConfigurator</code>,
652 sets the context on which it will operate, resets the logger
653 context, and then finally asks the configurator to configure the
654 context using the configuration file passed as a parameter to the
655 application. Internal status data is printed in case of warnings or
656 errors. Note that for multi-step configuration,
657 <code>context.reset()</code> invocation should be omitted.</p>
658
659 <h3 class="doAnchor" name="viewingStatusMessages">Viewing status
660 messages </h3>
661
662 <p>Logback collects its internal status data in a <code><a
663 href="../xref/ch/qos/logback/core/status/StatusManager.html">StatusManager</a></code>
664 object, accessible via the <code>LoggerContext</code>.
665 </p>
666
667 <p>Given a <code>StatusManager</code> you can access all the status
668 data associated with a logback context. To keep memory usage at
669 reasonable levels, the default <code>StatusManager</code>
670 implementation stores the status messages in two separate parts:
671 the header part and the tail part. The header part stores the first
672 <em>H</em> status messages whereas the tail part stores the last
673 <em>T</em> messages. At present time <em>H</em>=<em>T</em>=150,
674 although these values may change in future releases.</p>
675
676 <p>Logback-classic ships with a servlet called
677 ViewStatusMessagesServlet. This servlet prints the contents of the
678 <code>StatusManager</code> associated with the current
679 <code>LoggerContext</code> as an HTML table. Here is sample output.
680 </p>
681
682 <a href="images/chapters/configuration/lbClassicStatus.jpg">
683 <img src="images/chapters/configuration/lbClassicStatus.jpg" alt="click to enlarge" width="90%"/>
684 </a>
685
686 <p>To add this servlet to your web-application, add the following
687 lines to its <em>WEB-INF/web.xml</em> file.</p>
688
689 <pre class="prettyprint source"> &lt;servlet>
690 &lt;servlet-name>ViewStatusMessages&lt;/servlet-name>
691 &lt;servlet-class>ch.qos.logback.classic.ViewStatusMessagesServlet&lt;/servlet-class>
692 &lt;/servlet>
693
694 &lt;servlet-mapping>
695 &lt;servlet-name>ViewStatusMessages&lt;/servlet-name>
696 &lt;url-pattern>/lbClassicStatus&lt;/url-pattern>
697 &lt;/servlet-mapping></pre>
698
699 <p>The <code>ViewStatusMessages</code> servlet will be viewable at
700 the URL <code>http://host/yourWebapp/lbClassicStatus</code>
701 </p>
702
703 <h3 class="doAnchor" name="statusListener">Listening to status
704 messages</h3>
705
706 <p>You may also attach a <code>StatusListener</code> to a
707 <code>StatusManager</code> so that you can take immediate action in
708 response to status messages, especially to messages occurring after
709 logback configuration. Registering a status listener is a
710 convenient way to supervise logback's internal state without human
711 intervention.
712 </p>
713
714 <p>Logback ships with a <code>StatusListener</code> implementation
715 called <code><a
716 href="../xref/ch/qos/logback/core/status/OnConsoleStatusListener.html">OnConsoleStatusListener</a></code>
717 which, as its name indicates, prints all <em>new</em> incoming
718 status messages on the console.
719 </p>
720
721 <p>Here is <a
722 href="../xref/chapters/configuration/AddStatusListenerApp.html">sample
723 code</a> to register an <code>OnConsoleStatusListener</code>
724 instance with the StatusManager.
725 </p>
726
727 <pre class="prettyprint source"> LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory();
728 StatusManager statusManager = lc.getStatusManager();
729 OnConsoleStatusListener onConsoleListener = new OnConsoleStatusListener();
730 statusManager.add(onConsoleListener);</pre>
731
732 <p>Note that the registered status listener will only receive status
733 events subsequent to its registration. It will not receive prior
734 messages. Thus, it is usually a good idea to place status listener
735 registration directives at top of the configuration file before
736 other directives.</p>
737
738 <p>It is also possible to register one or more status listeners
739 within a configuration file. Here is an example.</p>
740
741 <p class="example">Example: Registering a status listener
742 (logback-examples/src/main/resources/chapters/configuration/onConsoleStatusListener.xml)</p>
743
744 <span class="asGroovy" onclick="return asGroovy('onConsoleStatusListener');">View as .groovy</span>
745 <pre id="onConsoleStatusListener" class="prettyprint source">&lt;configuration>
746 <b>&lt;statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /></b>
747
748 ... the rest of the configuration file
749 &lt;/configuration></pre>
750
751 <h3 class="doAnchor"
752 name="logback.statusLC">"logback.statusListenerClass" system
753 property</h3>
754
755 <p>One may also register a status listener by setting the
756 "logback.statusListenerClass" Java system property to the name of
757 the listener class you wish to register. For example,
758 </p>
759
760 <p class="source">java <b>-Dlogback.statusListenerClass</b>=ch.qos.logback.core.status.OnConsoleStatusListener&nbsp;...</p>
761
762 <p>Logback ships with several status listener implementations. <a
763 href="../xref/ch/qos/logback/core/status/OnConsoleStatusListener.html">OnConsoleStatusListener</a>
764 prints incoming status messages on the console, i.e. on
765 System.out. <a
766 href="../xref/ch/qos/logback/core/status/OnErrorConsoleStatusListener.html">OnErrorConsoleStatusListener</a>
767 prints incoming status messages on System.err. <a
768 href="../xref/ch/qos/logback/core/status/NopStatusListener.html">NopStatusListener</a>
769 drops incoming status messages.</p>
770
771
772 <p>Note that <a href="#automaticStatusPrinting">automatic status
773 printing</a> (in case of errors) is disabled if any status listener
774 is registered during configuration and in particular if the user
775 specifies a status listener via the "logback.statusListenerClass"
776 system. Thus, by setting <code>NopStatusListener</code> as a status
777 listener, you can silence internal status printing altogether. </p>
778
779 <p class="source">java <b>-Dlogback.statusListenerClass</b>=ch.qos.logback.core.status.NopStatusListener&nbsp;...</p>
780
781
782 <h2 class="doAnchor" name="stopContext">Stopping
783 logback-classic</h2>
784
785 <p>In order to release the resources used by logback-classic, it is
786 always a good idea to stop the logback context. Stopping the
787 context will close all appenders attached to loggers defined by the
788 context and stop any active threads.
789 </p>
790
791 <pre class="prettyprint lang-java source">
792 import org.sflf4j.LoggerFactory;
793 import ch.qos.logback.classic.LoggerContext;
794 ...
795
796 // assume SLF4J is bound to logback-classic in the current environment
797 <b>LoggerContext loggerContext = (LoggerContext) LoggerFactory.getILoggerFactory();</b>
798 <b>loggerContext.stop();</b></pre>
799
800 <p>In web-applications the above code could be invoked from within
801 the <a
802 href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContextListener.html#contextDestroyed(javax.servlet.ServletContextEvent)">contextDestroyed</a>
803 method of <code>ServletContextListener</code> in order to stop
804 logback-classic and release resources. Starting with version
805 1.1.10, the appropriate <code>ServletContextListener</code> is
806 installed automatically for you (<a href="#webShutdownHook">see just below</a>).
807 </p>
808
809 <h4 class="doAnchor" name="shutdownHook">Stopping logback-classic
810 via a shutdown hook</h4>
811
812 <p>Installing a JVM shutdown hook is a convenient way for shutting
813 down logback and releasing associated resources.
814 </p>
815
816
817 <pre class="prettyprint source">&lt;configuration debug="true">
818 &lt;!-- in the absence of the class attribute, assume
819 ch.qos.logback.core.hook.DelayingShutdownHook --&gt;
820 <b>&lt;shutdownHook/></b>
821 ....
822 &lt;/configuration></pre>
823
824 <p>The default shutdown hook, namely <a
825 href="../apidocs/ch/qos/logback/core/hook/DelayingShutdownHook.html">DelayingShutdownHook</a>,
826 can delay shutdown by a user specified duration. Note that you may
827 install a shutdown hook of your own making by setting the <span
828 class="attr">class</span> attribute to correspond to your shutdown
829 hook's class name.</p>
830
831 <h4 class="doAnchor" name="webShutdownHook">Stopping logback-classic
832 in web-applications</h4>
833
834 <p><span class="label">since 1.1.10</span> Logback-classic will
835 <b>automatically</b> ask the web-server to install a <code><a
836 href="../apidocs/ch/qos/logback/classic/servlet/LogbackServletContainerInitializer.html">LogbackServletContainerInitializer</a></code>
837 implementing the <code>ServletContainerInitializer</code> interface
838 (available in servlet-api 3.x and later). This initializer will in
839 turn install and instance of <code><a
840 href="../apidocs/ch/qos/logback/classic/servlet/LogbackServletContextListener.html">LogbackServletContextListener</a></code>.
841 This listener will stop the current logback-classic context when
842 the web-app is stopped or reloaded.
843 </p>
844
845 <p>You may disable the automatic the installation of
846 <code>LogbackServletContextListener</code> by setting a
847 &lt;context-param> named
848 <code>logbackDisableServletContainerInitializer</code> in your
849 web-application's web.xml file. Here is the relevant snippet.</p>
850
851
852 <pre class="prettyprint source">&lt;web-app>
853 &lt;context-param>
854 &lt;param-name>logbackDisableServletContainerInitializer&lt;/param-name>
855 &lt;param-value>true&lt;/param-value>
856 &lt;/context-param>
857 ....
858 &lt;/web-app></pre>
859
860 <p>Note that
861 <code>logbackDisableServletContainerInitializer</code> variable
862 can also be set as a Java system property an OS environment
863 variable. The most local setting has priority, i.e. web-app first,
864 system property second and OS environment last.</p>
865
866
867
868 <!-- =================================================================== -->
869 <!-- =================================================================== -->
870
871 <h2 class="doAnchor" name="syntax">Configuration file syntax</h2>
872
873 <p>As you have seen thus far in the manual with plenty of examples
874 still to follow, logback allows you to redefine logging behavior
875 without needing to recompile your code. Indeed, you can easily
876 configure logback so as to disable logging for certain parts of
877 your application, or direct output to a UNIX Syslog daemon, to a
878 database, to a log visualizer, or forward logging events to a
879 remote logback server, which would log according to local server
880 policy, for example by forwarding the log event to a second logback
881 server.
882 </p>
883
884 <p>The remainder of this section presents the syntax of
885 configuration files.
886 </p>
887
888 <p>As will be demonstrated over and over, the syntax of logback
889 configuration files is extremely flexible. As such, it is not
890 possible to specify the allowed syntax with a DTD file or an XML
891 schema. Nevertheless, the very basic structure of the configuration
892 file can be described as, <code>&lt;configuration></code> element,
893 containing zero or more <code>&lt;appender></code> elements,
894 followed by zero or more <code>&lt;logger></code> elements,
895 followed by at most one <code>&lt;root></code> element. The
896 following diagram illustrates this basic structure.</p>
897
898
899 <p align="left">
900 <img src="images/chapters/configuration/basicSyntax.png"
901 alt="basic Syntax" title="Basic configuration file structure"/>
902 </p>
903
904
905 <p class="highlight">If you are unsure which case to use for a
906 given tag name, just follow the <a
907 href="http://en.wikipedia.org/wiki/CamelCase">camelCase
908 convention</a> which is almost always the correct convention.</p>
909
910 <h4 class="doAnchor" name="caseSensitivity">Case sensitivity of
911 tag names</h4>
912
913 <p>Since logback version 0.9.17, tag names pertaining to explicit
914 rules are case insensitive. For example, <code>&lt;logger></code>, <code>&lt;Logger></code> and
915 <code>&lt;LOGGER></code> are valid configuration elements and will
916 be interpreted in the same way. Note that XML well-formedness
917 rules still apply, if you open a tag as <code>&lt;xyz></code> you
918 must close it as <code>&lt;/xyz></code>, <code>&lt;/XyZ></code>
919 will not work. As for <a href="onJoran.html#implicit">implicit
920 rules</a>, tag names are case sensitive except for the first
921 letter. Thus, <code>&lt;xyz></code> and <code>&lt;Xyz></code> are
922 equivalent but not <code>&lt;xYz></code>. Implicit rules usually
923 follow the <a href="http://en.wikipedia.org/wiki/CamelCase">camelCase</a>
924 convention, common in the Java world. Since it is not
925 easy to tell when a tag is associated with an explicit action and
926 when it is associated with an implicit action, it is not trivial
927 to say whether an XML tag is case-sensitive or insensitive with
928 respect to the first letter. If you are unsure which case to use
929 for a given tag name, just follow the camelCase convention which
930 is almost always the correct convention.
931 </p>
932
933 <h4 class="doAnchor" name="loggerElement">Configuring loggers, or
934 the <code>&lt;logger></code> element</h4>
935
936 <p>At this point you should have at least some understanding of <a
937 href="architecture.html#effectiveLevel">level inheritance</a> and
938 the <a href="architecture.html#basic_selection">basic selection
939 rule</a>. Otherwise, and unless you are an Egyptologist, logback
940 configuration will be no more meaningful to you than are
941 hieroglyphics.
942 </p>
943
944 <p>A logger is configured using the <code>&lt;logger></code>
945 element. A <code>&lt;logger></code> element takes exactly one
946 mandatory <span class="attr">name</span> attribute, an optional
947 <span class="attr">level</span> attribute, and an optional <span
948 class="attr">additivity</span> attribute, admitting the values
949 <em>true</em> or <em>false</em>. The value of the <span
950 class="attr">level</span> attribute admitting one of the
951 case-insensitive string values TRACE, DEBUG, INFO, WARN, ERROR,
952 ALL or OFF. The special case-insensitive value <em>INHERITED</em>,
953 or its synonym <em>NULL</em>, will force the level of the logger
954 to be inherited from higher up in the hierarchy. This comes in
955 handy if you set the level of a logger and later decide that
956 it should inherit its level.
957 </p>
958
959 <p class="highlight"> Note that unlike log4j, logback-classic does
960 <em>not</em> close nor remove any previously referenced appenders
961 when configuring a given logger.
962 </p>
963
964 <p>The <code>&lt;logger></code> element may contain zero or more
965 <code>&lt;appender-ref></code> elements; each appender thus
966 referenced is added to the named logger. Note that unlike log4j,
967 logback-classic does <em>not</em> close nor remove any previously
968 referenced appenders when configuring a given logger.
969 </p>
970
971
972
973 <h4 class="doAnchor" name="rootElement">Configuring the root
974 logger, or the <code>&lt;root></code> element</h4>
975
976 <p>The <code>&lt;root></code> element configures the root
977 logger. It supports a single attribute, namely the <span
978 class="attr">level</span> attribute. It does not allow any other
979 attributes because the additivity flag does not apply to the root
980 logger. Moreover, since the root logger is already named as
981 "ROOT", it does not allow a name attribute either. The value of the
982 level attribute can be one of the case-insensitive strings TRACE,
983 DEBUG, INFO, WARN, ERROR, ALL or OFF. Note that the level of the
984 root logger cannot be set to INHERITED or NULL.
985 </p>
986
987 <p class="highlight">Note that unlike log4j, logback-classic does
988 <em>not</em> close nor remove any previously referenced appenders
989 when configuring the root logger.</p>
990
991 <p> Similarly to the <code>&lt;logger></code> element, the
992 <code>&lt;root></code> element may contain zero or more
993 <code>&lt;appender-ref></code> elements; each appender thus
994 referenced is added to the root logger. Note that unlike log4j,
995 logback-classic does <em>not</em> close nor remove any previously
996 referenced appenders when configuring the root logger. </p>
997
998 <h4>Example</h4>
999
1000 <p>Setting the level of a logger or root logger is as simple as
1001 declaring it and setting its level, as the next example
1002 illustrates. Suppose we are no longer interested in seeing any
1003 DEBUG messages from any component belonging to the
1004 "chapters.configuration" package. The following configuration file
1005 shows how to achieve that.
1006 </p>
1007
1008 <p class="example">Example: Setting the level of a logger
1009 (logback-examples/src/main/resources/chapters/configuration/sample2.xml)</p>
1010
1011 <span class="asGroovy" onclick="return asGroovy('sample2');">View as .groovy</span>
1012 <pre id="sample2" class="prettyprint source">&lt;configuration>
1013
1014 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
1015 &lt;!-- encoders are assigned the type
1016 ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
1017 &lt;encoder>
1018 &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern>
1019 &lt;/encoder>
1020 &lt;/appender>
1021
1022 <b>&lt;logger name="chapters.configuration" level="INFO"/></b>
1023
1024 &lt;!-- Strictly speaking, the level attribute is not necessary since --&gt;
1025 &lt;!-- the level of the root level is set to DEBUG by default. --&gt;
1026 &lt;root level="DEBUG">
1027 &lt;appender-ref ref="STDOUT" />
1028 &lt;/root>
1029
1030 &lt;/configuration></pre>
1031
1032 <p>When the above configuration file is given as argument to the
1033 <em>MyApp3</em> application, it will yield the following output:
1034 </p>
1035
1036 <pre class="source">17:34:07.578 [main] INFO chapters.configuration.MyApp3 - Entering application.
1037 17:34:07.578 [main] INFO chapters.configuration.MyApp3 - Exiting application.</pre>
1038
1039 <p>Note that the message of level DEBUG generated by the <a
1040 href="../xref/chapters/configuration/Foo.html">"chapters.configuration.Foo"</a>
1041 logger has been suppressed. See also the Foo class.</p>
1042
1043 <p>You can configure the levels of as many loggers as you wish. In
1044 the next configuration file, we set the level of the
1045 <em>chapters.configuration</em> logger to INFO but at the same time set the level
1046 of the <em>chapters.configuration.Foo</em> logger to <code>DEBUG</code>.
1047 </p>
1048
1049 <p class="example">Example: Setting the level of multiple loggers
1050 (logback-examples/src/main/resources/chapters/configuration/sample3.xml)</p>
1051
1052 <span class="asGroovy" onclick="return asGroovy('sample3');">View as .groovy</span>
1053 <pre id="sample3" class="source prettyprint">&lt;configuration>
1054
1055 &lt;appender name="STDOUT"
1056 class="ch.qos.logback.core.ConsoleAppender">
1057 &lt;encoder>
1058 &lt;pattern>
1059 %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
1060 &lt;/pattern>
1061 &lt;/encoder>
1062 &lt;/appender>
1063
1064 <b>&lt;logger name="chapters.configuration" level="INFO" /></b>
1065 <b>&lt;logger name="chapters.configuration.Foo" level="DEBUG" /></b>
1066
1067 &lt;root level="DEBUG">
1068 &lt;appender-ref ref="STDOUT" />
1069 &lt;/root>
1070
1071 &lt;/configuration></pre>
1072
1073 <p>Running <code>MyApp3</code> with this configuration file will
1074 result in the following output on the console:
1075 </p>
1076
1077 <p class="prettyprint source">17:39:27.593 [main] INFO chapters.configuration.MyApp3 - Entering application.
1078 17:39:27.593 [main] DEBUG chapters.configuration.Foo - Did it again!
1079 17:39:27.593 [main] INFO chapters.configuration.MyApp3 - Exiting application.</p>
1080
1081 <p>The table below list the loggers and their levels, after
1082 <code>JoranConfigurator</code> has configured logback with the
1083 <em>sample3.xml</em> configuration file.
1084 </p>
1085
1086 <table class="bodyTable">
1087 <tr>
1088 <th>Logger name</th>
1089 <th>Assigned Level</th>
1090 <th>Effective Level</th>
1091 </tr>
1092 <tr>
1093 <td>root</td>
1094 <td><code>DEBUG</code></td>
1095 <td><code>DEBUG</code></td>
1096 </tr>
1097 <tr class="alt">
1098 <td>chapters.configuration</td>
1099 <td><code>INFO</code></td>
1100 <td><code>INFO</code></td>
1101 </tr>
1102 <tr>
1103 <td>chapters.configuration.MyApp3</td>
1104 <td><code>null</code></td>
1105 <td><code>INFO</code></td>
1106 </tr>
1107 <tr class="alt">
1108 <td>chapters.configuration.Foo</td>
1109 <td><code>DEBUG</code></td>
1110 <td><code>DEBUG</code></td>
1111 </tr>
1112 </table>
1113
1114 <p>It follows that the two logging statements of level
1115 <code>INFO</code> in the <code>MyApp3</code> class as well as the
1116 DEBUG messages in <code>Foo.doIt()</code> are all enabled. Note that
1117 the level of the root logger is always set to a non-null value,
1118 DEBUG by default.
1119 </p>
1120
1121 <p>Let us note that the <a
1122 href="architecture.html#basic_selection">basic-selection rule</a>
1123 depends on the effective level of the logger being invoked, not the
1124 level of the logger where appenders are attached. Logback will first
1125 determine whether a logging statement is enabled or not, and if
1126 enabled, it will invoke the appenders found in the logger hierarchy,
1127 regardless of their level. The configuration file
1128 <em>sample4.xml</em> is a case in point:
1129 </p>
1130
1131 <p class="example">Example: Logger level sample
1132 (logback-examples/src/main/resources/chapters/configuration/sample4.xml)</p>
1133 <span class="asGroovy" onclick="return asGroovy('sample4');">View as .groovy</span>
1134 <pre id="sample4" class="prettyprint source">&lt;configuration>
1135
1136 &lt;appender name="STDOUT"
1137 class="ch.qos.logback.core.ConsoleAppender">
1138 &lt;encoder>
1139 &lt;pattern>
1140 %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
1141 &lt;/pattern>
1142 &lt;/encoder>
1143 &lt;/appender>
1144
1145 <b>&lt;logger name="chapters.configuration" level="INFO" /></b>
1146
1147 &lt;!-- turn OFF all logging (children can override) -->
1148 &lt;root <b>level="OFF"</b>>
1149 &lt;appender-ref ref="STDOUT" />
1150 &lt;/root>
1151
1152 &lt;/configuration></pre>
1153
1154 <p>The following table lists the loggers and their levels after
1155 applying the <em>sample4.xml</em> configuration file.
1156 </p>
1157
1158 <table class="bodyTable">
1159 <tr>
1160 <th>Logger name</th>
1161 <th>Assigned Level</th>
1162 <th>Effective Level</th>
1163 </tr>
1164 <tr>
1165 <td>root</td>
1166 <td><code>OFF</code></td>
1167 <td><code>OFF</code></td>
1168 </tr>
1169 <tr class="alt">
1170 <td>chapters.configuration</td>
1171 <td><code>INFO</code></td>
1172 <td><code>INFO</code></td>
1173 </tr>
1174 <tr>
1175 <td>chapters.configuration.MyApp3</td>
1176 <td><code>null</code></td>
1177 <td><code>INFO</code></td>
1178 </tr>
1179 <tr class="alt">
1180 <td>chapters.configuration.Foo</td>
1181 <td><code>null</code></td>
1182 <td><code>INFO</code></td>
1183 </tr>
1184 </table>
1185
1186 <p>The ConsoleAppender named <em>STDOUT</em>, the only configured
1187 appender in <em>sample4.xml</em>, is attached to the root logger
1188 whose level is set to <code>OFF</code>. However, running
1189 <em>MyApp3</em> with configuration script <em>sample4.xml</em> will
1190 yield:
1191 </p>
1192
1193 <div class="source"><pre>17:52:23.609 [main] INFO chapters.configuration.MyApp3 - Entering application.
1194 17:52:23.609 [main] INFO chapters.configuration.MyApp3 - Exiting application.</pre></div>
1195
1196 <p>Thus, the level of the root logger has no apparent effect because
1197 the loggers in <code>chapters.configuration.MyApp3</code> and
1198 <code>chapters.configuration.Foo</code> classes are all enabled for the
1199 <code>INFO</code> level. As a side note, the <em>chapters.configuration</em>
1200 logger exists by virtue of its declaration in the configuration file
1201 - even if the Java source code does not directly refer to it.
1202 </p>
1203
1204 <h4 class="doAnchor" name="configuringAppenders">Configuring
1205 Appenders</h4>
1206
1207 <p>An appender is configured with the <code>&lt;appender></code>
1208 element, which takes two mandatory attributes <span
1209 class="attr">name</span> and <span class="attr">class</span>. The
1210 <span class="attr">name</span> attribute specifies the name of the
1211 appender whereas the <span class="attr">class</span> attribute
1212 specifies the fully qualified name of the appender class to
1213 instantiate. The <code>&lt;appender></code> element may contain zero
1214 or one <code>&lt;layout></code> elements, zero or more
1215 <code>&lt;encoder></code> elements and zero or more
1216 <code>&lt;filter></code> elements. Apart from these three common
1217 elements, <code>&lt;appender></code> elements may contain any number
1218 of elements corresponding to JavaBean properties of the appender
1219 class. Seamlessly supporting any property of a given logback
1220 component is one of the major strengths of <a
1221 href="onJoran.html">Joran</a> as discussed in a later chapter. The
1222 following diagram illustrates the common structure. Note that
1223 support for properties is not visible.
1224 </p>
1225
1226 <p align="left">
1227 <img src="images/chapters/configuration/appenderSyntax.png"
1228 alt="Appender Syntax" title="Appender element syntax"/>
1229 </p>
1230
1231 <p>The <code>&lt;layout></code> element takes a mandatory class
1232 attribute specifying the fully qualified name of the layout class to
1233 instantiate. As with the <code>&lt;appender></code> element,
1234 <code>&lt;layout></code> may contain other elements corresponding to
1235 properties of the layout instance. Since it's such a common case, if
1236 the layout class is <code>PatternLayout</code>, then the class
1237 attribute can be omitted as specified by <a
1238 href="onJoran.html#defaultClassMapping">default class mapping</a>
1239 rules.
1240 </p>
1241
1242 <p>The <code>&lt;encoder></code> element takes a mandatory class
1243 attribute specifying the fully qualified name of the encoder class
1244 to instantiate. Since it's such a common case, if the encoder class
1245 is <code>PatternLayoutEncoder</code>, then the class attribute can
1246 be omitted as specified by <a
1247 href="onJoran.html#defaultClassMapping">default class mapping</a>
1248 rules.
1249 </p>
1250
1251 <p>Logging to multiple appenders is as easy as defining the various
1252 appenders and referencing them in a logger, as the next
1253 configuration file illustrates:
1254 </p>
1255
1256 <p class="example">Example: Multiple loggers
1257 (logback-examples/src/main/resources/chapters/configuration/multiple.xml)</p>
1258
1259 <span class="asGroovy" onclick="return asGroovy('multiple');">View as .groovy</span>
1260 <pre id="multiple" class="prettyprint source">&lt;configuration>
1261
1262 &lt;appender name="<b>FILE</b>" class="ch.qos.logback.core.FileAppender">
1263 &lt;file>myApp.log&lt;/file>
1264
1265 &lt;encoder>
1266 &lt;pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n&lt;/pattern>
1267 &lt;/encoder>
1268 &lt;/appender>
1269
1270 &lt;appender name="<b>STDOUT</b>" class="ch.qos.logback.core.ConsoleAppender">
1271 &lt;encoder>
1272 &lt;pattern>%msg%n&lt;/pattern>
1273 &lt;/encoder>
1274 &lt;/appender>
1275
1276 &lt;root level="debug">
1277 <b>&lt;appender-ref ref="FILE" /></b>
1278 <b>&lt;appender-ref ref="STDOUT" /></b>
1279 &lt;/root>
1280 &lt;/configuration></pre>
1281
1282 <p>These configuration scripts define two appenders called
1283 <em>FILE</em> and <em>STDOUT</em>. The <em>FILE</em> appender logs
1284 to a file called <em>myApp.log</em>. The encoder for this appender
1285 is a <code>PatternLayoutEncoder</code> that outputs the date, level,
1286 thread name, logger name, file name and line number where the log
1287 request is located, the message and line separator character(s).
1288 The second appender called <code>STDOUT</code> outputs to the
1289 console. The encoder for this appender outputs only the message
1290 string followed by a line separator.
1291 </p>
1292
1293 <p>The appenders are attached to the root logger by referencing them
1294 by name within an <em>appender-ref</em> element. Note that each
1295 appender has its own encoder. Encoders are usually not designed to
1296 be shared by multiple appenders. The same is true for layouts. As
1297 such, logback configuration files do not provide any syntactical
1298 means for sharing encoders or layouts.
1299 </p>
1300
1301 <h4 class="doAnchor" name="cumulative">Appenders accumulate
1302 </h4>
1303
1304 <p>By default, <b>appenders are cumulative</b>: a logger will log to
1305 the appenders attached to itself (if any) as well as all the
1306 appenders attached to its ancestors. Thus, attaching the same
1307 appender to multiple loggers will cause logging output to be
1308 duplicated.
1309 </p>
1310
1311 <p class="example">Example: Duplicate appender
1312 (logback-examples/src/main/resources/chapters/configuration/duplicate.xml)</p>
1313
1314 <span class="asGroovy" onclick="return asGroovy('duplicate');">View as .groovy</span>
1315 <pre id="duplicate" class="prettyprint source">&lt;configuration>
1316
1317 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
1318 &lt;encoder>
1319 &lt;pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n&lt;/pattern>
1320 &lt;/encoder>
1321 &lt;/appender>
1322
1323 &lt;logger name="chapters.configuration">
1324 &lt;appender-ref ref="STDOUT" />
1325 &lt;/logger>
1326
1327 &lt;root level="debug">
1328 &lt;appender-ref ref="STDOUT" />
1329 &lt;/root>
1330 &lt;/configuration></pre>
1331
1332 <p>Running <code>MyApp3</code> with <em>duplicate.xml</em> will
1333 yield the following output:
1334 </p>
1335
1336 <p class="source">14:25:36.343 [main] INFO chapters.configuration.MyApp3 - Entering application.
1337 14:25:36.343 [main] INFO chapters.configuration.MyApp3 - Entering application.
1338 14:25:36.359 [main] DEBUG chapters.configuration.Foo - Did it again!
1339 14:25:36.359 [main] DEBUG chapters.configuration.Foo - Did it again!
1340 14:25:36.359 [main] INFO chapters.configuration.MyApp3 - Exiting application.
1341 14:25:36.359 [main] INFO chapters.configuration.MyApp3 - Exiting application.</p>
1342
1343 <p>Notice the duplicated output. The appender named <em>STDOUT</em>
1344 is attached to two loggers, to root and to
1345 <em>chapters.configuration</em>. Since the root logger is the
1346 ancestor of all loggers and <em>chapters.configuration</em> is the
1347 parent of both <em>chapters.configuration.MyApp3</em> and
1348 <em>chapters.configuration.Foo</em>, each logging request made with
1349 these two loggers will be output twice, once because <em>STDOUT</em>
1350 is attached to <em>chapters.configuration</em> and once because it
1351 is attached to <em>root</em>.
1352 </p>
1353
1354 <p>Appender additivity is not intended as a trap for new users. It
1355 is quite a convenient logback feature. For instance, you can
1356 configure logging such that log messages appear on the console (for
1357 all loggers in the system) while messages only from some specific
1358 set of loggers flow into a specific appender.
1359 </p>
1360
1361 <p class="example">Example: Multiple appender
1362 (logback-examples/src/main/resources/chapters/configuration/restricted.xml)</p>
1363 <span class="asGroovy" onclick="return asGroovy('restricted');">View as .groovy</span>
1364 <pre id="restricted" class="prettyprint source">&lt;configuration>
1365
1366 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1367 &lt;file>myApp.log&lt;/file>
1368 &lt;encoder>
1369 &lt;pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n&lt;/pattern>
1370 &lt;/encoder>
1371 &lt;/appender>
1372
1373 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
1374 &lt;encoder>
1375 &lt;pattern>%msg%n&lt;/pattern>
1376 &lt;/encoder>
1377 &lt;/appender>
1378
1379 &lt;logger name="chapters.configuration">
1380 &lt;appender-ref ref="FILE" />
1381 &lt;/logger>
1382
1383 &lt;root level="debug">
1384 &lt;appender-ref ref="STDOUT" />
1385 &lt;/root>
1386 &lt;/configuration></pre>
1387
1388 <p>In this example, the console appender will log all the messages
1389 (for all loggers in the system) whereas only logging requests
1390 originating from the <em>chapters.configuration</em> logger and its
1391 children will go into the <em>myApp.log</em> file.
1392 </p>
1393
1394 <h4 class="doAnchor" name="overrridingCumulativity">Overriding the
1395 default cumulative behaviour</h4>
1396
1397 <p>In case the default cumulative behavior turns out to be
1398 unsuitable for your needs, you can override it by setting the
1399 additivity flag to false. Thus, a branch in your logger tree may
1400 direct output to a set of appenders different from those of the rest
1401 of the tree.
1402 </p>
1403
1404 <p class="example">Example: Additivity flag
1405 (logback-examples/src/main/resources/chapters/configuration/additivityFlag.xml)</p>
1406
1407 <span class="asGroovy" onclick="return asGroovy('additivityFlag');">View as .groovy</span>
1408 <pre id="additivityFlag" class="prettyprint source">&lt;configuration>
1409
1410 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1411 &lt;file>foo.log&lt;/file>
1412 &lt;encoder>
1413 &lt;pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n&lt;/pattern>
1414 &lt;/encoder>
1415 &lt;/appender>
1416
1417 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
1418 &lt;encoder>
1419 &lt;pattern>%msg%n&lt;/pattern>
1420 &lt;/encoder>
1421 &lt;/appender>
1422
1423 &lt;logger name="chapters.configuration.Foo" <b>additivity="false"</b>>
1424 &lt;appender-ref ref="FILE" />
1425 &lt;/logger>
1426
1427 &lt;root level="debug">
1428 &lt;appender-ref ref="STDOUT" />
1429 &lt;/root>
1430 &lt;/configuration></pre>
1431
1432 <p>This example, the appender named <em>FILE</em> is attached to the
1433 <em>chapters.configuration.Foo</em> logger. Moreover, the <em>chapters.configuration.Foo</em>
1434 logger has its additivity flag set to false such that its logging
1435 output will be sent to the appender named <em>FILE</em> but not to
1436 any appender attached higher in the hierarchy. Other loggers remain
1437 oblivious to the additivity setting of the <em>chapters.configuration.Foo</em>
1438 logger. Running the <code>MyApp3</code> application with the
1439 <em>additivityFlag.xml</em> configuration file will output results
1440 on the console from the <em>chapters.configuration.MyApp3</em> logger. However,
1441 output from the <em>chapters.configuration.Foo</em> logger will appear in the
1442 <em>foo.log</em> file and only in that file.
1443 </p>
1444
1445 <h3 class="doAnchor" name="contextName">Setting the context
1446 name</h3>
1447
1448 <p>As mentioned <a href="architecture.html#LoggerContext">in an
1449 earlier chapter</a>, every logger is attached to a logger
1450 context. By default, the logger context is called
1451 "default". However, you can set a different name with the help of
1452 the <code>&lt;contextName></code> configuration directive. Note that
1453 once set, the logger context name <a
1454 href="../apidocs/ch/qos/logback/core/ContextBase.html#setName(java.lang.String)">cannot
1455 be changed</a>. Setting the context name is a simple and
1456 straightforward method in order to distinguish between multiple
1457 applications logging to the same target.
1458 </p>
1459
1460 <p class="example">Example: Set the context name and display it
1461 (logback-examples/src/main/resources/chapters/configuration/contextName.xml)</p>
1462
1463 <span class="asGroovy" onclick="return asGroovy('contextName');">View as .groovy</span>
1464 <pre id="contextName" class="prettyprint source">&lt;configuration>
1465 <b>&lt;contextName>myAppName&lt;/contextName></b>
1466 &lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
1467 &lt;encoder>
1468 &lt;pattern>%d <b>%contextName</b> [%t] %level %logger{36} - %msg%n&lt;/pattern>
1469 &lt;/encoder>
1470 &lt;/appender>
1471
1472 &lt;root level="debug">
1473 &lt;appender-ref ref="STDOUT" />
1474 &lt;/root>
1475 &lt;/configuration></pre>
1476
1477 <p>This last example illustrates naming of the logger
1478 context. Adding the <a
1479 href="layouts.html#conversionWord">contextName conversion word</a>
1480 in layout's pattern will output the said name.</p>
1481
1482 <!-- =============================================================== -->
1483
1484 <h3 class="doAnchor" name="variableSubstitution">Variable
1485 substitution</h3>
1486
1487 <p><span class="label">Note</span> Earlier versions of this document
1488 used the term "property substitution" instead of the term
1489 "variable". Please consider both terms interchangeable although the
1490 latter term conveys a clearer meaning.
1491 </p>
1492
1493 <p>As in many scripting languages, logback configuration files
1494 support definition and substitution of variables. Variables have a
1495 <a href="#scopes">scope</a> (see below). Moreover, variables can be
1496 defined within the configuration file itself, in an external file,
1497 in an external resource or even computed and <a
1498 href="#definingPropsOnTheFly">defined on the fly</a>.
1499 </p>
1500
1501 <p class="highlight">Variable substitution can occur at any point in
1502 a configuration file where a value can be specified.</p>
1503
1504 <p>Variable substitution can occur at any point in a configuration
1505 file where a value can be specified. The syntax of variable
1506 substitution is similar to that of Unix shells. The string between
1507 an opening <em>${</em> and closing <em>}</em> is interpreted as a
1508 reference to the <em>value</em> of the property. For property
1509 <em>aName</em>, the string "${aName}" will be replaced with the
1510 value held by the <em>aName</em> property.
1511 </p>
1512
1513
1514
1515 <p>As they often come in handy, the HOSTNAME and CONTEXT_NAME
1516 variables are automatically defined and have context scope. Given
1517 that in some environments it may take some time to compute the
1518 hostname, its value is computed lazily (only when needed). Moreover,
1519 HOSTNAME can be set from within the <a
1520 href="#definingProps">configuration directly.</a>
1521 </p>
1522
1523 <h4 class="doAnchor" name="definingProps">Defining variables</h4>
1524
1525 <p>Variables can be defined one at a time in the configuration file
1526 itself or loaded wholesale from an external properties file or an
1527 external resource. For historical reasons, the XML element for
1528 defining variables is <code>&lt;property&gt;</code> although in
1529 logback 1.0.7 and later the element <code>&lt;variable></code> can
1530 be used interchangeably.</p>
1531
1532 <p>The next example shows a variable declared at the beginning of
1533 the configuration file. It is then used further down the file to
1534 specify the location of the output file.
1535 </p>
1536
1537 <p class="example">Example: Simple Variable substitution
1538 (logback-examples/src/main/resources/chapters/configuration/variableSubstitution1.xml)
1539 </p>
1540
1541 <span class="asGroovy" onclick="return asGroovy('variableSubstitution1');">View as .groovy</span>
1542 <pre id="variableSubstitution1" class="prettyprint source">&lt;configuration>
1543
1544 <b>&lt;property name="USER_HOME" value="/home/sebastien" /></b>
1545
1546 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1547 <b>&lt;file>${USER_HOME}/myApp.log&lt;/file></b>
1548 &lt;encoder>
1549 &lt;pattern>%msg%n&lt;/pattern>
1550 &lt;/encoder>
1551 &lt;/appender>
1552
1553 &lt;root level="debug">
1554 &lt;appender-ref ref="FILE" />
1555 &lt;/root>
1556 &lt;/configuration></pre>
1557
1558 <p>The next example shows the use of a System property to achieve
1559 the same result. The property is not declared in the configuration
1560 file, thus logback will look for it in the System properties. Java
1561 system properties can be set on the command line as shown next:
1562 </p>
1563
1564 <p class="source">java -DUSER_HOME="/home/sebastien" MyApp2</p>
1565
1566 <p class="example">Example: System Variable substitution
1567 (logback-examples/src/main/resources/chapters/configuration/variableSubstitution2.xml)
1568 </p>
1569 <span class="asGroovy" onclick="return asGroovy('variableSubstitution2');">View as .groovy</span>
1570 <pre id="variableSubstitution2" class="prettyprint source">&lt;configuration>
1571
1572 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1573 <b>&lt;file>${USER_HOME}/myApp.log&lt;/file></b>
1574 &lt;encoder>
1575 &lt;pattern>%msg%n&lt;/pattern>
1576 &lt;/encoder>
1577 &lt;/appender>
1578
1579 &lt;root level="debug">
1580 &lt;appender-ref ref="FILE" />
1581 &lt;/root>
1582 &lt;/configuration></pre>
1583
1584
1585 <p>When multiple variables are needed, it may be more convenient to
1586 create a separate file that will contain all the variables. Here is
1587 how one can do such a setup.
1588 </p>
1589
1590 <p class="example">Example: Variable substitution using a
1591 separate file
1592 (logback-examples/src/main/resources/chapters/configuration/variableSubstitution3.xml)
1593 </p>
1594 <span class="asGroovy" onclick="return asGroovy('variableSubstitution3');">View as .groovy</span>
1595 <pre id="variableSubstitution3" class="prettyprint source">&lt;configuration>
1596
1597 <b>&lt;property file="src/main/java/chapters/configuration/variables1.properties" /></b>
1598
1599 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1600 <b>&lt;file>${USER_HOME}/myApp.log&lt;/file></b>
1601 &lt;encoder>
1602 &lt;pattern>%msg%n&lt;/pattern>
1603 &lt;/encoder>
1604 &lt;/appender>
1605
1606 &lt;root level="debug">
1607 &lt;appender-ref ref="FILE" />
1608 &lt;/root>
1609 &lt;/configuration></pre>
1610
1611 <p>This configuration file contains a reference to a file named
1612 <em>variables1.properties</em>. The variables contained in that
1613 file will be read and then defined within local scope. Here is what
1614 the <em>variable.properties</em> file might look like.
1615 </p>
1616
1617 <em>Example: Variable file
1618 (logback-examples/src/main/resources/chapters/configuration/variables1.properties)</em>
1619
1620 <pre class="source">USER_HOME=/home/sebastien</pre>
1621
1622 <p>You may also reference a resource on the class path instead of a
1623 file.</p>
1624
1625 <pre class="prettyprint source">&lt;configuration>
1626
1627 <b>&lt;property resource="resource1.properties" /></b>
1628
1629 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1630 <b>&lt;file>${USER_HOME}/myApp.log&lt;/file></b>
1631 &lt;encoder>
1632 &lt;pattern>%msg%n&lt;/pattern>
1633 &lt;/encoder>
1634 &lt;/appender>
1635
1636 &lt;root level="debug">
1637 &lt;appender-ref ref="FILE" />
1638 &lt;/root>
1639 &lt;/configuration></pre>
1640
1641
1642 <h4 class="doAnchor" name="scopes">Scopes</h4>
1643
1644 <p>A property can be defined for insertion in <em>local scope</em>,
1645 in <em>context scope</em>, or in <em>system scope</em>. Local scope
1646 is the default. Although it is possible to read variables from the
1647 OS environment, it is not possible to write into the OS
1648 environment.</p>
1649
1650
1651 <p><span class="label">local scope</span> A property with local
1652 scope exists from the point of its definition in a configuration
1653 file until the end of interpretation/execution of said
1654 configuration file. As a corollary, each time a configuration file
1655 is parsed and executed, variables in local scope are defined
1656 anew.</p>
1657
1658 <p><span class="label">context scope</span> A property with context
1659 scope is inserted into the context and lasts as long as the context
1660 or until it is cleared. Once defined, a property in context scope
1661 is part of the context. As such, it is available in all logging
1662 events, including those sent to remote hosts via serialization.
1663 </p>
1664
1665 <p><span class="label">system scope</span> A property with system
1666 scope is inserted into the JVM's system properties and lasts as
1667 long as the JVM or until it is cleared.
1668 </p>
1669
1670 <p class="highlight">Properties are looked up in the the local
1671 scope first, in the context scope second, in the system properties
1672 scope third, and in the OS environment last.
1673 </p>
1674
1675 <p>During substitution, properties are looked up in the local scope
1676 first, in the context scope second, in the system properties scope
1677 third, and in the <a
1678 href="http://docs.oracle.com/javase/tutorial/essential/environment/env.html">OS
1679 environment</a> fourth and last.
1680 </p>
1681
1682 <p>The <span class="attr">scope</span> attribute of the
1683 <code>&lt;property></code> element, <code>&lt;define></code>
1684 element or the <code>&lt;insertFromJNDI></code> element can be used
1685 to set the scope of a property. The <span class="attr">scope</span>
1686 attribute admits "local", "context" and "system" strings as
1687 possible values. If not specified, the scope is always assumed to
1688 be "local".
1689 </p>
1690
1691 <p class="example">Example: A variable defined in "context" scope
1692 (logback-examples/src/main/resources/chapters/configuration/contextScopedVariable.xml)
1693 </p>
1694
1695 <span class="asGroovy" onclick="return
1696 asGroovy('contextScopedVariable');">View as .groovy</span>
1697 <pre id="contextScopedVariable" class="prettyprint source">&lt;configuration>
1698
1699 &lt;property <b class="big">scope="context"</b> name="nodeId" value="firstNode" />
1700
1701 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1702 <b>&lt;file>/opt/${nodeId}/myApp.log&lt;/file></b>
1703 &lt;encoder>
1704 &lt;pattern>%msg%n&lt;/pattern>
1705 &lt;/encoder>
1706 &lt;/appender>
1707
1708 &lt;root level="debug">
1709 &lt;appender-ref ref="FILE" />
1710 &lt;/root>
1711 &lt;/configuration></pre>
1712
1713 <p>In the above example, given that the <em>nodeId</em> property is
1714 defined in the context scope, it will be available in every logging
1715 event, even those sent to remote hosts via serialization.</p>
1716
1717
1718 <h3 class="doAnchor" name="defaultValuesForVariables">Default values
1719 for variables</h3>
1720
1721 <p>Under certain circumstances, it may be desirable for a variable
1722 to have a default value if it is not declared or its value is
1723 null. As in the <a
1724 href="http://tldp.org/LDP/abs/html/parameter-substitution.html">Bash
1725 shell</a>, default values can be specified using the <b>":-"</b>
1726 operator. For example, assuming the variable named <em>aName</em> is
1727 not defined, <code>"${aName<b>:-golden</b>}"</code> will be
1728 interpreted as "golden".</p>
1729
1730 <h3 class="doAnchor" name="nestedSubst">Nested variables</h3>
1731
1732 <p>Variable nesting is fully supported. Both the name,
1733 default-value and value definition of a variable can reference
1734 other variables.</p>
1735
1736
1737 <h4>value nesting</h4>
1738 <p>The value definition of a variable can contain references to
1739 other variables. Suppose you wish to use variables to specify not
1740 only the destination directory but also the file name, and combine
1741 those two variables in a third variable called "destination". The
1742 properties file shown below gives an example.
1743 </p>
1744
1745 <p class="example">Example: Nested variable references
1746 (logback-examples/src/main/resources/chapters/configuration/variables2.properties)</p>
1747
1748 <pre class="source">USER_HOME=/home/sebastien
1749 fileName=myApp.log
1750 <b>destination=${USER_HOME}/${fileName}</b></pre>
1751
1752 <p>Note that in the properties file above, "destination" is
1753 composed from two other variables, namely "USER_HOME" and
1754 "fileName".
1755 </p>
1756
1757 <em>Example: Variable substitution using
1758 a separate file
1759 (logback-examples/src/main/resources/chapters/configuration/variableSubstitution4.xml)</em>
1760
1761 <pre class="prettyprint source">&lt;configuration>
1762
1763 &lt;property file="variables2.properties" />
1764
1765 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1766 <b>&lt;file>${destination}&lt;/file></b>
1767 &lt;encoder>
1768 &lt;pattern>%msg%n&lt;/pattern>
1769 &lt;/encoder>
1770 &lt;/appender>
1771
1772 &lt;root level="debug">
1773 &lt;appender-ref ref="FILE" />
1774 &lt;/root>
1775 &lt;/configuration></pre>
1776
1777
1778 <h4>name nesting</h4>
1779
1780 <p>When referencing a variable, the variable name may contain a
1781 reference to another variable. For example, if the variable named
1782 "userid" is assigned the value "alice", then
1783 "${${userid}.password}" references the variable with the name
1784 "alice.password".</p>
1785
1786 <h4>default value nesting</h4>
1787
1788 <p>The default value of a variable can reference a another
1789 variable. For example, assuming the variable 'id' is unassigned
1790 and the variable 'userid' is assigned the value "alice", then the
1791 expression "${id<b>:-</b>${userid}}" will return "alice".
1792 </p>
1793
1794
1795 <!-- ==============================================================
1796 -->
1797 <h3 class="doAnchor" name="hostname">HOSTNAME property</h3>
1798
1799 <p>As it often comes in handy, the <code>HOSTNAME</code> property is
1800 defined automatically during configuration with context scope.</p>
1801
1802 <!-- ============================================================== -->
1803 <h3 class="doAnchor" name="context_name">CONTEXT_NAME property</h3>
1804
1805 <p>As its name indicates, the <code>CONTEXT_NAME</code> property
1806 corresponds to the name of the current logging context.</p>
1807
1808 <!-- ============================================================== -->
1809
1810 <h3 class="doAnchor" name="timestamp">Setting a timestamp</h3>
1811
1812 <p>The <em>timestamp</em> element can define a property according to
1813 current date and time. The <em>timestamp</em> element is <a
1814 href="appenders.html#uniquelyNamed">explained in a subsequent
1815 chapter</a>.</p>
1816
1817 <!-- ============================================================== -->
1818 <h3 class="doAnchor" name="definingPropsOnTheFly">Defining
1819 properties on the fly</h3>
1820
1821 <p>You may define properties dynamically using the
1822 <code>&lt;define></code> element. The define element takes two
1823 mandatory attributes: <span class="attr">name</span> and <span
1824 class="attr">class</span>. The <span class="attr">name</span>
1825 attribute designates the name of the property to set whereas the
1826 <span class="attr">class</span> attribute designates any class
1827 implementing the <a
1828 href="../xref/ch/qos/logback/core/spi/PropertyDefiner.html">PropertyDefiner</a>
1829 interface. The value returned by the <code>getPropertyValue</code>()
1830 method of the <code>PropertyDefiner</code> instance will be the
1831 value of the named property. You may also specify a <a
1832 href="#scopes">scope</a> for the named property by specifying a
1833 <span class="attr">scope</span> attribute.
1834 </p>
1835
1836 <p>Here is an example.</p>
1837
1838 <pre class="prettyprint source">&lt;configuration>
1839
1840 &lt;define name="rootLevel" class="a.class.implementing.PropertyDefiner">
1841 &lt;shape>round&lt;/shape>
1842 &lt;color>brown&lt;/color>
1843 &lt;size>24&lt;/size>
1844 &lt;/define>
1845
1846 &lt;root level="${rootLevel}"/>
1847 &lt;/configuration></pre>
1848
1849 <p>In the above example, shape, color and size are properties of
1850 "a.class.implementing.PropertyDefiner". As long as there is a setter
1851 for a given property in your implementation of the
1852 <code>PropertyDefiner</code> instance, logback will inject the
1853 appropriate values as specified in the configuration file. </p>
1854
1855
1856
1857 <p>At the present time, logback does ships with two fairly simple
1858 implementations of <code>PropertyDefiner</code>.
1859 </p>
1860
1861 <table class="bodyTable striped">
1862 <tr>
1863 <th>Implementation name</th>
1864 <th>Description</th>
1865 </tr>
1866
1867 <tr>
1868 <td><a
1869 href="../apidocs/ch/qos/logback/core/property/FileExistsPropertyDefiner.html"><code>FileExistsPropertyDefiner</code></a>
1870 </td>
1871 <td>Set the named variable to "true" if the file specified by
1872 <span class="prop">path</span> property exists, to "false"
1873 otherwise.
1874 </td>
1875 </tr>
1876 <tr>
1877 <td><a
1878 href="../apidocs/ch/qos/logback/core/property/FileExistsPropertyDefiner.html"><code>ResourceExistsPropertyDefiner</code></a>
1879 </td>
1880 <td>Set the named variable to "true" if the <span
1881 class="prop">resource</span> specified by the user is available
1882 on the class path, to "false" otherwise.
1883 </td>
1884 </tr>
1885 </table>
1886
1887 <!-- ============================================================== -->
1888
1889 <h3 class="doAnchor" name="conditional">Conditional processing of
1890 configuration files</h3>
1891
1892 <p>Developers often need to juggle between several logback
1893 configuration files targeting different environments such as
1894 development, testing and production. These configuration files have
1895 substantial parts in common differing only in a few places. To avoid
1896 duplication, logback supports conditional processing of
1897 configuration files with the help of <code>&lt;if></code>,
1898 <code>&lt;then></code> and <code>&lt;else></code> elements so that a
1899 single configuration file can adequately target several
1900 environments. Note that conditional processing requires the <a
1901 href="../setup.html#janino">Janino library</a>.
1902 </p>
1903
1904 <p>The general format for conditional statements is shown below.</p>
1905
1906 <pre class="prettyprint source">
1907 &lt;!-- if-then form -->
1908 &lt;if condition="some conditional expression">
1909 &lt;then>
1910 ...
1911 &lt;/then>
1912 &lt;/if>
1913
1914 &lt;!-- if-then-else form -->
1915 &lt;if condition="some conditional expression">
1916 &lt;then>
1917 ...
1918 &lt;/then>
1919 &lt;else>
1920 ...
1921 &lt;/else>
1922 &lt;/if></pre>
1923
1924 <p>The condition is a Java expression in which only context
1925 properties or system properties are accessible. For a key passed as
1926 argument, the <code>property</code>() or its shorter equivalent
1927 <code>p</code>() methods return the String value of the property.
1928 For example, to access the value of a property with key "k", you
1929 would write <code>property("k")</code> or equivalently
1930 <code>p("k")</code>. If the property with key "k" is undefined, the
1931 property method will return the empty string and not null. This
1932 avoids the need to check for null values.</p>
1933
1934 <p>The <code>isDefined()</code> method can be used to check whether
1935 a property is defined. For example, to check whether the property
1936 "k" is defined you would write <code>isDefined("k")</code>
1937 Similarly, if you need to check whether a property is null, the
1938 <code>isNull()</code> method is provided. Example:
1939 <code>isNull("k")</code>.</p>
1940
1941 <pre class="prettyprint source">&lt;configuration debug="true">
1942
1943 <b>&lt;if condition='property("HOSTNAME").contains("torino")'></b>
1944 <b>&lt;then></b>
1945 &lt;appender name="CON" class="ch.qos.logback.core.ConsoleAppender">
1946 &lt;encoder>
1947 &lt;pattern>%d %-5level %logger{35} - %msg %n&lt;/pattern>
1948 &lt;/encoder>
1949 &lt;/appender>
1950 &lt;root>
1951 &lt;appender-ref ref="CON" />
1952 &lt;/root>
1953 <b>&lt;/then></b>
1954 <b>&lt;/if></b>
1955
1956 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
1957 &lt;file>${randomOutputDir}/conditional.log&lt;/file>
1958 &lt;encoder>
1959 &lt;pattern>%d %-5level %logger{35} - %msg %n&lt;/pattern>
1960 &lt;/encoder>
1961 &lt;/appender>
1962
1963 &lt;root level="ERROR">
1964 &lt;appender-ref ref="FILE" />
1965 &lt;/root>
1966 &lt;/configuration></pre>
1967
1968
1969 <p>Conditional processing is supported <em>anywhere</em> within the
1970 <code>&lt;configuration></code> element. Nested if-then-else
1971 statements are also supported. However, XML syntax is awfully
1972 cumbersome and is ill suited as the foundation of a general purpose
1973 programming language. Consequently, too many conditionals will
1974 quickly render your configuration files incomprehensible to subsequent
1975 readers, including yourself.
1976 </p>
1977
1978
1979 <!-- ============================================================== -->
1980
1981 <h3 class="doAnchor" name="insertFromJNDI">Obtaining variables from
1982 JNDI</h3>
1983
1984 <p>Under certain circumstances, you may want to make use of
1985 env-entries stored in JNDI. The <code>&lt;insertFromJNDI></code>
1986 configuration directive extracts an env-entry stored in JNDI and
1987 inserts the property in local scope with key specified by the <span
1988 class="attr">as</span> attribute. As all properties, it is possible
1989 to insert the new property into a <a href="#scopes">different
1990 scope</a> with the help of the <em>scope</em> attribute.
1991 </p>
1992
1993 <p class="example">Example: Insert as properties env-entries
1994 obtained via JNDI
1995 (logback-examples/src/main/resources/chapters/configuration/insertFromJNDI.xml)</p>
1996
1997 <pre class="prettyprint source">&lt;configuration>
1998 <b>&lt;insertFromJNDI env-entry-name="java:comp/env/appName" as="<span class="green">appName"</span> /></b>
1999 <b>&lt;contextName><span class="green">${appName}</span>&lt;/contextName></b>
2000
2001 &lt;appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
2002 &lt;encoder>
2003 &lt;pattern>%d ${CONTEXT_NAME} %level %msg %logger{50}%n&lt;/pattern>
2004 &lt;/encoder>
2005 &lt;/appender>
2006
2007 &lt;root level="DEBUG">
2008 &lt;appender-ref ref="CONSOLE" />
2009 &lt;/root>
2010 &lt;/configuration></pre>
2011
2012 <p>In this last example, the "java:comp/env/appName" env-entry is
2013 inserted as the <span class="variable">appName</span> property. Note
2014 that the <code>&lt;contextName></code> directive sets the context
2015 name based on the value of the <span class="variable">appName</span>
2016 property inserted by the previous <code>&lt;insertFromJNDI></code>
2017 directive.
2018 </p>
2019
2020 <h3 class="doAnchor" name="fileInclusion">File inclusion</h3>
2021
2022 <p>Joran supports including parts of a configuration file from
2023 another file. This is done by declaring a <code>&lt;include></code>
2024 element, as shown below:
2025 </p>
2026
2027 <p class="example">Example: File include
2028 (logback-examples/src/main/resources/chapters/configuration/containingConfig.xml)</p>
2029
2030 <pre class="prettyprint source">&lt;configuration>
2031 <b>&lt;include file="src/main/java/chapters/configuration/includedConfig.xml"/></b>
2032
2033 &lt;root level="DEBUG">
2034 &lt;appender-ref ref="includedConsole" />
2035 &lt;/root>
2036
2037 &lt;/configuration></pre>
2038
2039 <p>The target file MUST have its elements nested inside an
2040 <code>&lt;included></code> element. For example, a
2041 <code>ConsoleAppender</code> could be declared as:
2042 </p>
2043
2044 <p class="example">Example: File include
2045 (logback-examples/src/main/resources/chapters/configuration/includedConfig.xml)</p>
2046
2047 <pre class="source"><b class="green big">&lt;included></b>
2048 &lt;appender name="includedConsole" class="ch.qos.logback.core.ConsoleAppender">
2049 &lt;encoder>
2050 &lt;pattern>"%d - %m%n"&lt;/pattern>
2051 &lt;/encoder>
2052 &lt;/appender>
2053 <b class="green big">&lt;/included></b></pre>
2054
2055
2056 <p>Again, please note the mandatory
2057 <code class="big green">&lt;included></code> element.</p>
2058
2059 <p>The contents to include can be referenced as a file, as a
2060 resource, or as a URL.</p>
2061
2062 <ul>
2063
2064 <li><b>As a file:</b><br/> To include a file use the <span
2065 class="attr">file</span> attribute. You can use relative paths but
2066 note that the current directory is defined by the application and
2067 is not necessarily related to the path of the configuration
2068 file.</li>
2069
2070 <li><p><b>As a resource:</b><br/> To include a resource, i.e a
2071 file found on the class path, use the <span
2072 class="attr">resource</span> attribute.</p>
2073
2074 <pre class="prettyprint source">&lt;include resource="includedConfig.xml"/></pre>
2075
2076 </li>
2077
2078 <li><p><b>As a URL:</b><br/> To include the contents of a URL use
2079 the <span class="attr">url</span> attribute.</p>
2080
2081 <pre class="prettyprint source">&lt;include url="http://some.host.com/includedConfig.xml"/></pre>
2082
2083 </li>
2084 </ul>
2085
2086 <p>If it cannot find the file to be included, logback will complain
2087 by printing a status message. In case the included file is
2088 optional, you can suppress the warning message by setting <span
2089 class="attr">optional</span> attribute to <code>true</code> in the
2090 <code>&lt;include></code> element.</p>
2091
2092
2093 <pre class="prettyprint source">&lt;include optional="true" ..../></pre>
2094
2095 <!-- ==================== ContextListener =================== -->
2096 <h2 class="doAnchor" name="contextListener">Adding a context
2097 listener</h2>
2098
2099 <p>Instances of the <a
2100 href="../xref/ch/qos/logback/classic/spi/LoggerContextListener.html">LoggerContextListener</a>
2101 interface listen to events pertaining to the lifecycle of a logger
2102 context.
2103 </p>
2104
2105
2106 <p><code>JMXConfigurator</code> is one implementation of the
2107 <code>LoggerContextListener</code> interface. It is described in a <a
2108 href="jmxConfig.html">subsequent chapter</a>.
2109 </p>
2110
2111 <h3 class="doAnchor"
2112 name="LevelChangePropagator">LevelChangePropagator</h3>
2113
2114 <p>As of version 0.9.25, logback-classic ships with <a
2115 href="../xref/ch/qos/logback/classic/jul/LevelChangePropagator.html">LevelChangePropagator</a>,
2116 an implementation of <code>LoggerContextListener</code> which
2117 propagates changes made to the level of any logback-classic logger
2118 onto the java.util.logging framework. Such propagation eliminates
2119 the performance impact of disabled log statements. Instances of <a
2120 href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/logging/LogRecord.html?is-external=true">LogRecord</a>
2121 will be sent to logback (via SLF4J) only for enabled log
2122 statements. This makes it reasonable for real-world applications to
2123 use the <a
2124 href="http://www.slf4j.org/legacy.html#jul-to-slf4j">jul-to-slf4j</a>
2125 bridge.
2126 </p>
2127
2128
2129 <p>The contextListener element can be used to install <code>LevelChangePropagator</code> as shown next.</p>
2130
2131 <pre class="prettyprint source">&lt;configuration debug="true">
2132 <b>&lt;contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/></b>
2133 ....
2134 &lt;/configuration></pre>
2135
2136 <p>Setting the <span class="option">resetJUL</span> property of
2137 LevelChangePropagator will reset all previous level configurations
2138 of all j.u.l. loggers. However, previously installed handlers will be
2139 left untouched.</p>
2140
2141 <pre class="prettyprint source">&lt;configuration debug="true">
2142 &lt;contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator">
2143 <b>&lt;resetJUL>true&lt;/resetJUL></b>
2144 &lt;/contextListener>
2145 ....
2146 &lt;/configuration></pre>
2147 <p>
2148 </p>
2149
2150
2151 <script src="../templates/footer.js" type="text/javascript"></script>
2152 </div>
2153 </body>
2154 </html>