| 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">和訳 (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>—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} [%thread] %-5level %logger{36} - %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"><configuration> |
| 267 |
|
| 268 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 269 |
<!-- encoders are assigned the type |
| 270 |
ch.qos.logback.classic.encoder.PatternLayoutEncoder by default --> |
| 271 |
<encoder> |
| 272 |
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
| 273 |
</encoder> |
| 274 |
</appender> |
| 275 |
|
| 276 |
<root level="debug"> |
| 277 |
<appender-ref ref="STDOUT" /> |
| 278 |
</root> |
| 279 |
</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 |
<configuration <span class="big bold">debug="true"</span>> |
| 368 |
|
| 369 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 370 |
<!-- encoders are by default assigned the type |
| 371 |
ch.qos.logback.classic.encoder.PatternLayoutEncoder --> |
| 372 |
<encoder> |
| 373 |
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
| 374 |
</encoder> |
| 375 |
</appender> |
| 376 |
|
| 377 |
<root level="debug"> |
| 378 |
<appender-ref ref="STDOUT" /> |
| 379 |
</root> |
| 380 |
</configuration></pre> |
| 381 |
|
| 382 |
<p>Setting <code>debug="true"</code> within the |
| 383 |
<configuration> 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"><configuration> |
| 428 |
<b><statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /></b> |
| 429 |
|
| 430 |
... the rest of the configuration file |
| 431 |
</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><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 |
<configuration <b>scan="true"</b>> |
| 484 |
... |
| 485 |
</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><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 |
<configuration scan="true" <b>scanPeriod="30 seconds"</b> > |
| 500 |
... |
| 501 |
</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 (= 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 |
<configuration <span class="big bold">packagingData="true"</span>> |
| 583 |
... |
| 584 |
</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"> <servlet> |
| 690 |
<servlet-name>ViewStatusMessages</servlet-name> |
| 691 |
<servlet-class>ch.qos.logback.classic.ViewStatusMessagesServlet</servlet-class> |
| 692 |
</servlet> |
| 693 |
|
| 694 |
<servlet-mapping> |
| 695 |
<servlet-name>ViewStatusMessages</servlet-name> |
| 696 |
<url-pattern>/lbClassicStatus</url-pattern> |
| 697 |
</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"><configuration> |
| 746 |
<b><statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" /></b> |
| 747 |
|
| 748 |
... the rest of the configuration file |
| 749 |
</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 ...</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 ...</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"><configuration debug="true"> |
| 818 |
<!-- in the absence of the class attribute, assume |
| 819 |
ch.qos.logback.core.hook.DelayingShutdownHook --> |
| 820 |
<b><shutdownHook/></b> |
| 821 |
.... |
| 822 |
</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 |
<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"><web-app> |
| 853 |
<context-param> |
| 854 |
<param-name>logbackDisableServletContainerInitializer</param-name> |
| 855 |
<param-value>true</param-value> |
| 856 |
</context-param> |
| 857 |
.... |
| 858 |
</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><configuration></code> element, |
| 893 |
containing zero or more <code><appender></code> elements, |
| 894 |
followed by zero or more <code><logger></code> elements, |
| 895 |
followed by at most one <code><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><logger></code>, <code><Logger></code> and |
| 915 |
<code><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><xyz></code> you |
| 918 |
must close it as <code></xyz></code>, <code></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><xyz></code> and <code><Xyz></code> are |
| 922 |
equivalent but not <code><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><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><logger></code> |
| 945 |
element. A <code><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><logger></code> element may contain zero or more |
| 965 |
<code><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><root></code> element</h4> |
| 975 |
|
| 976 |
<p>The <code><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><logger></code> element, the |
| 992 |
<code><root></code> element may contain zero or more |
| 993 |
<code><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"><configuration> |
| 1013 |
|
| 1014 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 1015 |
<!-- encoders are assigned the type |
| 1016 |
ch.qos.logback.classic.encoder.PatternLayoutEncoder by default --> |
| 1017 |
<encoder> |
| 1018 |
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
| 1019 |
</encoder> |
| 1020 |
</appender> |
| 1021 |
|
| 1022 |
<b><logger name="chapters.configuration" level="INFO"/></b> |
| 1023 |
|
| 1024 |
<!-- Strictly speaking, the level attribute is not necessary since --> |
| 1025 |
<!-- the level of the root level is set to DEBUG by default. --> |
| 1026 |
<root level="DEBUG"> |
| 1027 |
<appender-ref ref="STDOUT" /> |
| 1028 |
</root> |
| 1029 |
|
| 1030 |
</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"><configuration> |
| 1054 |
|
| 1055 |
<appender name="STDOUT" |
| 1056 |
class="ch.qos.logback.core.ConsoleAppender"> |
| 1057 |
<encoder> |
| 1058 |
<pattern> |
| 1059 |
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n |
| 1060 |
</pattern> |
| 1061 |
</encoder> |
| 1062 |
</appender> |
| 1063 |
|
| 1064 |
<b><logger name="chapters.configuration" level="INFO" /></b> |
| 1065 |
<b><logger name="chapters.configuration.Foo" level="DEBUG" /></b> |
| 1066 |
|
| 1067 |
<root level="DEBUG"> |
| 1068 |
<appender-ref ref="STDOUT" /> |
| 1069 |
</root> |
| 1070 |
|
| 1071 |
</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"><configuration> |
| 1135 |
|
| 1136 |
<appender name="STDOUT" |
| 1137 |
class="ch.qos.logback.core.ConsoleAppender"> |
| 1138 |
<encoder> |
| 1139 |
<pattern> |
| 1140 |
%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n |
| 1141 |
</pattern> |
| 1142 |
</encoder> |
| 1143 |
</appender> |
| 1144 |
|
| 1145 |
<b><logger name="chapters.configuration" level="INFO" /></b> |
| 1146 |
|
| 1147 |
<!-- turn OFF all logging (children can override) --> |
| 1148 |
<root <b>level="OFF"</b>> |
| 1149 |
<appender-ref ref="STDOUT" /> |
| 1150 |
</root> |
| 1151 |
|
| 1152 |
</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><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><appender></code> element may contain zero |
| 1214 |
or one <code><layout></code> elements, zero or more |
| 1215 |
<code><encoder></code> elements and zero or more |
| 1216 |
<code><filter></code> elements. Apart from these three common |
| 1217 |
elements, <code><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><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><appender></code> element, |
| 1234 |
<code><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><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"><configuration> |
| 1261 |
|
| 1262 |
<appender name="<b>FILE</b>" class="ch.qos.logback.core.FileAppender"> |
| 1263 |
<file>myApp.log</file> |
| 1264 |
|
| 1265 |
<encoder> |
| 1266 |
<pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern> |
| 1267 |
</encoder> |
| 1268 |
</appender> |
| 1269 |
|
| 1270 |
<appender name="<b>STDOUT</b>" class="ch.qos.logback.core.ConsoleAppender"> |
| 1271 |
<encoder> |
| 1272 |
<pattern>%msg%n</pattern> |
| 1273 |
</encoder> |
| 1274 |
</appender> |
| 1275 |
|
| 1276 |
<root level="debug"> |
| 1277 |
<b><appender-ref ref="FILE" /></b> |
| 1278 |
<b><appender-ref ref="STDOUT" /></b> |
| 1279 |
</root> |
| 1280 |
</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"><configuration> |
| 1316 |
|
| 1317 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 1318 |
<encoder> |
| 1319 |
<pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern> |
| 1320 |
</encoder> |
| 1321 |
</appender> |
| 1322 |
|
| 1323 |
<logger name="chapters.configuration"> |
| 1324 |
<appender-ref ref="STDOUT" /> |
| 1325 |
</logger> |
| 1326 |
|
| 1327 |
<root level="debug"> |
| 1328 |
<appender-ref ref="STDOUT" /> |
| 1329 |
</root> |
| 1330 |
</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"><configuration> |
| 1365 |
|
| 1366 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1367 |
<file>myApp.log</file> |
| 1368 |
<encoder> |
| 1369 |
<pattern>%date %level [%thread] %logger{10} [%file:%line] %msg%n</pattern> |
| 1370 |
</encoder> |
| 1371 |
</appender> |
| 1372 |
|
| 1373 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 1374 |
<encoder> |
| 1375 |
<pattern>%msg%n</pattern> |
| 1376 |
</encoder> |
| 1377 |
</appender> |
| 1378 |
|
| 1379 |
<logger name="chapters.configuration"> |
| 1380 |
<appender-ref ref="FILE" /> |
| 1381 |
</logger> |
| 1382 |
|
| 1383 |
<root level="debug"> |
| 1384 |
<appender-ref ref="STDOUT" /> |
| 1385 |
</root> |
| 1386 |
</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"><configuration> |
| 1409 |
|
| 1410 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1411 |
<file>foo.log</file> |
| 1412 |
<encoder> |
| 1413 |
<pattern>%date %level [%thread] %logger{10} [%file : %line] %msg%n</pattern> |
| 1414 |
</encoder> |
| 1415 |
</appender> |
| 1416 |
|
| 1417 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 1418 |
<encoder> |
| 1419 |
<pattern>%msg%n</pattern> |
| 1420 |
</encoder> |
| 1421 |
</appender> |
| 1422 |
|
| 1423 |
<logger name="chapters.configuration.Foo" <b>additivity="false"</b>> |
| 1424 |
<appender-ref ref="FILE" /> |
| 1425 |
</logger> |
| 1426 |
|
| 1427 |
<root level="debug"> |
| 1428 |
<appender-ref ref="STDOUT" /> |
| 1429 |
</root> |
| 1430 |
</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><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"><configuration> |
| 1465 |
<b><contextName>myAppName</contextName></b> |
| 1466 |
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> |
| 1467 |
<encoder> |
| 1468 |
<pattern>%d <b>%contextName</b> [%t] %level %logger{36} - %msg%n</pattern> |
| 1469 |
</encoder> |
| 1470 |
</appender> |
| 1471 |
|
| 1472 |
<root level="debug"> |
| 1473 |
<appender-ref ref="STDOUT" /> |
| 1474 |
</root> |
| 1475 |
</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><property></code> although in |
| 1529 |
logback 1.0.7 and later the element <code><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"><configuration> |
| 1543 |
|
| 1544 |
<b><property name="USER_HOME" value="/home/sebastien" /></b> |
| 1545 |
|
| 1546 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1547 |
<b><file>${USER_HOME}/myApp.log</file></b> |
| 1548 |
<encoder> |
| 1549 |
<pattern>%msg%n</pattern> |
| 1550 |
</encoder> |
| 1551 |
</appender> |
| 1552 |
|
| 1553 |
<root level="debug"> |
| 1554 |
<appender-ref ref="FILE" /> |
| 1555 |
</root> |
| 1556 |
</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"><configuration> |
| 1571 |
|
| 1572 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1573 |
<b><file>${USER_HOME}/myApp.log</file></b> |
| 1574 |
<encoder> |
| 1575 |
<pattern>%msg%n</pattern> |
| 1576 |
</encoder> |
| 1577 |
</appender> |
| 1578 |
|
| 1579 |
<root level="debug"> |
| 1580 |
<appender-ref ref="FILE" /> |
| 1581 |
</root> |
| 1582 |
</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"><configuration> |
| 1596 |
|
| 1597 |
<b><property file="src/main/java/chapters/configuration/variables1.properties" /></b> |
| 1598 |
|
| 1599 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1600 |
<b><file>${USER_HOME}/myApp.log</file></b> |
| 1601 |
<encoder> |
| 1602 |
<pattern>%msg%n</pattern> |
| 1603 |
</encoder> |
| 1604 |
</appender> |
| 1605 |
|
| 1606 |
<root level="debug"> |
| 1607 |
<appender-ref ref="FILE" /> |
| 1608 |
</root> |
| 1609 |
</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"><configuration> |
| 1626 |
|
| 1627 |
<b><property resource="resource1.properties" /></b> |
| 1628 |
|
| 1629 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1630 |
<b><file>${USER_HOME}/myApp.log</file></b> |
| 1631 |
<encoder> |
| 1632 |
<pattern>%msg%n</pattern> |
| 1633 |
</encoder> |
| 1634 |
</appender> |
| 1635 |
|
| 1636 |
<root level="debug"> |
| 1637 |
<appender-ref ref="FILE" /> |
| 1638 |
</root> |
| 1639 |
</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><property></code> element, <code><define></code> |
| 1684 |
element or the <code><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"><configuration> |
| 1698 |
|
| 1699 |
<property <b class="big">scope="context"</b> name="nodeId" value="firstNode" /> |
| 1700 |
|
| 1701 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1702 |
<b><file>/opt/${nodeId}/myApp.log</file></b> |
| 1703 |
<encoder> |
| 1704 |
<pattern>%msg%n</pattern> |
| 1705 |
</encoder> |
| 1706 |
</appender> |
| 1707 |
|
| 1708 |
<root level="debug"> |
| 1709 |
<appender-ref ref="FILE" /> |
| 1710 |
</root> |
| 1711 |
</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"><configuration> |
| 1762 |
|
| 1763 |
<property file="variables2.properties" /> |
| 1764 |
|
| 1765 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1766 |
<b><file>${destination}</file></b> |
| 1767 |
<encoder> |
| 1768 |
<pattern>%msg%n</pattern> |
| 1769 |
</encoder> |
| 1770 |
</appender> |
| 1771 |
|
| 1772 |
<root level="debug"> |
| 1773 |
<appender-ref ref="FILE" /> |
| 1774 |
</root> |
| 1775 |
</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><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"><configuration> |
| 1839 |
|
| 1840 |
<define name="rootLevel" class="a.class.implementing.PropertyDefiner"> |
| 1841 |
<shape>round</shape> |
| 1842 |
<color>brown</color> |
| 1843 |
<size>24</size> |
| 1844 |
</define> |
| 1845 |
|
| 1846 |
<root level="${rootLevel}"/> |
| 1847 |
</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><if></code>, |
| 1898 |
<code><then></code> and <code><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 |
<!-- if-then form --> |
| 1908 |
<if condition="some conditional expression"> |
| 1909 |
<then> |
| 1910 |
... |
| 1911 |
</then> |
| 1912 |
</if> |
| 1913 |
|
| 1914 |
<!-- if-then-else form --> |
| 1915 |
<if condition="some conditional expression"> |
| 1916 |
<then> |
| 1917 |
... |
| 1918 |
</then> |
| 1919 |
<else> |
| 1920 |
... |
| 1921 |
</else> |
| 1922 |
</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"><configuration debug="true"> |
| 1942 |
|
| 1943 |
<b><if condition='property("HOSTNAME").contains("torino")'></b> |
| 1944 |
<b><then></b> |
| 1945 |
<appender name="CON" class="ch.qos.logback.core.ConsoleAppender"> |
| 1946 |
<encoder> |
| 1947 |
<pattern>%d %-5level %logger{35} - %msg %n</pattern> |
| 1948 |
</encoder> |
| 1949 |
</appender> |
| 1950 |
<root> |
| 1951 |
<appender-ref ref="CON" /> |
| 1952 |
</root> |
| 1953 |
<b></then></b> |
| 1954 |
<b></if></b> |
| 1955 |
|
| 1956 |
<appender name="FILE" class="ch.qos.logback.core.FileAppender"> |
| 1957 |
<file>${randomOutputDir}/conditional.log</file> |
| 1958 |
<encoder> |
| 1959 |
<pattern>%d %-5level %logger{35} - %msg %n</pattern> |
| 1960 |
</encoder> |
| 1961 |
</appender> |
| 1962 |
|
| 1963 |
<root level="ERROR"> |
| 1964 |
<appender-ref ref="FILE" /> |
| 1965 |
</root> |
| 1966 |
</configuration></pre> |
| 1967 |
|
| 1968 |
|
| 1969 |
<p>Conditional processing is supported <em>anywhere</em> within the |
| 1970 |
<code><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><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"><configuration> |
| 1998 |
<b><insertFromJNDI env-entry-name="java:comp/env/appName" as="<span class="green">appName"</span> /></b> |
| 1999 |
<b><contextName><span class="green">${appName}</span></contextName></b> |
| 2000 |
|
| 2001 |
<appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> |
| 2002 |
<encoder> |
| 2003 |
<pattern>%d ${CONTEXT_NAME} %level %msg %logger{50}%n</pattern> |
| 2004 |
</encoder> |
| 2005 |
</appender> |
| 2006 |
|
| 2007 |
<root level="DEBUG"> |
| 2008 |
<appender-ref ref="CONSOLE" /> |
| 2009 |
</root> |
| 2010 |
</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><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><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><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"><configuration> |
| 2031 |
<b><include file="src/main/java/chapters/configuration/includedConfig.xml"/></b> |
| 2032 |
|
| 2033 |
<root level="DEBUG"> |
| 2034 |
<appender-ref ref="includedConsole" /> |
| 2035 |
</root> |
| 2036 |
|
| 2037 |
</configuration></pre> |
| 2038 |
|
| 2039 |
<p>The target file MUST have its elements nested inside an |
| 2040 |
<code><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"><included></b> |
| 2048 |
<appender name="includedConsole" class="ch.qos.logback.core.ConsoleAppender"> |
| 2049 |
<encoder> |
| 2050 |
<pattern>"%d - %m%n"</pattern> |
| 2051 |
</encoder> |
| 2052 |
</appender> |
| 2053 |
<b class="green big"></included></b></pre> |
| 2054 |
|
| 2055 |
|
| 2056 |
<p>Again, please note the mandatory |
| 2057 |
<code class="big green"><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"><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"><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><include></code> element.</p> |
| 2091 |
|
| 2092 |
|
| 2093 |
<pre class="prettyprint source"><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"><configuration debug="true"> |
| 2132 |
<b><contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/></b> |
| 2133 |
.... |
| 2134 |
</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"><configuration debug="true"> |
| 2142 |
<contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"> |
| 2143 |
<b><resetJUL>true</resetJUL></b> |
| 2144 |
</contextListener> |
| 2145 |
.... |
| 2146 |
</configuration></pre> |
| 2147 |
<p> |
| 2148 |
</p> |
| 2149 |
|
| 2150 |
|
| 2151 |
<script src="../templates/footer.js" type="text/javascript"></script> |
| 2152 |
</div> |
| 2153 |
</body> |
| 2154 |
</html> |