Debian Codegraph @

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

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml">
4 <head>
5 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
6 <title>Chapter 4: Appenders</title>
7 <link rel="stylesheet" type="text/css" href="../css/common.css" />
8 <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" />
9 <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" />
10 <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen"/>
11 </head>
12 <body onload="prettyPrint(); decorate();">
13 <script type="text/javascript">prefix='../';</script>
14 <script type="text/javascript" src="../js/prettify.js"></script>
15 <script type="text/javascript" src="../templates/header.js"></script>
16 <script type="text/javascript" src="../js/dsl.js"></script>
17 <script type="text/javascript" src="../js/jquery-min.js"></script>
18 <script type="text/javascript" src="../js/decorator.js"></script>
19 <div id="left">
20 <noscript>Please turn on Javascript to view this menu</noscript>
21 <script src="../templates/left.js" type="text/javascript"></script>
22 </div>
23 <div id="right">
24 <script src="menu.js" type="text/javascript"></script>
25 </div>
26
27 <div id="content">
28
29 <h1>Chapter 4: Appenders</h1>
30
31 <a href="appenders_ja.html">&#x548C;&#x8A33; (Japanese translation)</a>
32
33
34 <div class="quote">
35
36 <p><em>There is so much to tell about the Western country in
37 that day that it is hard to know where to start. One thing sets
38 off a hundred others. The problem is to decide which one to tell
39 first.</em></p>
40
41 <p>&mdash;JOHN STEINBECK, <em>East of Eden</em></p>
42 </div>
43
44
45 <script src="../templates/creative.js" type="text/javascript"></script>
46 <script src="../templates/setup.js" type="text/javascript"></script>
47
48 <h2 class="doAnchor" name="whatIsAnAppender">What is an Appender?</h2>
49
50 <p>Logback delegates the task of writing a logging event to
51 components called appenders. Appenders must implement the <a
52 href="../xref/ch/qos/logback/core/Appender.html"><code>ch.qos.logback.core.Appender</code></a>
53 interface. The salient methods of this interface are summarized
54 below:
55 </p>
56 <pre class="prettyprint source">package ch.qos.logback.core;
57
58 import ch.qos.logback.core.spi.ContextAware;
59 import ch.qos.logback.core.spi.FilterAttachable;
60 import ch.qos.logback.core.spi.LifeCycle;
61
62
63 public interface Appender&lt;E> extends LifeCycle, ContextAware, FilterAttachable {
64
65 public String getName();
66 public void setName(String name);
67 <b>void doAppend(E event);</b>
68
69 }</pre>
70
71 <p>Most of the methods in the <code>Appender</code> interface are
72 setters and getters. A notable exception is the
73 <code>doAppend()</code> method taking an object instance of type
74 <em>E</em> as its only parameter. The actual type of <em>E</em>
75 will vary depending on the logback module. Within the
76 logback-classic module <em>E</em> would be of type <a
77 href="../apidocs/ch/qos/logback/classic/spi/ILoggingEvent.html">ILoggingEvent</a>
78 and within the logback-access module it would be of type <a
79 href="../apidocs/ch/qos/logback/access/spi/AccessEvent.html">AccessEvent</a>.
80 The <code>doAppend()</code> method is perhaps the most important in
81 the logback framework. It is responsible for outputting the logging
82 events in a suitable format to the appropriate output device.
83 </p>
84
85 <p>Appenders are named entities. This ensures that they can be
86 referenced by name, a quality confirmed to be instrumental in
87 configuration scripts. The <code>Appender</code> interface extends
88 the <code>FilterAttachable</code> interface. It follows that one or
89 more filters can be attached to an appender instance. Filters are
90 discussed in detail in a subsequent chapter.
91 </p>
92
93 <p>Appenders are ultimately responsible for outputting logging
94 events. However, they may delegate the actual formatting of the
95 event to a <code>Layout</code> or to an <code>Encoder</code> object.
96 Each layout/encoder is associated with one and only one appender,
97 referred to as the owning appender. Some appenders have a built-in
98 or fixed event format. Consequently, they do not require nor have a
99 layout/encoder. For example, the <code>SocketAppender</code> simply
100 serializes logging events before transmitting them over the wire.
101 </p>
102
103
104 <h2 class="doAnchor" name="AppenderBase">AppenderBase</h2>
105
106 <p>The <a href="../xref/ch/qos/logback/core/AppenderBase.html">
107 <code>ch.qos.logback.core.AppenderBase</code></a> class is an
108 abstract class implementing the <code>Appender</code> interface. It
109 provides basic functionality shared by all appenders, such as
110 methods for getting or setting their name, their activation status,
111 their layout and their filters. It is the super-class of all
112 appenders shipped with logback. Although an abstract class,
113 <code>AppenderBase</code> actually implements the
114 <code>doAppend()</code> method in the <code>Append</code> interface.
115 Perhaps the clearest way to discuss <code>AppenderBase</code> class
116 is by presenting an excerpt of actual source code.
117 </p>
118
119 <pre class="prettyprint source">public synchronized void doAppend(E eventObject) {
120
121 // prevent re-entry.
122 if (guard) {
123 return;
124 }
125
126 try {
127 guard = true;
128
129 if (!this.started) {
130 if (statusRepeatCount++ &lt; ALLOWED_REPEATS) {
131 addStatus(new WarnStatus(
132 "Attempted to append to non started appender [" + name + "].",this));
133 }
134 return;
135 }
136
137 if (getFilterChainDecision(eventObject) == FilterReply.DENY) {
138 return;
139 }
140
141 // ok, we now invoke the derived class's implementation of append
142 this.append(eventObject);
143
144 } finally {
145 guard = false;
146 }
147 }</pre>
148
149 <p>This implementation of the <code>doAppend()</code> method is
150 synchronized. It follows that logging to the same appender from
151 different threads is safe. While a thread, say <em>T</em>, is
152 executing the <code>doAppend()</code> method, subsequent calls by
153 other threads are queued until <em>T</em> leaves the
154 <code>doAppend()</code> method, ensuring <em>T</em>'s exclusive
155 access to the appender.
156 </p>
157
158 <p>Since such synchronization is not always appropriate, logback
159 ships with <a
160 href="../xref/ch/qos/logback/core/UnsynchronizedAppenderBase.html"><code>ch.qos.logback.core.UnsynchronizedAppenderBase</code></a>
161 which is very similar to the <a
162 href="../xref/ch/qos/logback/core/AppenderBase.html"><code>AppenderBase</code></a>
163 class. For the sake of conciseness, we will be discussing
164 <code>UnsynchronizedAppenderBase</code> in the remainder of this document.
165 </p>
166
167
168 <p>The first thing the <code>doAppend()</code> method does is to
169 check whether the guard is set to true. If it is, it immediately
170 exits. If the guard is not set, it is set to true at the next
171 statement. The guard ensures that the <code>doAppend()</code> method
172 will not recursively call itself. Just imagine that a component,
173 called somewhere beyond the <code>append()</code> method, wants to
174 log something. Its call could be directed to the very same appender
175 that just called it resulting in an infinite loop and a stack
176 overflow.
177 </p>
178
179 <p>In the following statement we check whether the
180 <code>started</code> field is true. If it is not,
181 <code>doAppend()</code> will send a warning message and return. In
182 other words, once an appender is closed, it is impossible to write
183 to it. <code>Appender</code> objects implement the
184 <code>LifeCycle</code> interface, which implies that they implement
185 <code>start()</code>, <code>stop()</code> and
186 <code>isStarted()</code> methods. After setting all the properties of
187 an appender, Joran, logback's configuration framework, calls the
188 <code>start()</code> method to signal the appender to activate its
189 properties. Depending on its kind, an appender may fail to start if
190 certain properties are missing or because of interference between
191 various properties. For example, given that file creation depends on
192 truncation mode, <code>FileAppender</code> cannot act on the value
193 of its <code>File</code> option until the value of the Append option
194 is also known with certainty. The explicit activation step ensures
195 that an appender acts on its properties <em>after</em> their values
196 become known.
197 </p>
198
199 <p>If the appender could not be started or if it has been stopped, a
200 warning message will be issued through logback's internal status
201 management system. After several attempts, in order to avoid
202 flooding the internal status system with copies of the same warning
203 message, the <code>doAppend()</code> method will stop issuing these
204 warnings.
205 </p>
206
207 <p>The next <code>if</code> statement checks the result of the
208 attached filters. Depending on the decision resulting from the
209 filter chain, events can be denied or explicitly accepted. In
210 the absence of a decision by the filter chain, events are accepted
211 by default.
212 </p>
213
214 <p>The <code>doAppend()</code> method then invokes the derived
215 classes' implementation of the <code>append()</code> method. This
216 method does the actual work of appending the event to the
217 appropriate device.
218 </p>
219
220 <p>Finally, the guard is released so as to allow a subsequent
221 invocation of the <code>doAppend()</code> method.
222 </p>
223
224 <p>For the remainder of this manual, we reserve the term "option" or
225 alternatively "property" for any attribute that is inferred
226 dynamically using JavaBeans introspection through setter and getter
227 methods. </p>
228
229 <h1>Logback-core</h1>
230
231 <p>Logback-core lays the foundation upon which the other logback
232 modules are built. In general, the components in logback-core
233 require some, albeit minimal, customization. However, in the next
234 few sections, we describe several appenders which are ready for use
235 out of the box.
236 </p>
237
238
239
240 <h2 class="doAnchor"
241 name="OutputStreamAppender">OutputStreamAppender
242 </h2>
243
244 <p><a
245 href="../xref/ch/qos/logback/core/OutputStreamAppender.html"><code>OutputStreamAppender</code></a>
246 appends events to a <code>java.io.OutputStream</code>. This class
247 provides basic services that other appenders build upon. Users do
248 not usually instantiate <code>OutputStreamAppender</code> objects
249 directly, since in general the <code>java.io.OutputStream</code>
250 type cannot be conveniently mapped to a string, as there is no way
251 to specify the target <code>OutputStream</code> object in a
252 configuration script. Simply put, you cannot configure a
253 <code>OutputStreamAppender</code> from a configuration file.
254 However, this does not mean that <code>OutputStreamAppender</code>
255 lacks configurable properties. These properties are described next.
256 </p>
257
258 <table class="bodyTable striped">
259 <tr>
260 <th>Property Name</th>
261 <th>Type</th>
262 <th>Description</th>
263 </tr>
264
265 <tr>
266 <td><span class="prop" name="osaEncoder">encoder</span></td>
267
268 <td><a
269 href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a></td>
270
271 <td>Determines the manner in which an event is written to the
272 underlying <code>OutputStreamAppender</code>. Encoders are
273 described in a <a href="encoders.html">dedicated chapter</a>.
274 </td>
275 </tr>
276 <tr>
277 <td><span class="prop" name="immediateFlush">immediateFlush</span></td>
278 <td><code>boolean</code></td>
279
280 <td>The default value for <span
281 class="option">immediateFlush</span> is 'true'. Immediate
282 flushing of the output stream ensures that logging events are
283 immediately written out and will not be lost in case your
284 application exits without properly closing appenders. On the
285 other hand, setting this property to 'false' is likely to
286 quadruple (your mileage may vary) logging throughput. Again, if
287 <span class="option">immediateFlush</span> is set to 'false' and
288 if appenders are not closed properly when your application exits,
289 then logging events not yet written to disk may be lost.
290 </td>
291 </tr>
292
293
294 </table>
295
296 <p>The <code>OutputStreamAppender</code> is the super-class of three other
297 appenders, namely <code>ConsoleAppender</code>,
298 <code>FileAppender</code> which in turn is the super class of
299 <code>RollingFileAppender</code>. The next figure illustrates the
300 class diagram for <code>OutputStreamAppender</code> and its subclasses.
301 </p>
302
303 <img src="images/chapters/appenders/appenderClassDiagram.jpg" alt="A UML diagram showing OutputStreamAppender and sub-classes"/>
304
305
306 <h2 class="doAnchor" name="ConsoleAppender">ConsoleAppender</h2>
307
308 <p>The <a href="../xref/ch/qos/logback/core/ConsoleAppender.html">
309 <code>ConsoleAppender</code></a>, as the name indicates, appends on
310 the console, or more precisely on <em>System.out</em> or
311 <em>System.err</em>, the former being the default
312 target. <code>ConsoleAppender</code> formats events with the help of
313 an encoder specified by the user. Encoders will be discussed in a
314 subsequent chapter. Both <em>System.out</em> and <em>System.err</em>
315 are of type <code>java.io.PrintStream</code>. Consequently, they
316 are wrapped inside an <code>OutputStreamWriter</code> which buffers
317 I/O operations.
318 </p>
319
320 <table class="bodyTable striped">
321 <tr>
322 <th>Property Name</th>
323 <th>Type</th>
324 <th>Description</th>
325 </tr>
326 <tr>
327 <td><span class="prop" container="conApp">encoder</span></td>
328 <td>
329 <a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
330 </td>
331 <td>See <code>OutputStreamAppender</code> properties.</td>
332 </tr>
333 <tr>
334 <td><span class="prop" container="conApp">target</span></td>
335 <td><code>String</code></td>
336 <td>
337 One of the String values <em>System.out</em> or
338 <em>System.err</em>. The default target is <em>System.out</em>.
339 </td>
340 </tr>
341
342 <tr>
343 <td><span class="prop" container="conApp">withJansi</span></td>
344 <td><code>boolean</code></td>
345 <td>By the default <span class="prop">withJansi</span> property
346 is set to <code>false</code>. Setting <span
347 class="prop">withJansi</span> to <code>true</code> activates the
348 <a href="http://jansi.fusesource.org/">Jansi</a> library which
349 provides support for ANSI color codes on Windows machines. On a
350 Windows host, if this property is set to true, then you should
351 put "org.fusesource.jansi:jansi:${jansi.version}" on the class
352 path. Note that Unix-based operating systems such as Linux and
353 Mac OS X support ANSI color codes by default.
354
355 <p>Under the Eclipse IDE, you might want to try the <a
356 href="http://www.mihai-nita.net/eclipse/">ANSI in Eclipse
357 Console</a> plugin.
358 </p>
359 </td>
360 </tr>
361
362 </table>
363
364 <p>Here is a sample configuration that uses
365 <code>ConsoleAppender</code>.
366 </p>
367
368
369
370 <p class="example">Example: ConsoleAppender configuration
371 (logback-examples/src/main/resources/chapters/appenders/conf/logback-Console.xml)</p>
372
373 <span class="asGroovy" onclick="return asGroovy('logback_Console');">View as .groovy</span>
374
375 <pre id="logback_Console" class="prettyprint source">&lt;configuration>
376
377 <b>&lt;appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
378 &lt;!-- encoders are assigned the type
379 ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
380 &lt;encoder>
381 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg %n&lt;/pattern>
382 &lt;/encoder>
383 &lt;/appender></b>
384
385 &lt;root level="DEBUG">
386 &lt;appender-ref ref="STDOUT" />
387 &lt;/root>
388 &lt;/configuration></pre>
389
390 <p>After you have set your current path to the
391 <em>logback-examples</em> directory and <a href="../setup.html">set
392 up your class path</a>, you can give the above configuration file a
393 whirl by issuing the following command:
394 </p>
395
396 <p class="source">java <a
397 href="../xref/chapters/appenders/ConfigurationTester.html">chapters.appenders.ConfigurationTester</a> src/main/java/chapters/appenders/conf/logback-Console.xml</p>
398
399
400 <h2 class="doAnchor" name="FileAppender">FileAppender</h2>
401
402 <p>The <a
403 href="../xref/ch/qos/logback/core/FileAppender.html"><code>FileAppender</code></a>,
404 a subclass of <code>OutputStreamAppender</code>, appends log events into
405 a file. The target file is specified by the <span
406 class="prop">File</span> option. If the file already exists, it
407 is either appended to, or truncated depending on the value of the
408 <span class="prop">append</span> property.
409 </p>
410
411 <table class="bodyTable properties striped">
412 <tr>
413 <th>Property Name</th>
414 <th>Type</th>
415 <th>Description</th>
416 </tr>
417 <tr>
418 <td><span class="prop" container="fileApppender">append</span></td>
419 <td><code>boolean</code></td>
420 <td>If true, events are appended at the end of an existing
421 file. Otherwise, if <span class="prop">append</span> is false,
422 any existing file is truncated. The <span
423 class="option">append</span> option is set to true by default.
424 </td>
425 </tr>
426 <tr >
427 <td><span class="prop" container="fileApppender">encoder</span></td>
428 <td>
429 <a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
430 </td>
431 <td>See <code>OutputStreamAppender</code> properties.</td>
432 </tr>
433
434
435 <tr>
436 <td><span class="prop"
437 container="fileApppender">file</span></td>
438 <td><code>String</code></td>
439 <td>The name of the file to write to. If the file does not
440 exist, it is created. On the MS Windows platform users
441 frequently forget to escape back slashes. For example, the
442 value <em>c:\temp\test.log</em> is not likely to be interpreted
443 properly as <em>'\t'</em> is an escape sequence interpreted as
444 a single tab character <em>(\u0009)</em>. Correct values can
445 be specified as <em>c:/temp/test.log</em> or alternatively as
446 <em>c:\\temp\\test.log</em>. The <span
447 class="prop">File</span> option has no default value.
448
449 <p>If the parent directory of the file does not exist,
450 <code>FileAppender</code> will automatically create it,
451 including any necessary but nonexistent parent directories.
452 </p>
453 </td>
454 </tr>
455
456 <tr>
457 <td><span class="prop" name="prudent">prudent</span></td>
458 <td><code>boolean</code></td>
459
460 <td>In prudent mode, <code>FileAppender</code> will safely
461 write to the specified file, even in the presence of other
462 <code>FileAppender</code> instances running in different
463 JVMs, potentially running on different hosts. The default
464 value for prudent mode is <code>false</code>.
465
466 <p>Prudent mode can be used in conjunction with
467 <code>RollingFileAppender</code> although some <a
468 href="#prudentWithRolling">restrictions apply</a>.</p>
469
470 <p>Prudent mode implies that <span
471 class="prop">append</span> property is automatically set to
472 true.
473 </p>
474
475 <p>Prudent more relies on exclusive file locks. Experiments
476 show that file locks approximately triple (x3) the cost of
477 writing a logging event. On an "average" PC writing to a file
478 located on a <b>local</b> hard disk, when prudent mode is
479 off, it takes about 10 microseconds to write a single logging
480 event. When prudent mode is on, it takes approximately 30
481 microseconds to output a single logging event. This
482 translates to logging throughput of 100'000 events per second
483 when prudent mode is off and approximately 33'000 events per
484 second in prudent mode.
485 </p>
486
487 <p>Prudent mode effectively serializes I/O operations between
488 all JVMs writing to the same file. Thus, as the number of
489 JVMs competing to access a file increases so will the delay
490 incurred by each I/O operation. As long as the <em>total</em>
491 number of I/O operations is in the order of 20 log requests
492 per second, the impact on performance should be
493 negligible. Applications generating 100 or more I/O
494 operations per second can see an impact on performance and
495 should avoid using <span class="prop">prudent</span> mode.
496 </p>
497
498 <p><span class="label">Networked file locks</span> When the
499 log file is located on a networked file system, the cost of
500 prudent mode is even greater. Just as importantly, file locks
501 over a networked file system can be sometimes strongly biased
502 such that the process currently owning the lock immediately
503 re-obtains the lock upon its release. Thus, while one process
504 hogs the lock for the log file, other processes starve
505 waiting for the lock to the point of appearing deadlocked.
506 </p>
507
508 <p>The impact of prudent mode is highly dependent on network
509 speed as well as the OS implementation details. We provide an
510 very small application called <a
511 href="https://gist.github.com/2794241">FileLockSimulator</a>
512 which can help you simulate the behavior of prudent mode in
513 your environment.
514 </p>
515
516
517 </td>
518
519 </tr>
520 </table>
521
522 <p><span class="label notice">Immediate Flush</span> By default,
523 each log event is immediately flushed to the underlying output
524 stream. This default approach is safer in the sense that logging
525 events are not lost in case your application exits without properly
526 closing appenders. However, for significantly increased logging
527 throughput, you may want to set the <span
528 class="prop">immediateFlush</span> property to
529 <code>false</code>.</p>
530
531 <p>Below is an example of a configuration file for
532 <code>FileAppender</code>:
533 </p>
534
535 <p class="example">Example: FileAppender configuration
536 (logback-examples/src/main/resources/chapters/appenders/conf/logback-fileAppender.xml)</p>
537
538 <span class="asGroovy" onclick="return asGroovy('logback-fileAppender');">View as .groovy</span>
539 <pre id="logback-fileAppender" class="prettyprint source">&lt;configuration>
540
541 <b>&lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
542 &lt;file>testFile.log&lt;/file>
543 &lt;append>true&lt;/append>
544 &lt;!-- set immediateFlush to false for much higher logging throughput -->
545 &lt;immediateFlush>true&lt;/immediateFlush>
546 &lt;!-- encoders are assigned the type
547 ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
548 &lt;encoder>
549 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n&lt;/pattern>
550 &lt;/encoder>
551 &lt;/appender></b>
552
553 &lt;root level="DEBUG">
554 &lt;appender-ref ref="FILE" />
555 &lt;/root>
556 &lt;/configuration></pre>
557
558 <p>After changing the current directory to
559 <em>logback-examples</em>, run this example by launching the
560 following command:
561 </p>
562
563 <p class="source">java chapters.appenders.ConfigurationTester
564 src/main/java/chapters/appenders/conf/logback-fileAppender.xml</p>
565
566
567 <h3 class="doAnchor" name="uniquelyNamed">Uniquely named files (by
568 timestamp)</h3>
569
570 <p>During the application development phase or in the case of
571 short-lived applications, e.g. batch applications, it is desirable
572 to create a new log file at each new application launch. This is
573 fairly easy to do with the help of the <code>&lt;timestamp></code>
574 element. Here's an example.</p>
575
576
577 <p class="example">Example: Uniquely named FileAppender
578 configuration by timestamp
579 (logback-examples/src/main/resources/chapters/appenders/conf/logback-timestamp.xml)</p>
580
581 <span class="asGroovy" onclick="return asGroovy('logback-timestamp');">View as .groovy</span>
582 <pre id="logback-timestamp" class="prettyprint source">&lt;configuration>
583
584 &lt;!-- Insert the current time formatted as "yyyyMMdd'T'HHmmss" under
585 the key "bySecond" into the logger context. This value will be
586 available to all subsequent configuration elements. -->
587 <b>&lt;timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss"/></b>
588
589 &lt;appender name="FILE" class="ch.qos.logback.core.FileAppender">
590 &lt;!-- use the previously created timestamp to create a uniquely
591 named log file -->
592 &lt;file><b>log-${bySecond}.txt</b>&lt;/file>
593 &lt;encoder>
594 &lt;pattern>%logger{35} - %msg%n&lt;/pattern>
595 &lt;/encoder>
596 &lt;/appender>
597
598 &lt;root level="DEBUG">
599 &lt;appender-ref ref="FILE" />
600 &lt;/root>
601 &lt;/configuration></pre>
602
603
604 <p>The timestamp element takes two mandatory attributes <span
605 class="attr">key</span> and <span class="attr">datePattern</span>
606 and an optional <span class="attr">timeReference</span>
607 attribute. The <span class="attr">key</span> attribute is the name
608 of the key under which the timestamp will be available to
609 subsequent configuration elements <a
610 href="configuration.html#variableSubstitution">as a
611 variable</a>. The <span class="attr">datePattern</span> attribute
612 denotes the date pattern used to convert the current time (at which
613 the configuration file is parsed) into a string. The date pattern
614 should follow the conventions defined in <a
615 href="https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html">SimpleDateFormat</a>. The
616 <span class="attr">timeReference</span> attribute denotes the time
617 reference for the time stamp. The default is the
618 interpretation/parsing time of the configuration file, i.e. the
619 current time. However, under certain circumstances it might be
620 useful to use the context birth time as time reference. This can be
621 accomplished by setting the <span class="attr">timeReference</span>
622 attribute to <code>"contextBirth"</code>.
623 </p>
624
625 <p>Experiment with the <code>&lt;timestamp></code> element by
626 running the command:</p>
627
628 <p class="command">java chapters.appenders.ConfigurationTester src/main/resources/chapters/appenders/conf/logback-timestamp.xml</p>
629
630 <p>To use the logger context birth date as time reference, you
631 would set the <span class="attr">timeReference</span> attribute to
632 "contextBirth" as shown below.</p>
633
634
635 <p class="example">Example: Timestamp using context birth date as time reference
636 (logback-examples/src/main/resources/chapters/appenders/conf/logback-timestamp-contextBirth.xml)</p>
637
638 <span class="asGroovy" onclick="return asGroovy('logback-timestamp-contextBirth');">View as .groovy</span>
639 <pre id="logback-timestamp-contextBirth" class="prettyprint source">&lt;configuration>
640 &lt;timestamp key="bySecond" datePattern="yyyyMMdd'T'HHmmss"
641 <b>timeReference="contextBirth"</b>/>
642 ...
643 &lt;/configuration></pre>
644
645 <h2 class="doAnchor" name="RollingFileAppender">RollingFileAppender
646 </h2>
647
648 <p><a
649 href="../xref/ch/qos/logback/core/rolling/RollingFileAppender.html"><code>RollingFileAppender</code></a>
650 extends <code>FileAppender</code> with the capability to rollover log
651 files. For example, <code>RollingFileAppender</code> can log to a
652 file named <em>log.txt</em> file and, once a certain condition is
653 met, change its logging target to another file.
654 </p>
655
656 <p>There are two important sub-components that interact with
657 <code>RollingFileAppender</code>. The first
658 <code>RollingFileAppender</code> sub-component, namely
659 <code>RollingPolicy</code>, (<a href="#onRollingPolicies">see
660 below</a>) is responsible for undertaking the actions required for
661 a rollover. A second sub-component of
662 <code>RollingFileAppender</code>, namely
663 <code>TriggeringPolicy</code>, (<a href="#TriggeringPolicy">see
664 below</a>) will determine if and exactly when rollover
665 occurs. Thus, <code>RollingPolicy</code> is responsible for the
666 <em>what</em> and <code>TriggeringPolicy</code> is responsible for
667 the <em>when</em>. </p>
668
669 <p>To be of any use, a <code>RollingFileAppender</code> must have
670 both a <code>RollingPolicy</code> and a
671 <code>TriggeringPolicy</code> set up. However, if its
672 <code>RollingPolicy</code> also implements the
673 <code>TriggeringPolicy</code> interface, then only the former needs
674 to be specified explicitly.
675 </p>
676
677 <p>Here are the available properties for <code>RollingFileAppender</code>:</p>
678
679 <table class="bodyTable striped">
680 <tr>
681 <th>Property Name</th>
682 <th>Type</th>
683 <th>Description</th>
684 </tr>
685 <tr>
686 <td><span class="prop" container="rfa">file</span></td>
687 <td><code>String</code></td>
688 <td>See <code>FileAppender</code> properties.</td>
689 </tr>
690 <tr>
691 <td><span class="prop" container="rfa">append</span></td>
692 <td><code>boolean</code></td>
693 <td>See <code>FileAppender</code> properties.</td>
694 </tr>
695 <tr>
696 <td><span class="prop" container="rfa">encoder</span></td>
697 <td>
698 <a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
699 </td>
700 <td>See <code>OutputStreamAppender</code> properties.</td>
701 </tr>
702 <tr>
703 <td><span class="prop" container="rfa">rollingPolicy</span></td>
704 <td><code>RollingPolicy</code></td>
705 <td>This option is the component that will dictate
706 <code>RollingFileAppender</code>'s behavior when rollover
707 occurs. See more information below.
708 </td>
709 </tr>
710 <tr>
711 <td><span class="prop" container="rfa">triggeringPolicy</span></td>
712 <td><code>TriggeringPolicy</code></td>
713 <td>
714 This option is the component that will tell
715 <code>RollingFileAppender</code> when to activate the rollover
716 procedure. See more information below.
717 </td>
718 </tr>
719 <tr>
720 <td valign="top"><span class="prop" name="prudentWithRolling">prudent</span></td>
721
722 <td valign="top"><code>boolean</code></td>
723
724 <td valign="top">
725 <a
726 href="#FixedWindowRollingPolicy"><code>FixedWindowRollingPolicy</code></a>
727 is not supported in prudent mode.
728
729 <p> <code>RollingFileAppender</code> supports the prudent
730 mode in conjunction with <a
731 href="#TimeBasedRollingPolicy"><code>TimeBasedRollingPolicy</code></a>
732 albeit with two restrictions.
733 </p>
734
735 <ol>
736 <li>In prudent mode, file compression is not supported nor
737 allowed. (We can't have one JVM writing to a file while
738 another JVM is compressing it.) </li>
739
740 <li>The <span class="prop">file</span> property of
741 <code>FileAppender</code> cannot be set and must be left
742 blank. Indeed, most operating systems do not allow renaming
743 of a file while another process has it opened.
744 </li>
745
746 </ol>
747
748 See also properties for <code>FileAppender</code>.
749 </td>
750 </tr>
751 </table>
752
753 <h3 class="doAnchor" name="onRollingPolicies">Overview of rolling
754 policies</h3>
755
756 <p><a
757 href="../xref/ch/qos/logback/core/rolling/RollingPolicy.html"><code>RollingPolicy</code></a>
758 is responsible for the rollover procedure which involves file
759 moving and renaming.</p>
760
761 <p>The <code>RollingPolicy</code> interface is presented below:</p>
762
763 <pre class="prettyprint source">package ch.qos.logback.core.rolling;
764
765 import ch.qos.logback.core.FileAppender;
766 import ch.qos.logback.core.spi.LifeCycle;
767
768 public interface RollingPolicy extends LifeCycle {
769
770 <b>public void rollover() throws RolloverFailure;</b>
771 public String getActiveFileName();
772 public CompressionMode getCompressionMode();
773 public void setParent(FileAppender appender);
774 }</pre>
775
776 <p>The <code>rollover</code> method accomplishes the work involved
777 in archiving the current log file. The
778 <code>getActiveFileName()</code> method is called to compute the
779 file name of the current log file (where live logs are written
780 to). As indicated by <code>getCompressionMode</code> method a
781 RollingPolicy is also responsible for determining the compression
782 mode. Lastly, a <code>RollingPolicy</code> is given a reference to
783 its parent via the <code>setParent</code> method.
784 </p>
785
786 <!-- =================
787 ================= -->
788
789
790 <h4 class="doAnchor" name="TimeBasedRollingPolicy">TimeBasedRollingPolicy </h4>
791
792 <p><a
793 href="../xref/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html">
794 <code>TimeBasedRollingPolicy</code></a> is possibly the most
795 popular rolling policy. It defines a rollover policy based on time,
796 for example by day or by month.
797 <code>TimeBasedRollingPolicy</code> assumes the responsibility for
798 rollover as well as for the triggering of said rollover. Indeed,
799 <code>TimeBasedTriggeringPolicy</code> implements <em>both</em>
800 <code>RollingPolicy</code> and <code>TriggeringPolicy</code>
801 interfaces.
802 </p>
803
804 <p><code>TimeBasedRollingPolicy</code>'s configuration takes one
805 mandatory <span class="prop">fileNamePattern</span> property and
806 several optional properties.
807 </p>
808
809 <table class="bodyTable striped">
810 <tr>
811 <th>Property Name</th>
812 <th>Type</th>
813 <th>Description</th>
814 </tr>
815 <tr>
816 <td><span class="prop" container="tbrp">fileNamePattern</span></td>
817 <td><code>String</code></td>
818 <td>
819 The mandatory <span class="prop">fileNamePattern</span>
820 property defines the name of the rolled-over (archived) log
821 files. Its value should consist of the name of the file, plus
822 a suitably placed <em>%d</em> conversion specifier. The
823 <em>%d</em> conversion specifier may contain a date-and-time
824 pattern as specified by the
825 <code>java.text.SimpleDateFormat</code> class. If the
826 date-and-time pattern is omitted, then the default pattern
827 <em>yyyy-MM-dd</em> is assumed. <b>The rollover period is
828 inferred from the value of <span
829 class="prop">fileNamePattern</span>.</b>
830
831
832 <p>Note that the <span class="prop">file</span> property in
833 <code>RollingFileAppender</code> (the parent of
834 <code>TimeBasedRollingPolicy</code>) can be either set or
835 omitted. By setting the <span class="prop">file</span>
836 property of the containing <code>FileAppender</code>, you can
837 decouple the location of the active log file and the location
838 of the archived log files. The current logs will be always
839 targeted at the file specified by the <span
840 class="prop">file</span> property. It follows that the name
841 of the currently active log file will not change over
842 time. However, if you choose to omit the <span
843 class="prop">file</span> property, then the active file
844 will be computed anew for each period based on the value of
845 <span class="prop">fileNamePattern</span>. The examples
846 below should clarify this point.
847 </p>
848
849 <p>The date-and-time pattern, as found within the accolades
850 of %d{} follow java.text.SimpleDateFormat conventions. The
851 forward slash '/' or backward slash '\' characters anywhere
852 within the <span class="option">fileNamePattern</span>
853 property or within the date-and-time pattern will be
854 interpreted as directory separators.
855 </p>
856
857 <h5>Multiple %d specifiers</h5>
858
859 <p>It is possible to specify multiple %d specifiers but only
860 one of which can be primary, i.e. used to infer the rollover
861 period. All other tokens <em>must</em> be marked as auxiliary
862 by passing the 'aux' parameter (see examples below).</p>
863
864 <p>Multiple %d specifiers allow you to organize archive files
865 in a folder structure different than that of the roll-over
866 period. For example, the file name pattern shown below
867 organizes log folders by year and month but roll-over log
868 files every day at midnight.</p>
869
870 <pre>/var/log/<b>%d{yyyy/MM, aux}</b>/myapplication.<b>%d{yyyy-MM-dd}</b>.log</pre>
871
872 <h5>TimeZone</h5>
873
874 <p>Under certain circumstances, you might wish to roll-over
875 log files according to a clock in a timezone different than
876 that of the host. It is possible to pass a timezone argument
877 following the date-and-time pattern within the %d conversion
878 specifier. For example:</p>
879
880 <pre>aFolder/test.<b>%d</b>{yyyy-MM-dd-HH, <b>UTC</b>}.log</pre>
881
882 <p>If the specified timezone identifier is unknown or
883 misspelled, the GMT timezone is assumed as dictated by the <a
884 href="http://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#getTimeZone(java.lang.String)">TimeZone.getTimeZone(String)</a>
885 method specification.
886 </p>
887 </td>
888 </tr>
889 <tr>
890 <td><span class="prop" container="tbrp">maxHistory</span></td>
891 <td>int</td>
892 <td>The optional <span class="prop">maxHistory</span> property
893 controls the maximum number of archive files to keep,
894 asynchronously deleting older files. For example, if you
895 specify monthly rollover, and set maxHistory to 6, then 6
896 months worth of archives files will be kept with files older
897 than 6 months deleted. Note as old archived log files are
898 removed, any folders which were created for the purpose of log
899 file archiving will be removed as appropriate.
900 </td>
901 </tr>
902
903 <tr>
904 <td><span class="prop" container="tbrp">totalSizeCap</span></td>
905 <td>int</td>
906 <td><p>The optional <span class="prop">totalSizeCap</span>
907 property controls the total size of all archive files. Oldest
908 archives are deleted asynchronously when the total size cap is
909 exceeded. The <span class="prop">totalSizeCap</span> property
910 requires <span class="option">maxHistory</span> property to be
911 set as well. Moreover, the "max history" restriction is always
912 applied first and the "total size cap" restriction applied
913 second. </p>
914 </td>
915 </tr>
916
917 <tr >
918 <td><span class="prop"
919 container="tbrp">cleanHistoryOnStart</span></td>
920 <td>boolean</td>
921 <td>
922 <p>If set to true, archive removal will be executed on
923 appender start up. By default this property is set to
924 false. </p>
925
926 <p>Archive removal is normally performed during roll
927 over. However, some applications may not live long enough for
928 roll over to be triggered. It follows that for such
929 short-lived applications archive removal may never get a
930 chance to execute. By setting <span
931 class="prop">cleanHistoryOnStart</span> to true, archive
932 removal is performed at appender start up.</p>
933 </td>
934 </tr>
935 </table>
936
937
938 <p>Here are a few <code>fileNamePattern</code> values with an
939 explanation of their effects.</p>
940
941
942
943 <table class="bodyTable striped">
944 <tr>
945 <th>
946 <span class="prop">fileNamePattern</span>
947 </th>
948 <th>Rollover schedule</th>
949 <th>Example</th>
950 </tr>
951 <tr>
952 <td class="small">
953 <em>/wombat/foo.%d</em>
954 </td>
955 <td>Daily rollover (at midnight). Due to the omission of the
956 optional time and date pattern for the <em>%d</em> token
957 specifier, the default pattern of <em>yyyy-MM-dd</em> is
958 assumed, which corresponds to daily rollover.
959 </td>
960
961 <td>
962 <p><span class="prop">file</span> property not set: During November
963 23rd, 2006, logging output will go to the file
964 <em>/wombat/foo.2006-11-23</em>. At midnight and for the
965 rest of the 24th, logging output will be directed to
966 <em>/wombat/foo.2006-11-24</em>.
967 </p>
968
969 <p><span class="prop">file</span> property set to
970 <em>/wombat/foo.txt</em>: During November 23rd, 2006, logging
971 output will go to the file <em>/wombat/foo.txt</em>. At
972 midnight, <em>foo.txt</em> will be renamed as
973 <em>/wombat/foo.2006-11-23</em>. A new
974 <em>/wombat/foo.txt</em> file will be created and for the
975 rest of November 24th logging output will be directed to
976 <em>foo.txt</em>.
977 </p>
978
979 </td>
980 </tr>
981
982
983 <tr>
984 <td class="small">
985 <em>/wombat/%d{yyyy/MM}/foo.txt</em>
986 </td>
987 <td>Rollover at the beginning of each month.</td>
988 <td>
989 <p><span class="prop">file</span> property not set: During
990 the month of October 2006, logging output will go to
991 <em>/wombat/2006/10/foo.txt</em>. After midnight of October
992 31st and for the rest of November, logging output will be
993 directed to <em>/wombat/2006/11/foo.txt</em>.
994 </p>
995
996 <p><span class="prop">file</span> property set to
997 <em>/wombat/foo.txt</em>: The active log file will always be
998 <em>/wombat/foo.txt</em>. During the month of October 2006,
999 logging output will go to <em>/wombat/foo.txt</em>. At
1000 midnight of October 31st, <em>/wombat/foo.txt</em> will be
1001 renamed as <em>/wombat/2006/10/foo.txt</em>. A new
1002 <em>/wombat/foo.txt</em> file will be created where logging
1003 output will go for the rest of November. At midnight of
1004 November 30th, <em>/wombat/foo.txt</em> will be renamed as
1005 <em>/wombat/2006/11/foo.txt</em> and so on.
1006 </p>
1007 </td>
1008 </tr>
1009 <tr>
1010 <td class="small">
1011 <em>/wombat/foo.%d{yyyy-ww}.log</em>
1012 </td>
1013
1014 <td>Rollover at the first day of each week. Note that the first
1015 day of the week depends on the locale.</td>
1016
1017 <td>Similar to previous cases, except that rollover will occur
1018 at the beginning of every new week.
1019 </td>
1020 </tr>
1021 <tr>
1022 <td class="small">
1023 <em>/wombat/foo%d{yyyy-MM-dd_HH}.log</em>
1024 </td>
1025 <td>Rollover at the top of each hour.</td>
1026 <td>Similar to previous cases, except that rollover will occur
1027 at the top of every hour.
1028 </td>
1029 </tr>
1030 <tr>
1031 <td class="small">
1032 <em>/wombat/foo%d{yyyy-MM-dd_HH-mm}.log</em>
1033 </td>
1034 <td>Rollover at the beginning of every minute.</td>
1035 <td>Similar to previous cases, except that rollover will occur
1036 at the beginning of every minute.
1037 </td>
1038 </tr>
1039 <tr>
1040 <td class="small">
1041 <em>/wombat/foo%d{yyyy-MM-dd_HH-mm, UTC}.log</em>
1042 </td>
1043 <td>Rollover at the beginning of every minute.</td>
1044 <td>Similar to previous cases, except that file names will be
1045 expressed in UTC.
1046 </td>
1047 </tr>
1048
1049
1050 <tr>
1051 <td class="small">
1052 <em>/foo/%d{yyyy-MM,<b>aux</b>}/%d.log</em>
1053 </td>
1054 <td>Rollover daily. Archives located under a folder containing
1055 year and month.
1056 </td>
1057 <td>In this example, the first %d token is marked as
1058 <b>aux</b>iliary. The second %d token, with time and date
1059 pattern omitted, is then assumed to be primary. Thus, rollover
1060 will occur daily (default for %d) and the folder name will
1061 depend on the year and month. For example, during the month of
1062 November 2006, archived files will all placed under the
1063 /foo/2006-11/ folder, e.g <em>/foo/2006-11/2006-11-14.log</em>.
1064 </td>
1065
1066 </tr>
1067 </table>
1068
1069 <p>Any forward or backward slash characters are interpreted as
1070 folder (directory) separators. Any required folder will be created
1071 as necessary. You can thus easily place your log files in separate
1072 folders.
1073 </p>
1074
1075
1076 <p><code>TimeBasedRollingPolicy</code> supports automatic file
1077 compression. This feature is enabled if the value of the <span
1078 class="prop">fileNamePattern</span> option ends with <em>.gz</em>
1079 or <em>.zip</em>.
1080 </p>
1081
1082 <table class="bodyTable striped">
1083 <tr class="a">
1084 <th><span class="prop">fileNamePattern</span></th>
1085 <th>Rollover schedule</th>
1086 <th>Example</th>
1087 </tr>
1088 <tr>
1089 <td><em>/wombat/foo.%d.gz</em></td>
1090 <td>Daily rollover (at midnight) with automatic GZIP compression of the
1091 archived files.</td>
1092 <td>
1093 <p><span class="prop">file</span> property not set: During
1094 November 23rd, 2009, logging output will go to the file
1095 <em>/wombat/foo.2009-11-23</em>. However, at midnight that
1096 file will be compressed to become
1097 <em>/wombat/foo.2009-11-23.gz</em>. For the 24th of November,
1098 logging output will be directed to
1099 <em>/wombat/folder/foo.2009-11-24</em> until it's rolled over
1100 at the beginning of the next day.
1101 </p>
1102
1103 <p><span class="prop">file</span> property set to
1104 /wombat/foo.txt: During November 23rd, 2009, logging output
1105 will go to the file <em>/wombat/foo.txt</em>. At midnight that
1106 file will be compressed and renamed as
1107 <em>/wombat/foo.2009-11-23.gz</em>. A new
1108 <em>/wombat/foo.txt</em> file will be created where logging
1109 output will go for the rest of November 24rd. At midnight
1110 November 24th, <em>/wombat/foo.txt</em> will be compressed and
1111 renamed as <em>/wombat/foo.2009-11-24.gz</em> and so on.
1112 </p>
1113 </td>
1114 </tr>
1115 </table>
1116
1117 <p>The <span class="prop">fileNamePattern</span> serves a dual
1118 purpose. First, by studying the pattern, logback computes the
1119 requested rollover periodicity. Second, it computes each archived
1120 file's name. Note that it is possible for two different patterns to
1121 specify the same periodicity. The patterns <em>yyyy-MM</em> and
1122 <em>yyyy@MM</em> both specify monthly rollover, although the
1123 resulting archive files will carry different names.
1124 </p>
1125
1126 <p>By setting the <span class="prop">file</span> property you can
1127 decouple the location of the active log file and the location of
1128 the archived log files. The logging output will be targeted into
1129 the file specified by the <span class="prop">file</span>
1130 property. It follows that the name of the active log file will not
1131 change over time. However, if you choose to omit the <span
1132 class="prop">file</span> property, then the active file will be
1133 computed anew for each period based on the value of <span
1134 class="prop">fileNamePattern</span>. By leaving the <span
1135 class="prop">file</span> option unset you can avoid file <a
1136 href="../codes.html#renamingError">renaming errors</a> which occur
1137 while there exist external file handles referencing log files during
1138 roll over.
1139 </p>
1140
1141 <p>The <span class="prop">maxHistory</span> property controls the
1142 maximum number of archive files to keep, deleting older files. For
1143 example, if you specify monthly rollover, and set <span
1144 class="prop">maxHistory</span> to 6, then 6 months worth of
1145 archives files will be kept with files older than 6 months
1146 deleted. Note as old archived log files are removed, any folders
1147 which were created for the purpose of log file archiving will be
1148 removed as appropriate.
1149 </p>
1150
1151 <p>For various technical reasons, rollovers are not clock-driven
1152 but depend on the arrival of logging events. For example, on 8th of
1153 March 2002, assuming the <span
1154 class="prop">fileNamePattern</span> is set to <em>yyyy-MM-dd</em>
1155 (daily rollover), the arrival of the first event after midnight
1156 will trigger a rollover. If there are no logging events during, say
1157 23 minutes and 47 seconds after midnight, then rollover will
1158 actually occur at 00:23'47 AM on March 9th and not at 0:00 AM.
1159 Thus, depending on the arrival rate of events, rollovers might be
1160 triggered with some latency. However, regardless of the delay, the
1161 rollover algorithm is known to be correct, in the sense that all
1162 logging events generated during a certain period will be output in
1163 the correct file delimiting that period.
1164 </p>
1165
1166 <p>Here is a sample configuration for
1167 <code>RollingFileAppender</code> in conjunction with a
1168 <code>TimeBasedRollingPolicy</code>.
1169 </p>
1170
1171 <p class="example">Example: Sample configuration of a
1172 <code>RollingFileAppender</code> using a
1173 <code>TimeBasedRollingPolicy</code>
1174 (logback-examples/src/main/resources/chapters/appenders/conf/logback-RollingTimeBased.xml)</p>
1175
1176 <span class="asGroovy" onclick="return asGroovy('logback-RollingTimeBased');">View as .groovy</span>
1177 <pre id="logback-RollingTimeBased" class="prettyprint source">&lt;configuration>
1178 &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
1179 &lt;file>logFile.log&lt;/file>
1180 <b>&lt;rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
1181 &lt;!-- daily rollover -->
1182 &lt;fileNamePattern>logFile.%d{yyyy-MM-dd}.log&lt;/fileNamePattern>
1183
1184 &lt;!-- keep 30 days' worth of history capped at 3GB total size -->
1185 &lt;maxHistory>30&lt;/maxHistory>
1186 &lt;totalSizeCap>3GB&lt;/totalSizeCap>
1187
1188 &lt;/rollingPolicy></b>
1189
1190 &lt;encoder>
1191 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n&lt;/pattern>
1192 &lt;/encoder>
1193 &lt;/appender>
1194
1195 &lt;root level="DEBUG">
1196 &lt;appender-ref ref="FILE" />
1197 &lt;/root>
1198 &lt;/configuration></pre>
1199
1200 <p>The next configuration sample illustrates the use of
1201 <code>RollingFileAppender</code> associated with
1202 <code>TimeBasedRollingPolicy</code> in <span class="prop">prudent</span>
1203 mode.
1204 </p>
1205
1206 <p class="example">Example: Sample configuration of a
1207 <code>RollingFileAppender</code> using a
1208 <code>TimeBasedRollingPolicy</code>
1209 (logback-examples/src/main/resources/chapters/appenders/conf/logback-PrudentTimeBasedRolling.xml)</p>
1210
1211 <span class="asGroovy" onclick="return asGroovy('logback-PrudentTimeBasedRolling');">View as .groovy</span>
1212 <pre id="logback-PrudentTimeBasedRolling" class="prettyprint source">&lt;configuration>
1213 &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
1214 <b>&lt;!-- Support multiple-JVM writing to the same log file --></b>
1215 <b>&lt;prudent>true&lt;/prudent></b>
1216 &lt;rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
1217 &lt;fileNamePattern>logFile.%d{yyyy-MM-dd}.log&lt;/fileNamePattern>
1218 &lt;maxHistory>30&lt;/maxHistory>
1219 &lt;totalSizeCap>3GB&lt;/totalSizeCap>
1220 &lt;/rollingPolicy>
1221
1222 &lt;encoder>
1223 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n&lt;/pattern>
1224 &lt;/encoder>
1225 &lt;/appender>
1226
1227 &lt;root level="DEBUG">
1228 &lt;appender-ref ref="FILE" />
1229 &lt;/root>
1230 &lt;/configuration></pre>
1231
1232
1233
1234 <h3 class="doAnchor" name="SizeAndTimeBasedRollingPolicy">Size and
1235 time based rolling policy</h3>
1236
1237
1238 <p>Sometimes you may wish to archive files essentially by date but
1239 at the same time limit the size of each log file, in particular if
1240 post-processing tools impose size limits on the log files. In
1241 order to address this requirement, logback ships with
1242 <code>SizeAndTimeBasedRollingPolicy</code>.</p>
1243
1244 <p>Note that <code>TimeBasedRollingPolicy</code> already allows
1245 limiting the combined size of archived log files. If you only wish
1246 to limit the combined size of log archives, then
1247 <code>TimeBasedRollingPolicy</code> described above and setting
1248 the <a href="#tbrpTotalSizeCap"><span
1249 class="option">totalSizeCap</span></a> property should be amply
1250 sufficent.
1251 </p>
1252
1253 <p>Here is a sample configuration file demonstrating time and size
1254 based log file archiving.</p>
1255
1256 <p class="example">Example: Sample configuration for
1257 <code>SizeAndTimeBasedFNATP</code>
1258 (logback-examples/src/main/resources/chapters/appenders/conf/logback-sizeAndTime.xml)</p>
1259
1260 <span class="asGroovy" onclick="return asGroovy('logback-sizeAndTime');">View as .groovy</span>
1261 <pre id="logback-sizeAndTime" class="prettyprint source">&lt;configuration>
1262 &lt;appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender">
1263 &lt;file>mylog.txt&lt;/file>
1264 &lt;rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
1265 &lt;!-- rollover daily -->
1266 &lt;fileNamePattern><b>mylog-%d{yyyy-MM-dd}.<span class="big">%i</span>.txt</b>&lt;/fileNamePattern>
1267 <b>&lt;!-- each file should be at most 100MB, keep 60 days worth of history, but at most 20GB --></b>
1268 <b>&lt;maxFileSize>100MB&lt;/maxFileSize></b>
1269 &lt;maxHistory>60&lt;/maxHistory>
1270 &lt;totalSizeCap>20GB&lt;/totalSizeCap>
1271 &lt;/rollingPolicy>
1272 &lt;encoder>
1273 &lt;pattern>%msg%n&lt;/pattern>
1274 &lt;/encoder>
1275 &lt;/appender>
1276
1277
1278 &lt;root level="DEBUG">
1279 &lt;appender-ref ref="ROLLING" />
1280 &lt;/root>
1281
1282 &lt;/configuration></pre>
1283
1284 <p>Note the "%i" conversion token in addition to "%d". <b>Both the
1285 %i and %d tokens are mandatory.</b> Each time the current log file
1286 reaches <span class="prop">maxFileSize</span> before the current
1287 time period ends, it will be archived with an increasing index,
1288 starting at 0.</p>
1289
1290 <p>Size and time based archiving supports deletion of old archive
1291 files. You need to specify the number of periods to preserve with
1292 the <span class="prop">maxHistory</span> property. When your
1293 application is stopped and restarted, logging will continue at the
1294 correct location, i.e. at the largest index number for the current
1295 period.
1296 </p>
1297
1298 <p>In versions prior to 1.1.7, this document mentioned a component
1299 called <code>SizeAndTimeBasedFNATP</code>. However, given that
1300 <code>SizeAndTimeBasedFNATP</code> offers a simpler configuration
1301 structure, we no longer document
1302 <code>SizeAndTimeBasedFNATP</code>. Nevertheless, earlier
1303 configuration files using <code>SizeAndTimeBasedFNATP</code> will
1304 continue to work just fine. In fact,
1305 <code>SizeAndTimeBasedRollingPolicy</code> is implemented with a
1306 <code>SizeAndTimeBasedFNATP</code> subcomponent.</p>
1307
1308 <h4 class="doAnchor" name="FixedWindowRollingPolicy">FixedWindowRollingPolicy</h4>
1309
1310 <p>When rolling over, <a
1311 href="../xref/ch/qos/logback/core/rolling/FixedWindowRollingPolicy.html">
1312 <code>FixedWindowRollingPolicy</code></a> renames files according
1313 to a fixed window algorithm as described below.
1314 </p>
1315
1316 <p>The <span class="prop">fileNamePattern</span> option
1317 represents the file name pattern for the archived (rolled over) log
1318 files. This option is required and must include an integer token
1319 <em>%i</em> somewhere within the pattern.
1320 </p>
1321
1322 <p>Here are the available properties for
1323 <code>FixedWindowRollingPolicy</code>
1324 </p>
1325
1326 <table class="bodyTable striped">
1327 <tr>
1328 <th>Property Name</th>
1329 <th>Type</th>
1330 <th>Description</th>
1331 </tr>
1332 <tr>
1333 <td><span class="prop" container="fwrp">minIndex</span></td>
1334 <td><code>int</code></td>
1335 <td>
1336 <p>This option represents the lower bound for the window's
1337 index.
1338 </p>
1339 </td>
1340 </tr>
1341 <tr>
1342 <td><span class="prop" container="fwrp">maxIndex</span></td>
1343 <td><code>int</code></td>
1344 <td>
1345 <p>This option represents the upper bound for the window's
1346 index.
1347 </p>
1348 </td>
1349 </tr>
1350 <tr>
1351 <td><span class="prop" container="fwrp">fileNamePattern</span></td>
1352 <td><code>String</code></td>
1353 <td>
1354 <p>This option represents the pattern that will be followed
1355 by the <code>FixedWindowRollingPolicy</code> when renaming
1356 the log files. It must contain the string <em>%i</em>, which
1357 will indicate the position where the value of the current
1358 window index will be inserted.
1359 </p>
1360 <p>For example, using <em>MyLogFile%i.log</em> associated
1361 with minimum and maximum values of <em>1</em> and <em>3</em>
1362 will produce archive files named <em>MyLogFile1.log</em>,
1363 <em>MyLogFile2.log</em> and <em>MyLogFile3.log</em>.
1364 </p>
1365 <p>Note that file compression is also specified via this
1366 property. For example, <span
1367 class="prop">fileNamePattern</span> set to
1368 <em>MyLogFile%i.log.zip</em> means that archived files must be
1369 compressed using the <em>zip</em> format; <em>gz</em> format
1370 is also supported.
1371 </p>
1372 </td>
1373 </tr>
1374 </table>
1375
1376 <p>Given that the fixed window rolling policy requires as many file
1377 renaming operations as the window size, large window sizes are
1378 strongly discouraged. When large values are specified by the user,
1379 the current implementation will automatically reduce the window
1380 size to 20.
1381 </p>
1382
1383 <p>Let us go over a more concrete example of the fixed window
1384 rollover policy. Suppose that <span class="prop">minIndex</span> is
1385 set to <em>1</em>, <span class="prop">maxIndex</span> set to
1386 <em>3</em>, <span class="prop">fileNamePattern</span> property set
1387 to <em>foo%i.log</em>, and that <span class="prop">file</span>
1388 property is set to <em>foo.log</em>.
1389 </p>
1390
1391 <table class="bodyTable striped">
1392 <tr>
1393 <th>Number of rollovers</th>
1394 <th>Active output target</th>
1395 <th>Archived log files</th>
1396 <th>Description</th>
1397 </tr>
1398 <tr>
1399 <td>0</td>
1400 <td>foo.log</td>
1401 <td>-</td>
1402 <td>No rollover has happened yet, logback logs into the initial
1403 file.
1404 </td>
1405 </tr>
1406 <tr>
1407 <td>1</td>
1408 <td>foo.log</td>
1409 <td>foo1.log</td>
1410 <td>First rollover. <em>foo.log</em> is renamed as
1411 <em>foo1.log</em>. A new <em>foo.log</em> file is created and
1412 becomes the active output target.
1413 </td>
1414 </tr>
1415 <tr>
1416 <td>2</td>
1417 <td>foo.log</td>
1418 <td>foo1.log, foo2.log</td>
1419 <td>Second rollover. <em>foo1.log</em> is renamed as
1420 <em>foo2.log</em>. <em>foo.log</em> is renamed as
1421 <em>foo1.log</em>. A new <em>foo.log</em> file is created and
1422 becomes the active output target.
1423 </td>
1424 </tr>
1425 <tr>
1426 <td>3</td>
1427 <td>foo.log</td>
1428 <td>foo1.log, foo2.log, foo3.log</td>
1429 <td>Third rollover. <em>foo2.log</em> is renamed as
1430 <em>foo3.log</em>. <em>foo1.log</em> is renamed as
1431 <em>foo2.log</em>. <em>foo.log</em> is renamed as
1432 <em>foo1.log</em>. A new <em>foo.log</em> file is created and
1433 becomes the active output target.
1434 </td>
1435 </tr>
1436 <tr>
1437 <td>4</td>
1438 <td>foo.log</td>
1439 <td>foo1.log, foo2.log, foo3.log</td>
1440 <td>In this and subsequent rounds, the rollover begins by
1441 deleting <em>foo3.log</em>. Other files are renamed by
1442 incrementing their index as shown in previous steps. In this and
1443 subsequent rollovers, there will be three archive logs and one
1444 active log file.
1445 </td>
1446 </tr>
1447 </table>
1448
1449 <p>The configuration file below gives an example of configuring
1450 <code>RollingFileAppender</code> and
1451 <code>FixedWindowRollingPolicy</code>. Note that the <span
1452 class="prop">File</span> option is mandatory even if it contains
1453 some of the same information as conveyed with the <span
1454 class="prop">fileNamePattern</span> option.
1455 </p>
1456
1457 <p class="example">Example: Sample configuration of a <code>RollingFileAppender</code> using a
1458 <code>FixedWindowRollingPolicy</code> (logback-examples/src/main/resources/chapters/appenders/conf/logback-RollingFixedWindow.xml)</p>
1459
1460 <span class="asGroovy" onclick="return asGroovy('logback-RollingFixedWindow');">View as .groovy</span>
1461 <pre id="logback-RollingFixedWindow" class="prettyprint source">&lt;configuration>
1462 &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
1463 <b>&lt;file>test.log&lt;/file></b>
1464
1465 <b>&lt;rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
1466 &lt;fileNamePattern>tests.%i.log.zip&lt;/fileNamePattern>
1467 &lt;minIndex>1&lt;/minIndex>
1468 &lt;maxIndex>3&lt;/maxIndex>
1469 &lt;/rollingPolicy></b>
1470
1471 &lt;triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
1472 &lt;maxFileSize>5MB&lt;/maxFileSize>
1473 &lt;/triggeringPolicy>
1474 &lt;encoder>
1475 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n&lt;/pattern>
1476 &lt;/encoder>
1477 &lt;/appender>
1478
1479 &lt;root level="DEBUG">
1480 &lt;appender-ref ref="FILE" />
1481 &lt;/root>
1482 &lt;/configuration></pre>
1483
1484
1485 <h2>
1486 <a name="TriggeringPolicy" href="#TriggeringPolicy">Overview of
1487 triggering policies</a>
1488 </h2>
1489
1490 <p><a
1491 href="../xref/ch/qos/logback/core/rolling/TriggeringPolicy.html"><code>TriggeringPolicy</code></a>
1492 implementations are responsible for instructing the
1493 <code>RollingFileAppender</code> when to rollover.</p>
1494
1495 <p>The <code>TriggeringPolicy</code> interface contains only one
1496 method.</p>
1497
1498 <pre class="prettyprint source">package ch.qos.logback.core.rolling;
1499
1500 import java.io.File;
1501 import ch.qos.logback.core.spi.LifeCycle;
1502
1503 public interface TriggeringPolicy&lt;E&gt; extends LifeCycle {
1504
1505 <b>public boolean isTriggeringEvent(final File activeFile, final &lt;E&gt; event);</b>
1506 }</pre>
1507
1508 <p>The <code>isTriggeringEvent()</code> method takes as parameters
1509 the active file and the logging event currently being
1510 processed. The concrete implementation determines whether the
1511 rollover should occur or not, based on these parameters.
1512 </p>
1513
1514 <p>The most widely-used triggering policy, namely
1515 <code>TimeBasedRollingPolicy</code> which also doubles as a
1516 rolling policy, was already <a
1517 href="#TimeBasedRollingPolicy">discussed earlier</a> along with
1518 other rolling policies. </p>
1519
1520 <h4><a name="SizeBasedTriggeringPolicy"
1521 href="#SizeBasedTriggeringPolicy">SizeBasedTriggeringPolicy</a></h4>
1522
1523 <p><a
1524 href="../xref/ch/qos/logback/core/rolling/SizeBasedTriggeringPolicy.html">
1525 <code>SizeBasedTriggeringPolicy</code></a> looks at the size of the
1526 currently active file. If it grows larger than the specified size,
1527 it will signal the owning <code>RollingFileAppender</code> to
1528 trigger the rollover of the existing active file.
1529 </p>
1530
1531 <p><code>SizeBasedTriggeringPolicy</code> accepts only one
1532 parameter, namely <span class="prop">maxFileSize</span>, with a
1533 default value of 10 MB.
1534 </p>
1535
1536 <p>The <span class="prop">maxFileSize</span> option can be
1537 specified in bytes, kilobytes, megabytes or gigabytes by suffixing
1538 a numeric value with <em>KB</em>, <em>MB</em> and respectively
1539 <em>GB</em>. For example, <em>5000000</em>, <em>5000KB</em>,
1540 <em>5MB</em> and <em>2GB</em> are all valid values, with the first
1541 three being equivalent.
1542 </p>
1543
1544 <p>Here is a sample configuration with a
1545 <code>RollingFileAppender</code> in conjunction with
1546 <code>SizeBasedTriggeringPolicy</code> triggering rollover when
1547 the log file reaches 5MB in size.
1548 </p>
1549
1550 <p class="example">Example: Sample configuration of a
1551 <code>RollingFileAppender</code> using a
1552 <code>SizeBasedTriggeringPolicy</code>
1553 (logback-examples/src/main/resources/chapters/appenders/conf/logback-RollingSizeBased.xml)</p>
1554
1555 <span class="asGroovy" onclick="return asGroovy('logback-RollingSizeBased');">View as .groovy</span>
1556 <pre id="logback-RollingSizeBased" class="prettyprint source">&lt;configuration>
1557 &lt;appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
1558 &lt;file>test.log&lt;/file>
1559 &lt;rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
1560 &lt;fileNamePattern>test.%i.log.zip&lt;/fileNamePattern>
1561 &lt;minIndex>1&lt;/minIndex>
1562 &lt;maxIndex>3&lt;/maxIndex>
1563 &lt;/rollingPolicy>
1564
1565 <b>&lt;triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
1566 &lt;maxFileSize>5MB&lt;/maxFileSize>
1567 &lt;/triggeringPolicy></b>
1568 &lt;encoder>
1569 &lt;pattern>%-4relative [%thread] %-5level %logger{35} - %msg%n&lt;/pattern>
1570 &lt;/encoder>
1571 &lt;/appender>
1572
1573 &lt;root level="DEBUG">
1574 &lt;appender-ref ref="FILE" />
1575 &lt;/root>
1576 &lt;/configuration></pre>
1577
1578
1579 <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXx -->
1580 <a name="Classic"></a>
1581 <h2>Logback Classic</h2>
1582
1583
1584 <p>While logging events are generic in logback-core, within
1585 logback-classic they are always instances of
1586 <code>ILoggingEvent</code>. Logback-classic is nothing more than a
1587 specialized processing pipeline handling instances of
1588 <code>ILoggingEvent</code>.
1589
1590 </p>
1591
1592 <h3 class="doAnchor" name="SocketAppender">SocketAppender and
1593 SSLSocketAppender
1594 </h3>
1595
1596 <p>The appenders covered thus far are only able to log to local
1597 resources. In contrast, the <a
1598 href="../xref/ch/qos/logback/classic/net/SocketAppender.html">
1599 <code>SocketAppender</code></a> is designed to log to a remote
1600 entity by transmitting serialized <code>ILoggingEvent</code>
1601 instances over the wire. When using <code>SocketAppender</code>
1602 logging events on the wire are sent in the clear. However, when
1603 using <a href="../xref/ch/qos/logback/classic/net/SSLSocketAppender.html">
1604 <code>SSLSocketAppender</code></a>, logging events are delivered over
1605 a secure channel.</p>
1606
1607 <p>
1608 The actual type of the serialized event
1609 is <a
1610 href="../xref/ch/qos/logback/classic/spi/LoggingEventVO.html"><code>LoggingEventVO</code></a>
1611 which implements the <code>ILoggingEvent</code>
1612 interface. Nevertheless, remote logging is non-intrusive as far as
1613 the logging event is concerned. On the receiving end after
1614 deserialization, the event can be logged as if it were generated
1615 locally. Multiple <code>SocketAppender</code> instances running on
1616 different machines can direct their logging output to a central
1617 log server whose format is fixed. <code>SocketAppender</code>
1618 does not take an associated layout because it sends serialized
1619 events to a remote server. <code>SocketAppender</code> operates
1620 above the <em>Transmission Control Protocol (TCP)</em> layer which
1621 provides a reliable, sequenced, flow-controlled end-to-end octet
1622 stream. Consequently, if the remote server is reachable, then log
1623 events will eventually arrive there. Otherwise, if the remote
1624 server is down or unreachable, the logging events will simply be
1625 dropped. If and when the server comes back up, then event
1626 transmission will be resumed transparently. This transparent
1627 reconnection is performed by a connector thread which periodically
1628 attempts to connect to the server.
1629 </p>
1630
1631 <p>Logging events are automatically buffered by the native TCP
1632 implementation. This means that if the link to server is slow but
1633 still faster than the rate of event production by the client, the
1634 client will not be affected by the slow network
1635 connection. However, if the network connection is slower than the
1636 rate of event production, then the client can only progress at the
1637 network rate. In particular, in the extreme case where the network
1638 link to the server is down, the client will be eventually blocked.
1639 Alternatively, if the network link is up, but the server is down,
1640 the client will not be blocked, although the log events will be
1641 lost due to server unavailability.
1642 </p>
1643
1644 <p>Even if a <code>SocketAppender</code> is no longer attached to
1645 any logger, it will not be garbage collected in the presence of a
1646 connector thread. A connector thread exists only if the
1647 connection to the server is down. To avoid this garbage
1648 collection problem, you should close the
1649 <code>SocketAppender</code> explicitly. Long lived applications
1650 which create/destroy many <code>SocketAppender</code> instances
1651 should be aware of this garbage collection problem. Most other
1652 applications can safely ignore it. If the JVM hosting the
1653 <code>SocketAppender</code> exits before the
1654 <code>SocketAppender</code> is closed, either explicitly or
1655 subsequent to garbage collection, then there might be
1656 untransmitted data in the pipe which may be lost. This is a common
1657 problem on Windows based systems. To avoid lost data, it is
1658 usually sufficient to <code>close()</code> the
1659 <code>SocketAppender</code> either explicitly or by calling the
1660 <code>LoggerContext</code>'s <code>stop()</code>
1661 method before exiting the application.
1662 </p>
1663
1664 <p>The remote server is identified by the <span
1665 class="prop">remoteHost</span> and <span
1666 class="prop">port</span> properties.
1667 <code>SocketAppender</code> properties are listed in the following
1668 table. <code>SSLSocketAppender</code> supports many additional
1669 configuration properties, which are detailed in the section
1670 entitled <a href="usingSSL.html">Using SSL</a>.
1671 </p>
1672
1673 <table class="bodyTable striped">
1674 <tr>
1675 <th>Property Name</th>
1676 <th>Type</th>
1677 <th>Description</th>
1678 </tr>
1679 <tr>
1680 <td><span class="prop" container="socket">includeCallerData</span></td>
1681 <td><code>boolean</code></td>
1682 <td>
1683 <p>
1684 The <span class="prop" container="socket">includeCallerData</span> option takes a boolean value.
1685 If true, the caller data will be available to the remote host.
1686 By default no caller data is sent to the server.
1687 </p>
1688 </td>
1689 </tr>
1690 <tr>
1691 <td><span class="prop" container="socket">port</span></td>
1692 <td><code>int</code></td>
1693 <td>
1694 <p>
1695 The port number of the remote server.
1696 </p>
1697 </td>
1698 </tr>
1699 <tr>
1700 <td><span class="prop"
1701 container="socket">reconnectionDelay</span></td>
1702 <td><code><a
1703 href="../apidocs/ch/qos/logback/core/util/Duration.html">Duration</a></code></td>
1704 <td>
1705 The <span class="prop">reconnectionDelay</span> option takes
1706 a duration string, such "10 seconds" representing the time
1707 to wait between each failed connection attempt to the
1708 server. The default value of this option is 30 seconds.
1709 Setting this option to zero turns off reconnection
1710 capability. Note that in case of successful connection to
1711 the server, there will be no connector thread present.
1712 </td>
1713 </tr>
1714 <tr>
1715 <td><span class="prop" container="socket">queueSize</span></td>
1716 <td><code>int</code></td>
1717 <td>
1718 <p>The <span class="prop">queueSize</span> property takes an
1719 integer (greater than zero) representing the number of logging
1720 events to retain for delivery to the remote receiver. When
1721 the queue size is one, event delivery to the remote
1722 receiver is synchronous. When the queue size is greater
1723 than one, new events are enqueued, assuming that there is
1724 space available in the queue. Using a queue length greater
1725 than one can improve performance by eliminating delays caused
1726 by transient network delays.
1727 </p>
1728
1729 <p>See also the <span class="prop">eventDelayLimit</span>
1730 property.</p>
1731
1732 </td>
1733 </tr>
1734
1735 <tr>
1736 <td><span class="prop" container="socket">eventDelayLimit</span></td>
1737 <td><code><a
1738 href="../apidocs/ch/qos/logback/core/util/Duration.html">Duration</a></code></td>
1739 <td>
1740 The <span class="prop">eventDelayLimit</span> option takes a
1741 duration string, such "10 seconds". It represents the time
1742 to wait before dropping events in case the local queue is
1743 full, i.e. already contains <span
1744 class="prop">queueSize</span> events. This may occur if the
1745 remote host is persistently slow accepting events. The
1746 default value of this option is 100 milliseconds.
1747 </td>
1748 </tr>
1749 <tr>
1750 <td><span class="prop" container="socket">remoteHost</span></td>
1751 <td><code>String</code></td>
1752 <td>
1753 The host name of the server.
1754 </td>
1755 </tr>
1756 <tr>
1757 <td><span class="prop" container="socket">ssl</span></td>
1758 <td><code>SSLConfiguration</code></td>
1759 <td>Supported only for <code>SSLSocketAppender</code>, this
1760 property provides the SSL configuration that will be used by
1761 the appender, as described in <a href="usingSSL.html">Using SSL</a>.
1762 </td>
1763 </tr>
1764 </table>
1765
1766 <h4>Logging Server Options</h4>
1767 <p>The standard Logback Classic distribution includes two options
1768 for servers that can be used to receive logging events from
1769 <code>SocketAppender</code> or <code>SSLSocketAppender</code>.</p>
1770 <ul>
1771 <li><code>ServerSocketReceiver</code> and its SSL-enabled
1772 counterpart <code>SSLServerSocketReceiver</code> are receiver
1773 components which can be configured in the <em>logback.xml</em>
1774 configuration file of an application in order receive events
1775 from a remote socket appender. See <a href="receivers.html">
1776 Receivers</a> for configuration details and usage examples.
1777 </li>
1778 <li><code>SimpleSocketServer</code> and its SSL-enabled counterpart
1779 <code>SimpleSSLSocketServer</code> both offer an
1780 easy-to-use standalone Java application that is designed to
1781 be configured and run from your shell's command line interface.
1782 These applications simply wait for logging events from
1783 <code>SocketAppender</code> or <code>SSLSocketAppender</code>
1784 clients. Each received event is logged according to local server
1785 policy. Usage examples are given below.
1786 </li>
1787 </ul>
1788
1789 <h4><a name="simpleSocketServer"></a>Using SimpleSocketServer</h4>
1790 <p>
1791 The <code>SimpleSocketServer</code> application takes two command-line
1792 arguments: <em>port</em> and <em>configFile</em>;
1793 where <em>port</em> is the port to listen on and
1794 <em>configFile</em> is a configuration script in XML format.
1795 </p>
1796
1797 <p>
1798 Assuming you are in the <em>logback-examples/</em> directory,
1799 start <code>SimpleSocketServer</code> with the following command:
1800 </p>
1801
1802 <p class="source">java ch.qos.logback.classic.net.SimpleSocketServer 6000 \
1803 src/main/java/chapters/appenders/socket/server1.xml</p>
1804
1805 <p>where 6000 is the port number to listen on and
1806 <em>server1.xml</em> is a configuration script that adds a
1807 <code>ConsoleAppender</code> and a
1808 <code>RollingFileAppender</code> to the root logger. After you
1809 have started <code>SimpleSocketServer</code>, you can send it log
1810 events from multiple clients using <code>SocketAppender</code>.
1811 The examples associated with this manual include two such clients:
1812 <code>chapters.appenders.SocketClient1</code> and
1813 <code>chapters.appenders.SocketClient2</code> Both clients wait for the user
1814 to type a line of text on the console. The text is encapsulated
1815 in a logging event of level debug and then sent to the remote
1816 server. The two clients differ in the configuration of the
1817 <code>SocketAppender</code>. <code>SocketClient1</code> configures
1818 the appender programmatically while <code>SocketClient2</code>
1819 requires a configuration file.
1820 </p>
1821
1822 <p>Assuming <code>SimpleSocketServer</code> is running on the
1823 local host, you connect to it with the following command:
1824 </p>
1825
1826 <p class="source">java chapters.appenders.socket.SocketClient1 localhost 6000</p>
1827
1828 <p>Each line that you type should appear on the console of the
1829 <code>SimpleSocketServer</code> launched in the previous step. If
1830 you stop and restart the <code>SimpleSocketServer</code> the
1831 client will transparently reconnect to the new server instance,
1832 although the events generated while disconnected will be simply
1833 (and irrevocably) lost.
1834 </p>
1835
1836 <p>
1837 Unlike
1838 <code>SocketClient1</code>, the sample application
1839 <code>SocketClient2</code> does not configure logback by itself.
1840 It requires a configuration file in XML format.
1841 The configuration file <em>client1.xml</em>
1842 shown below creates a <code>SocketAppender</code>
1843 and attaches it to the root logger.
1844 </p>
1845
1846 <p class="example">Example: SocketAppender configuration
1847 (logback-examples/src/main/resources/chapters/appenders/socket/client1.xml)</p>
1848 <span class="asGroovy" onclick="return asGroovy('client1');">View as .groovy</span>
1849 <pre id="client1" class="prettyprint source">&lt;configuration>
1850
1851 &lt;appender name="SOCKET" class="ch.qos.logback.classic.net.SocketAppender">
1852 &lt;remoteHost>${host}&lt;/remoteHost>
1853 &lt;port>${port}&lt;/port>
1854 &lt;reconnectionDelay>10000&lt;/reconnectionDelay>
1855 &lt;includeCallerData>${includeCallerData}&lt;/includeCallerData>
1856 &lt;/appender>
1857
1858 &lt;root level="DEBUG">
1859 &lt;appender-ref ref="SOCKET" />
1860 &lt;/root>
1861
1862 &lt;/configuration></pre>
1863
1864 <p>
1865 Note that in the above configuration scripts the values for the
1866 <span class="prop">remoteHost</span>, <span class="prop">port</span> and
1867 <span class="prop">includeCallerData</span> properties
1868 are not given directly but as substituted variable keys. The values for the variables
1869 can be specified as system properties:
1870 </p>
1871
1872 <p class="source">java -Dhost=localhost -Dport=6000 -DincludeCallerData=false \
1873 chapters.appenders.socket.SocketClient2 src/main/java/chapters/appenders/socket/client1.xml</p>
1874
1875 <p>This command should give similar results to the previous
1876 <code>SocketClient1</code>
1877 example.
1878 </p>
1879
1880 <p>Allow us to repeat for emphasis that serialization of logging
1881 events is not intrusive. A deserialized event carries the same
1882 information as any other logging event. It can be manipulated as
1883 if it were generated locally; except that serialized logging
1884 events by default do not include caller data. Here is an example
1885 to illustrate the point. First, start
1886 <code>SimpleSocketServer</code> with the following command:
1887 </p>
1888
1889 <p class="source"> java ch.qos.logback.classic.net.SimpleSocketServer 6000 \
1890 src/main/java/chapters/appenders/socket/server2.xml</p>
1891
1892 <p>The configuration file <em>server2.xml</em> creates a
1893 <code>ConsoleAppender</code> whose layout outputs the caller's file
1894 name and line number along with other information. If you run
1895 <code>SocketClient2</code> with the configuration file
1896 <em>client1.xml</em> as previously, you will notice that the output
1897 on the server side will contain two question marks between
1898 parentheses instead of the file name and the line number of the
1899 caller:
1900 </p>
1901
1902 <p class="source">2006-11-06 17:37:30,968 DEBUG [Thread-0] [?:?] chapters.appenders.socket.SocketClient2 - Hi</p>
1903
1904 <p>The outcome can be easily changed by instructing the
1905 <code>SocketAppender</code> to include caller data by setting the
1906 <span class="prop">includeCallerData</span> option to
1907 true. Using the following command will do the trick:
1908 </p>
1909
1910 <pre class="source">java -Dhost=localhost -Dport=6000 -DincludeCallerData=true \
1911 chapters.appenders.socket.SocketClient2 src/main/java/chapters/appenders/socket/client1.xml</pre>
1912
1913 <p>As deserialized events can be handled in the same way as
1914 locally generated events, they even can be sent to a second server
1915 for further treatment. As an exercise, you may wish to setup two
1916 servers where the first server tunnels the events it receives from
1917 its clients to a second server.
1918 </p>
1919
1920 <h4><a name="simpleSSLSocketServer"></a>Using SimpleSSLSocketServer</h4>
1921
1922 <p>The <code>SimpleSSLSocketServer</code> requires the same
1923 <em>port</em> and <em>configFile</em> command-line arguments used
1924 by <code>SimpleSocketServer</code>. Additionally, you must provide
1925 the location and password for your logging server's X.509 credential
1926 using system properties specified on the command line.
1927 </p>
1928
1929 <p>Assuming you are in the <em>logback-examples/</em> directory,
1930 start <code>SimpleSSLSocketServer</code> with the following command:
1931 </p>
1932
1933 <p class="source">java -Djavax.net.ssl.keyStore=src/main/java/chapters/appenders/socket/ssl/keystore.jks \
1934 -Djavax.net.ssl.keyStorePassword=changeit \
1935 ch.qos.logback.classic.net.SimpleSSLSocketServer 6000 \
1936 src/main/java/chapters/appenders/socket/ssl/server.xml
1937 </p>
1938
1939 <p>This example runs <code>SimpleSSLSocketServer</code> using an
1940 X.509 credential that is suitable for testing and experimentation,
1941 only. <strong>Before using <code>SimpleSSLSocketServer</code> in a
1942 production setting you should obtain an appropriate X.509 credential
1943 to identify your logging server</strong>. See
1944 <a href="usingSSL.html">Using SSL</a> for more details.
1945 </p>
1946
1947 <p>Because the server configuration has <code>debug="true"</code>
1948 specified on the root element, you'll will see in the server's
1949 startup logging the SSL configuration that will be used. This is
1950 useful in validating that local security policies are properly
1951 implemented.
1952 </p>
1953
1954 <p>With <code>SimpleSSLSocketServer</code> running, you can connect
1955 to the server using an <code>SSLSocketAppender</code>. The following
1956 example shows the appender configuration needed:
1957 </p>
1958
1959 <p class="example">Example: SSLSocketAppender configuration
1960 (logback-examples/src/main/resources/chapters/appenders/socket/ssl/client.xml)</p>
1961 <span class="asGroovy" onclick="return asGroovy('sslclient');">View as .groovy</span>
1962 <pre id="sslclient" class="prettyprint source">&lt;configuration debug="true">
1963
1964 &lt;appender name="SOCKET" class="ch.qos.logback.classic.net.SSLSocketAppender">
1965 &lt;remoteHost>${host}&lt;/remoteHost>
1966 &lt;port>${port}&lt;/port>
1967 &lt;reconnectionDelay>10000&lt;/reconnectionDelay>
1968 &lt;ssl>
1969 &lt;trustStore>
1970 &lt;location>${truststore}&lt;/location>
1971 &lt;password>${password}&lt;/password>
1972 &lt;/trustStore>
1973 &lt;/ssl>
1974 &lt;/appender>
1975
1976 &lt;root level="DEBUG">
1977 &lt;appender-ref ref="SOCKET" />
1978 &lt;/root>
1979
1980 &lt;/configuration></pre>
1981
1982 <p>Note that, just as in the previous example, the values for
1983 <span class="prop">remoteHost</span>, <span class="prop">port</span>
1984 are specified using substituted variable keys. Additionally, note
1985 the presence of the <span class="prop">ssl</span> property and its
1986 nested <span class="prop">trustStore</span> property, which specifies
1987 the location and password of a trust store using substituted
1988 variables. This configuration is necessary because our example
1989 server is using a self-signed certificate. See
1990 <a href="usingSSL.html">Using SSL</a> for more information on
1991 SSL configuration properties for <code>SSLSocketAppender</code>.
1992 </p>
1993
1994 <p>We can run a client application using this configuration by
1995 specifying the substitution variable values on the command line as
1996 system properties:
1997 </p>
1998
1999 <p class="source">java -Dhost=localhost -Dport=6000 \
2000 -Dtruststore=file:src/main/java/chapters/appenders/socket/ssl/truststore.jks \
2001 -Dpassword=changeit \
2002 chapters.appenders.socket.SocketClient2 src/main/java/chapters/appenders/socket/ssl/client.xml
2003 </p>
2004
2005 <p>As in the previous examples, you can type in a message when
2006 prompted by the client application, and the message will be delivered
2007 to the logging server (now over a secure channel) where it will be
2008 displayed on the console.
2009 </p>
2010
2011 <p>Note that the <em>truststore</em> property given on the command
2012 line specifies a file URL that identifies the location of the
2013 trust store. You may also use a classpath URL as described in <a
2014 href="usingSSL.html">Using SSL</a>.
2015 </p>
2016
2017 <p>As we saw previously at server startup, because the client
2018 configuration has <code>debug="true"</code> specified on the root
2019 element, the client's startup logging includes the details of the
2020 SSL configuration as aid to auditing local policy conformance.
2021 </p>
2022
2023
2024 <h3 class="doAnchor" name="serverSocketAppender">
2025 ServerSocketAppender and SSLServerSocketAppender</h3>
2026
2027 <p>The <code>SocketAppender</code> component (and its SSL-enabled
2028 counterpart) discussed previously are designed to allow an
2029 application to connect to a remote logging server over the network
2030 for the purpose of delivering logging events to the server. In
2031 some situations, it may be inconvenient or infeasible to have an
2032 application initiate a connection to a remote logging server. For
2033 these situations, Logback offers <a
2034 href="../xref/ch/qos/logback/classic/net/server/ServerSocketAppender">
2035 <code>ServerSocketAppender</code></a>.
2036 </p>
2037
2038 <p>Instead of initiating a connection to a remote logging server,
2039 <code>ServerSocketAppender</code> passively listens on a TCP socket
2040 awaiting incoming connections from remote clients. Logging events
2041 that are delivered to the appender are distributed to each connected
2042 client. Logging events that occur when no client is connected are
2043 <em>summarily discarded</em>.
2044 </p>
2045
2046 <p>In addition to the basic <code>ServerSocketAppender</code>, Logback
2047 offers <a href="../xref/ch/qos/logback/classic/net/server/SSLServerSocketAppender">
2048 <code>SSLServerSocketAppender</code></a>, which distributes logging events
2049 to each connected client using a secure, encrypted channel. Moreover, the
2050 SSL-enabled appender fully supports mutual certificate-based authentication,
2051 which can be used to ensure that only authorized clients can connect to
2052 the appender to receive logging events.
2053 </p>
2054
2055 <p>The approach to encoding logging events for transmission on the wire
2056 is identical to that used by <code>SocketAppender</code>; each event is
2057 a serialized instance of <code>ILoggingEvent</code>. Only the direction
2058 of connection initiation is reversed. While <code>SocketAppender</code>
2059 acts as the active peer in establishing the connection to a logging server,
2060 <code>ServerSocketAppender</code> is passive; it listens for
2061 incoming connections from clients.</p>
2062
2063 <p>The <code>ServerSocketAppender</code> subtypes are intended to be
2064 used exclusively with Logback <em>receiver</em> components. See
2065 <a href="receivers.html">Receivers</a> for additional information on
2066 this component type.</p>
2067
2068 <p>The following configuration properties are supported by
2069 <code>ServerSocketAppender</code>:</p>
2070
2071 <table class="bodyTable striped">
2072 <tr>
2073 <th>Property Name</th>
2074 <th>Type</th>
2075 <th>Description</th>
2076 </tr>
2077 <tr>
2078 <td><span class="prop" container="serverSocketAppender">address</span></td>
2079 <td><code>String</code></td>
2080 <td>The local network interface address on which the appender
2081 will listen. If this property is not specified, the appender
2082 will listen on all network interfaces.</td>
2083 </tr>
2084 <tr>
2085 <td><span class="prop" container="serverSocketAppender">includeCallerData</span></td>
2086 <td><code>boolean</code></td>
2087 <td>
2088 <p>
2089 If true, the caller data will be available to the remote host.
2090 By default no caller data is sent to the client.
2091 </p>
2092 </td>
2093 </tr>
2094 <tr>
2095 <td><span class="prop" container="serverSocketAppender">port</span></td>
2096 <td><code>int</code></td>
2097 <td>
2098 <p>
2099 The port number on which the appender will listen.
2100 </p>
2101 </td>
2102 </tr>
2103 <tr>
2104 <td><span class="prop" container="serverSocketAppender">ssl</span></td>
2105 <td><code>SSLConfiguration</code></td>
2106 <td>Supported only for <code>SSLServerSocketAppender</code>, this
2107 property provides the SSL configuration that will be used by
2108 the appender, as described in <a href="usingSSL.html">Using SSL</a>.
2109 </td>
2110 </tr>
2111 </table>
2112
2113 <p>The following example illustrates a configuration that uses
2114 <code>ServerSocketAppender</code>:
2115 </p>
2116
2117 <p class="example">Example: Basic ServerSocketAppender Configuration
2118 (logback-examples/src/main/resources/chapters/appenders/socket/server4.xml)</p>
2119 <pre id="SocketReceiver" class="prettyprint source">&lt;configuration debug="true">
2120 &lt;appender name="SERVER"
2121 class="ch.qos.logback.classic.net.server.ServerSocketAppender">
2122 &lt;port>${port}&lt;/port>
2123 &lt;includeCallerData>${includeCallerData}&lt;/includeCallerData>
2124 &lt;/appender>
2125
2126 &lt;root level="debug">
2127 &lt;appender-ref ref="SERVER" />
2128 &lt;/root>
2129
2130 &lt;/configuration>
2131 </pre>
2132 <p>Note that this configuration differs from previous examples using
2133 <code>SocketAppender</code> only in the <em>class</em> specified for
2134 the appender, and in the absence of the <span class="prop">remoteHost</span>
2135 property &mdash; this appender waits passively for inbound connections
2136 from remote hosts rather than opening a connection to a remote logging
2137 server.
2138 </p>
2139
2140 <p>The following example illustrates a configuration using
2141 <code>SSLServerSocketAppender</code>.</p>
2142
2143 <p class="example">Example: Basic SSLServerSocketAppender Configuration
2144 (logback-examples/src/main/resources/chapters/appenders/socket/ssl/server3.xml)</p>
2145 <pre id="SocketReceiver" class="prettyprint source">&lt;configuration debug="true">
2146 &lt;appender name="SERVER"
2147 class="ch.qos.logback.classic.net.server.SSLServerSocketAppender">
2148 &lt;port>${port}&lt;/port>
2149 &lt;includeCallerData>${includeCallerData}&lt;/includeCallerData>
2150 &lt;ssl>
2151 &lt;keyStore>
2152 &lt;location>${keystore}&lt;/location>
2153 &lt;password>${password}&lt;/password>
2154 &lt;/keyStore>
2155 &lt;/ssl>
2156 &lt;/appender>
2157
2158 &lt;root level="debug">
2159 &lt;appender-ref ref="SERVER" />
2160 &lt;/root>
2161
2162 &lt;/configuration>
2163 </pre>
2164
2165 <p>The principal differences between this configuration and the
2166 previous configuration is that the appender's <em>class</em> attribute
2167 identifies the <code>SSLServerSocketAppender</code> type, and the
2168 presence of the nested <span class="prop">ssl</span> element which
2169 specifies, in this example, configuration of a key store containing
2170 an X.509 credential for the appender. See <a href="usingSSL.html">
2171 Using SSL</a> for information regarding SSL configuration properties.
2172 </p>
2173
2174 <p>Because the <code>ServerSocketAppender</code> subtypes are designed
2175 to be used with receiver components, we will defer presenting
2176 illustrative examples to the chapter entitled
2177 <a href="receivers.html">Receivers</a>.</p>
2178
2179 <h3 class="doAnchor">SMTPAppender</h3>
2180
2181 <p>The <a
2182 href="../xref/ch/qos/logback/classic/net/SMTPAppender.html"><code>SMTPAppender</code></a>
2183 accumulates logging events in one or more fixed-size buffers and
2184 sends the contents of the appropriate buffer in an email after a
2185 user-specified event occurs. SMTP email transmission (sending) is
2186 performed asynchronously. By default, the email transmission is
2187 triggered by a logging event of level ERROR. Moreover, by default,
2188 a single buffer is used for all events.
2189 </p>
2190
2191 <p>The various properties for <code>SMTPAppender</code> are
2192 summarized in the following table.
2193 </p>
2194
2195 <table class="bodyTable striped">
2196 <tr>
2197 <th>Property Name</th>
2198 <th>Type</th>
2199 <th>Description</th>
2200 </tr>
2201
2202 <tr>
2203 <td><span class="prop" container="smtp">smtpHost</span></td>
2204 <td><code>String</code></td>
2205 <td>The host name of the SMTP server. This parameter is mandatory.</td>
2206 </tr>
2207
2208 <tr>
2209 <td><span class="prop" container="smtp">smtpPort</span></td>
2210 <td><code>int</code></td>
2211 <td>The port where the SMTP server is listening. Defaults to
2212 25.</td>
2213 </tr>
2214
2215 <tr>
2216 <td><span class="prop" name="smtpTo">to</span></td>
2217 <td><code>String</code></td>
2218 <td>The email address of the recipient as a
2219 <em>pattern</em>. The pattern is evaluated anew with the
2220 triggering event as input for each outgoing email. Multiple
2221 recipients can be specified by separating the destination
2222 addresses with commas. Alternatively, multiple recipients can
2223 also be specified by using multiple <code>&lt;to></code>
2224 elements.
2225 </td>
2226 </tr>
2227
2228 <tr>
2229 <td><span class="prop" container="smtp">from</span></td>
2230 <td><code>String</code></td>
2231 <td>The originator of the email messages sent by
2232 <code>SMTPAppender</code> in the <a
2233 href="http://en.wikipedia.org/wiki/Email_address">usual email
2234 address format</a>. If you wish to include the sender's name,
2235 then use the format
2236 "Adam&nbsp;Smith&nbsp;&amp;lt;[email protected]&amp;gt;" so that
2237 the message appears as originating from
2238 "Adam&nbsp;Smith&nbsp;&lt;[email protected]&gt;".
2239 </td>
2240 </tr>
2241 <tr>
2242 <td><span class="prop">subject</span></td>
2243 <td><code>String</code></td>
2244 <td>
2245 <p>The subject of the email. It can be any value accepted as
2246 a valid conversion pattern by <a
2247 href="layouts.html#ClassicPatternLayout">PatternLayout</a>. Layouts
2248 will be discussed in the next chapter.
2249 </p>
2250
2251 <p>The outgoing email message will have a subject line
2252 corresponding to applying the pattern on the logging event
2253 that triggered the email message.
2254 </p>
2255
2256 <p>Assuming the <span class="prop">subject</span> option
2257 is set to "Log: %logger - %msg" and the triggering event's
2258 logger is named "com.foo.Bar", and contains the message
2259 "Hello world", then the outgoing email will have the subject
2260 line "Log: com.foo.Bar - Hello World".
2261 </p>
2262
2263 <p>By default, this option is set to "%logger{20} - %m".</p>
2264 </td>
2265
2266 </tr>
2267 <tr>
2268 <td><span class="prop" container="smtp">discriminator</span></td>
2269 <td><code><a href="../xref/ch/qos/logback/core/sift/Discriminator.html">Discriminator</a></code></td>
2270 <td>
2271 <p>With the help of a <span
2272 class="prop">Discriminator</span>,
2273 <code>SMTPAppender</code> can scatter incoming events into
2274 different buffers according to the value returned by the
2275 discriminator. The default discriminator always returns the
2276 same value so that the same buffer is used for all events.
2277 </p>
2278
2279 <p>By specifying a discriminator other than the default
2280 one, it is possible to receive email messages
2281 containing a events pertaining to a particular user, user
2282 session or client IP address.
2283 </p>
2284 </td>
2285 </tr>
2286 <tr>
2287 <td><span class="prop" name="smtpAppender_Evaluator">evaluator</span></td>
2288 <td><code><a
2289 href="../xref/ch/qos/logback/classic/boolex/IEvaluator.html">IEvaluator</a></code></td>
2290 <td>
2291 <p>This option is declared by creating a new
2292 <code>&lt;EventEvaluator/></code> element. The name of the
2293 class that the user wishes to use as the
2294 <code>SMTPAppender</code>'s <code>Evaluator</code> needs
2295 to be specified via the <span class="attr">class</span>
2296 attribute.
2297 </p>
2298
2299
2300 <p>In the absence of this option, <code>SMTPAppender</code>
2301 is assigned an instance of <a
2302 href="../xref/ch/qos/logback/classic/boolex/OnErrorEvaluator.html">OnErrorEvaluator</a>
2303 which triggers email transmission when it encounters an
2304 event of level <em>ERROR</em> or higher.
2305 </p>
2306
2307 <!--
2308 <p><code>EventEvaluator</code> objects are subclasses of the
2309 <code>JaninoEventEvaluatorBase</code> which depends on
2310 Janino. See the <a href="../dependencies.html">dependencies
2311 page</a> for more information.
2312 </p>
2313 -->
2314
2315 <p>Logback ships with several other evaluators, namely <a
2316 href="../xref/ch/qos/logback/classic/boolex/OnMarkerEvaluator.html"><code>OnMarkerEvaluator</code></a>
2317 (discussed below) and a powerful evaluator called <a
2318 href="../xref/ch/qos/logback/classic/boolex/JaninoEventEvaluator.html"><code>JaninoEventEvaluator</code></a>,
2319 discussed in <a href="filters.html#evalutatorFilter">another
2320 chapter</a>. The more recent versions of logback ship with
2321 an even more powerful evaluator called <a
2322 href="filters.html#GEventEvaluator"><code>GEventEvaluator</code></a>.
2323 </p>
2324
2325 </td>
2326 </tr>
2327
2328 <tr>
2329 <td valign="top"><span class="prop" container="smtp">cyclicBufferTracker</span></td>
2330 <td><a href="../xref/ch/qos/logback/core/spi/CyclicBufferTracker.html"><code>CyclicBufferTracker</code></a>
2331 </td>
2332 <td>
2333 <p>As the name indicates, an instance of the
2334 <code>CyclicBufferTracker</code> class tracks cyclic
2335 buffers. It does so based on the keys returned by the <span
2336 class="prop">discriminator</span> (see above).
2337 </p>
2338 <p>If you don't specify a <span
2339 class="prop">cyclicBufferTracker</span>, an instance of <a
2340 href="../xref/ch/qos/logback/core/spi/CyclicBufferTracker.html">CyclicBufferTracker</a>
2341 will be automatically created. By default, this instance
2342 will keep events in a cyclic buffer of size 256. You may
2343 change the size with the help of the <span
2344 class="prop">bufferSize</span> option (see below).</p>
2345 </td>
2346 </tr>
2347 <tr>
2348 <td><span class="prop" container="smtp">username</span></td>
2349 <td><code>String</code></td> <td>The username value to use
2350 during plain user/password authentication. By default, this
2351 parameter is null. </td>
2352 </tr>
2353 <tr class="alt">
2354 <td><span class="prop" container="smtp">password</span></td>
2355 <td><code>String</code></td>
2356 <td>The password value to use for plain user/password
2357 authentication. By default, this parameter is null.
2358 </td>
2359 </tr>
2360 <tr>
2361 <td><span class="prop" container="smtp">STARTTLS</span> </td>
2362 <td><code>boolean</code></td>
2363 <td>If this parameter is set to true, then this appender
2364 will issue the STARTTLS command (if the server supports it)
2365 causing the connection to switch to SSL. Note that the
2366 connection is initially non-encrypted. By default, this
2367 parameter is set to false.
2368 </td>
2369 </tr>
2370 <tr>
2371 <td><span class="prop" container="smtp">SSL</span></td>
2372 <td><code>boolean</code></td> <td>If this parameter is set to
2373 true, then this appender will open an SSL connection to the
2374 server. By default, this parameter is set to false. </td>
2375 </tr>
2376
2377 <tr>
2378 <td><span class="prop" container="smtp">charsetEncoding</span></td>
2379 <td><code>String</code></td>
2380 <td>The outgoing email message will be encoded in the
2381 designated <a
2382 href="https://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html">charset</a>. The
2383 default charset encoding is "UTF-8" which works well for most
2384 purposes.
2385 </td>
2386 </tr>
2387
2388
2389 <tr>
2390 <td><span class="prop" container="smtp">localhost</span></td>
2391 <td><code>String</code></td>
2392 <td>In case the hostname of the SMTP client is not properly
2393 configured, e.g. if the client hostname is not fully
2394 qualified, certain SMTP servers may reject the HELO/EHLO
2395 commands sent by the client. To overcome this issue, you may
2396 set the value of the <span class="prop">localhost</span>
2397 property to the fully qualified name of the client host. See
2398 also the "mail.smtp.localhost" property in the documentation
2399 for the <a
2400 href="http://javamail.kenai.com/nonav/javadocs/com/sun/mail/smtp/package-summary.html">com.sun.mail.smtp</a>
2401 package.</td>
2402 </tr>
2403
2404 <tr>
2405 <td><span class="prop" container="smtp">asynchronousSending</span></td>
2406 <td><code>boolean</code></td>
2407 <td>This property determines whether email transmission is
2408 done asynchronously or not. By default, the <span
2409 class="prop">asynchronousSending</span> property is
2410 'true'. However, under certain circumstances asynchronous
2411 sending may be inappropriate. For example if your application
2412 uses <code>SMTPAppender</code> to send alerts in response to a
2413 fatal error, and then exits, the relevant thread may not have
2414 the time to send the alert email. In this case, set <span
2415 class="prop">asynchronousSending</span> property to 'false'
2416 for synchronous email transmission.
2417 </td>
2418 </tr>
2419
2420 <tr>
2421 <td><span class="prop" container="smtp">includeCallerData</span></td>
2422 <td><code>boolean</code></td>
2423 <td>By default, <span class="prop">includeCallerData</span> is
2424 set to <code>false</code>. You should set <span
2425 class="prop">includeCallerData</span> to <code>true</code> if
2426 <span class="prop">asynchronousSending</span> is enabled and
2427 you wish to include caller data in the logs. </td>
2428 </tr>
2429
2430 <tr>
2431 <td><span class="prop" container="smtp">sessionViaJNDI</span></td>
2432 <td><code>boolean</code></td>
2433 <td><code>SMTPAppender</code> relies on
2434 <code>javax.mail.Session</code> to send out email messages. By
2435 default, <span class="prop">sessionViaJNDI</span> is set to
2436 <code>false</code> so the <code>javax.mail.Session</code>
2437 instance is built by <code>SMTPAppender</code> itself with the
2438 properties specified by the user. If the <span
2439 class="prop">sessionViaJNDI</span> property is set to
2440 <code>true</code>, the <code>javax.mail.Session</code> object
2441 will be retrieved via JNDI. See also the <span
2442 class="prop">jndiLocation</span> property.
2443
2444 <p>Retrieving the <code>Session</code> via JNDI can reduce the
2445 number of places you need to configure/reconfigure the same
2446 information, making your application <a
2447 href="http://en.wikipedia.org/wiki/Don't_repeat_yourself">dryer</a>. For
2448 more information on configuring resources in Tomcat see <a
2449 href="http://tomcat.apache.org/tomcat-6.0-doc/jndi-resources-howto.html#JavaMail_Sessions">JNDI
2450 Resources How-to</a>. <span class="label">beware</span> As
2451 noted in that document, make sure to remove <em>mail.jar</em>
2452 and <em>activation.jar</em> from your web-applications
2453 <em>WEB-INF/lib</em> folder when retrieving the
2454 <code>Session</code> from JNDI.
2455 </p>
2456 </td>
2457 </tr>
2458
2459 <tr>
2460 <td><span class="prop" container="smtp">jndiLocation</span></td>
2461 <td><code>String</code></td>
2462 <td>The location where the javax.mail.Session is placed in
2463 JNDI. By default, <span class="prop">jndiLocation</span> is
2464 set to <span style="white-space:nowrap">"java:comp/env/mail/Session"</span>.
2465 </td>
2466 </tr>
2467
2468 </table>
2469
2470 <p>The <code>SMTPAppender</code> keeps only the last 256 logging
2471 events in its cyclic buffer, throwing away older events when its
2472 buffer becomes full. Thus, the number of logging events delivered
2473 in any e-mail sent by <code>SMTPAppender</code> is upper-bounded
2474 by 256. This keeps memory requirements bounded while still
2475 delivering a reasonable amount of application context.
2476 </p>
2477
2478 <p>The <code>SMTPAppender</code> relies on the JavaMail API. It
2479 has been tested with JavaMail API version 1.4. The JavaMail API
2480 requires the JavaBeans Activation Framework package. You can
2481 download the <a
2482 href="http://java.sun.com/products/javamail/">JavaMail API</a> and
2483 the <a
2484 href="http://java.sun.com/beans/glasgow/jaf.html">JavaBeans
2485 Activation Framework</a> from their respective websites. Make
2486 sure to place these two jar files in the classpath before trying
2487 the following examples.
2488 </p>
2489
2490 <p>A sample application, <a
2491 href="../xref/chapters/appenders/mail/EMail.html"><code>chapters.appenders.mail.EMail</code></a>
2492 generates a number of log messages followed by a single
2493 error message. It takes two parameters. The first parameter is an
2494 integer corresponding to the number of logging events to
2495 generate. The second parameter is the logback configuration
2496 file. The last logging event generated by <em>EMail</em>
2497 application, an ERROR, will trigger the transmission of an email
2498 message.
2499 </p>
2500
2501 <p>Here is a sample configuration file intended for the
2502 <code>Email</code> application:
2503 </p>
2504
2505 <p class="example">Example: A sample <code>SMTPAppender</code> configuration (logback-examples/src/main/resources/chapters/appenders/mail/mail1.xml)</p>
2506 <span class="asGroovy" onclick="return asGroovy('mail1');">View as .groovy</span>
2507 <pre id="mail1" class="prettyprint source">&lt;configuration>
2508 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2509 &lt;smtpHost>ADDRESS-OF-YOUR-SMTP-HOST&lt;/smtpHost>
2510 &lt;to>EMAIL-DESTINATION&lt;/to>
2511 &lt;to>ANOTHER_EMAIL_DESTINATION&lt;/to> &lt;!-- additional destinations are possible --&gt;
2512 &lt;from>SENDER-EMAIL&lt;/from>
2513 &lt;subject>TESTING: %logger{20} - %m&lt;/subject>
2514 &lt;layout class="ch.qos.logback.classic.PatternLayout">
2515 &lt;pattern>%date %-5level %logger{35} - %message%n&lt;/pattern>
2516 &lt;/layout>
2517 &lt;/appender>
2518
2519 &lt;root level="DEBUG">
2520 &lt;appender-ref ref="EMAIL" />
2521 &lt;/root>
2522 &lt;/configuration></pre>
2523
2524 <p>Before trying out <code>chapters.appenders.mail.Email</code> application
2525 with the above configuration file, you must set the <span
2526 class="prop">smtpHost</span>, <span class="prop">to</span> and
2527 <span class="prop">from</span> properties to values appropriate for
2528 your environment. Once you have set the correct values in the
2529 configuration file, execute the following command:
2530 </p>
2531
2532 <div class="source"><pre>java chapters.appenders.mail.EMail 100 src/main/java/chapters/appenders/mail/mail1.xml</pre></div>
2533
2534 <p>The recipient you specified should receive an email message
2535 containing 100 logging events formatted by
2536 <code>PatternLayout</code> The figure below is the resulting email
2537 message as shown by Mozilla Thunderbird.
2538 </p>
2539
2540 <p><img src="images/chapters/appenders/smtpAppender1.jpg" alt="resulting email"/></p>
2541
2542 <p>In the next example configuration file <em>mail2.xml</em>, the
2543 values for the <span class="prop">smtpHost</span>, <span
2544 class="prop">to</span> and <span class="prop">from</span>
2545 properties are determined by variable substitution. Here is the
2546 relevant part of <em>mail2.xml</em>.
2547 </p>
2548
2549 <pre class="prettyprint source">&lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2550 &lt;smtpHost>${smtpHost}&lt;/smtpHost>
2551 &lt;to>${to}&lt;/to>
2552 &lt;from>${from}&lt;/from>
2553 &lt;layout class="ch.qos.logback.classic.html.HTMLLayout"/>
2554 &lt;/appender></pre>
2555
2556 <p>You can pass the required parameters on the command line:</p>
2557
2558 <div class="source"><pre>java [email protected] [email protected] -DsmtpHost=some_smtp_host \
2559 chapters.appenders.mail.EMail 10000 src/main/java/chapters/appenders/mail/mail2.xml
2560 </pre></div>
2561
2562 <p>Be sure to replace with values as appropriate for your
2563 environment.
2564 </p>
2565
2566 <p>Note that in this latest example, <code>PatternLayout</code>
2567 was replaced by <code>HTMLLayout</code> which formats logs as an
2568 HTML table. You can change the list and order of columns as well
2569 as the CSS of the table. Please refer to <a
2570 href="layouts.html#ClassicHTMLLayout">HTMLLayout</a> documentation
2571 for further details.
2572 </p>
2573
2574 <p>Given that the size of the cyclic buffer is 256, the recipient
2575 should see an email message containing 256 events conveniently
2576 formatted in an HTML table. Note that this run of the
2577 <code>chapters.appenders.mail.Email</code> application generated
2578 10'000 events of which only the last 256 were included in the
2579 outgoing email.
2580 </p>
2581
2582 <p><img src="images/chapters/appenders/smtpAppender2.jpg" alt="2nd email"/></p>
2583
2584 <p>Email clients such as Mozilla Thunderbird, Eudora or MS
2585 Outlook, offer reasonably good CSS support for HTML email.
2586 However, they sometimes automatically downgrade HTML to
2587 plaintext. For example, to view HTML email in Thunderbird, the
2588 "View&rarr;Message&nbsp;Body&nbsp;As&rarr;Original HTML" option
2589 must be set. Yahoo! Mail's support for HTML email, in particular
2590 its CSS support is very good. Gmail on the other hand, while it
2591 honors the basic HTML table structure, ignores the internal CSS
2592 formatting. Gmail supports inline CSS formatting but since inline
2593 CSS would make the resulting output too voluminous,
2594 <code>HTMLLayout</code> does not use inline CSS.
2595 </p>
2596
2597 <h3 class="doAnchor" name="cyclicBufferSize">Custom buffer
2598 size</h3>
2599
2600 <p>By default, the outgoing message will contain the last 256
2601 messages seen by <code>SMTPAppender</code>. If your heart so
2602 desires, you may set a different buffer size as shown in the next example.
2603 </p>
2604
2605 <p class="example">Example: <code>SMTPAppender</code> configuration with a custom bufer size (logback-examples/src/main/resources/chapters/appenders/mail/customBufferSize.xml)</p>
2606 <pre class="prettyprint source">&lt;configuration>
2607 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2608 &lt;smtpHost>${smtpHost}&lt;/smtpHost>
2609 &lt;to>${to}&lt;/to>
2610 &lt;from>${from}&lt;/from>
2611 &lt;subject>%logger{20} - %m&lt;/subject>
2612 &lt;layout class="ch.qos.logback.classic.html.HTMLLayout"/>
2613
2614 <b>&lt;cyclicBufferTracker class="ch.qos.logback.core.spi.CyclicBufferTracker"></b>
2615 <b>&lt;!-- send just one log entry per email --></b>
2616 <b>&lt;bufferSize>1&lt;/bufferSize></b>
2617 <b>&lt;/cyclicBufferTracker></b>
2618 &lt;/appender>
2619
2620 &lt;root level="DEBUG">
2621 &lt;appender-ref ref="EMAIL" />
2622 &lt;/root>
2623 &lt;/configuration> </pre>
2624
2625
2626 <h3 class="doAnchor">Triggering event</h3>
2627
2628 <p>If the Evaluator property is not set, the
2629 <code>SMTPAppender</code> defaults to an <a
2630 href="../xref/ch/qos/logback/classic/boolex/OnErrorEvaluator.html">OnErrorEvaluator</a>
2631 instance which triggers email transmission when it encounters an
2632 event of level ERROR. While triggering an outgoing email in
2633 response to an error is relatively reasonable, it is possible to
2634 override this default behavior by providing a different
2635 implementation of the <code>EventEvaluator</code> interface.
2636 </p>
2637
2638 <p>The <code>SMTPAppender</code> submits each incoming event to
2639 its evaluator by calling <code>evaluate()</code> method in order
2640 to check whether the event should trigger an email or just be
2641 placed in the cyclic buffer. When the evaluator gives a positive
2642 answer to its evaluation, an email is sent out. The
2643 <code>SMTPAppender</code> contains one and only one evaluator
2644 object. This object may manage its own internal state. For
2645 illustrative purposes, the <code>CounterBasedEvaluator</code>
2646 class listed next implements an event evaluator whereby every
2647 1024th event triggers an email message.
2648 </p>
2649
2650 <p class="example">Example: A <code>EventEvaluator</code> implementation
2651 that evaluates to <code>true</code> every 1024th event (<a href="../xref/chapters/appenders/mail/CounterBasedEvaluator.html">logback-examples/src/main/java/chapters/appenders/mail/CounterBasedEvaluator.java</a>)</p>
2652
2653 <pre class="prettyprint source">package chapters.appenders.mail;
2654
2655 import ch.qos.logback.core.boolex.EvaluationException;
2656 import ch.qos.logback.core.boolex.EventEvaluator;
2657 import ch.qos.logback.core.spi.ContextAwareBase;
2658
2659 public class CounterBasedEvaluator extends ContextAwareBase implements EventEvaluator {
2660
2661 static int LIMIT = 1024;
2662 int counter = 0;
2663 String name;
2664
2665 <b>public boolean evaluate(Object event) throws NullPointerException,
2666 EvaluationException {
2667 counter++;
2668
2669 if (counter == LIMIT) {
2670 counter = 0;
2671
2672 return true;
2673 } else {
2674 return false;
2675 }
2676 }</b>
2677
2678 public String getName() {
2679 return name;
2680 }
2681
2682 public void setName(String name) {
2683 this.name = name;
2684 }
2685 }</pre>
2686
2687 <p>Note that this class extends <code>ContextAwareBase</code> and
2688 implements <code>EventEvaluator</code>. This allows the user to
2689 concentrate on the core functions of her
2690 <code>EventEvaluator</code> and let the base class provide the
2691 common functionality.
2692 </p>
2693
2694 <p>Setting the <span class="prop">Evaluator</span> option of
2695 <code>SMTPAppender</code> instructs it to use a custom evaluator.
2696 The next configuration file attaches a <code>SMTPAppender</code>
2697 to the root logger. This appender uses a
2698 <code>CounterBasedEvaluator</code> instance as its event
2699 evaluator.
2700 </p>
2701
2702 <p class="example">Example: <code>SMTPAppender</code> with custom
2703 <code>Evaluator</code> and buffer size (logback-examples/src/main/resources/chapters/appenders/mail/mail3.xml)</p>
2704 <span class="asGroovy" onclick="return asGroovy('mail3');">View as .groovy</span>
2705 <pre id="mail3" class="prettyprint source">&lt;configuration>
2706 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2707 <b>&lt;evaluator class="chapters.appenders.mail.CounterBasedEvaluator" /></b>
2708 &lt;smtpHost>${smtpHost}&lt;/smtpHost>
2709 &lt;to>${to}&lt;/to>
2710 &lt;from>${from}&lt;/from>
2711 &lt;subject>%logger{20} - %m&lt;/subject>
2712
2713 &lt;layout class="ch.qos.logback.classic.html.HTMLLayout"/>
2714 &lt;/appender>
2715
2716 &lt;root level="DEBUG">
2717 &lt;appender-ref ref="EMAIL" />
2718 &lt;/root>
2719 &lt;/configuration></pre>
2720
2721
2722 <h3 class="doAnchor" name="OnMarkerEvaluator">Marker based
2723 triggering </h3>
2724
2725 <p>Although reasonable, the default triggering policy whereby every
2726 event of level ERROR triggers an outgoing email may result in too
2727 many emails, cluttering the targeted user's mailbox. Logback ships
2728 with another triggering policy, called <a
2729 href="../xref/ch/qos/logback/classic/boolex/OnMarkerEvaluator.html">OnMarkerEvaluator</a>. It
2730 is based on markers. In essence, emails are triggered only if the
2731 event is marked with a user-specified marker. The next example
2732 should make the point clearer.
2733 </p>
2734
2735 <p>The <a
2736 href="../xref/chapters/appenders/mail/Marked_EMail.html">Marked_EMail</a>
2737 application contains several logging statements some of which are
2738 of level ERROR. One noteworthy statement contains a marker. Here
2739 is the relevant code.
2740 </p>
2741
2742 <pre class="prettyprint source">Marker notifyAdmin = MarkerFactory.getMarker("NOTIFY_ADMIN");
2743 logger.error(<b>notifyAdmin</b>,
2744 "This is a serious an error requiring the admin's attention",
2745 new Exception("Just testing"));</pre>
2746
2747 <p>The next configuration file will trigger outgoing emails only in
2748 presence of events bearing the NOTIFY_ADMIN or the
2749 TRANSACTION_FAILURE markers.
2750 </p>
2751
2752 <p class="example">Example: <code>SMTPAppender</code> with
2753 <code>OnMarkerEvaluator</code> (logback-examples/src/main/resources/chapters/appenders/mail/mailWithMarker.xml)</p>
2754
2755 <span class="asGroovy" onclick="return asGroovy('mailWithMarker');">View as .groovy</span>
2756 <pre id="mailWithMarker" class="prettyprint source">&lt;configuration>
2757 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2758 <b>&lt;evaluator class="ch.qos.logback.classic.boolex.OnMarkerEvaluator">
2759 &lt;marker>NOTIFY_ADMIN&lt;/marker>
2760 &lt;!-- you specify add as many markers as you want -->
2761 &lt;marker>TRANSACTION_FAILURE&lt;/marker>
2762 &lt;/evaluator></b>
2763 &lt;smtpHost>${smtpHost}&lt;/smtpHost>
2764 &lt;to>${to}&lt;/to>
2765 &lt;from>${from}&lt;/from>
2766 &lt;layout class="ch.qos.logback.classic.html.HTMLLayout"/>
2767 &lt;/appender>
2768
2769 &lt;root>
2770 &lt;level value ="debug"/>
2771 &lt;appender-ref ref="EMAIL" />
2772 &lt;/root>
2773 &lt;/configuration></pre>
2774
2775 <p>Give it a whirl with the following command:</p>
2776
2777 <pre class="source">java [email protected] [email protected] -DsmtpHost=some_smtp_host \
2778 chapters.appenders.mail.Marked_EMail src/main/java/chapters/appenders/mail/mailWithMarker.xml</pre>
2779
2780
2781 <h4 class="doAnchor" name="marker_JaninoEventEvaluator">Marker-based
2782 triggering with JaninoEventEvaluator</h4>
2783
2784 <p>Note that instead of using the marker-centric
2785 <code>OnMarkerEvaluator</code>, we could use the much more generic
2786 <a
2787 href="filters.html#JaninoEventEvaluator"><code>JaninoEventEvaluator</code></a>
2788 or its even more powerful cousin <a
2789 href="filters.html#GEventEvaluator"><code>GEventEvaluator</code></a>.
2790 For example, the following configuration file uses
2791 <code>JaninoEventEvaluator</code> instead of
2792 <code>OnMarkerEvaluator</code> but is otherwise equivalent to the
2793 previous configuration file.
2794 </p>
2795
2796 <p class="example">Example: <code>SMTPAppender</code> with
2797 <code>JaninoEventEvaluator</code> (logback-examples/src/main/resources/chapters/appenders/mail/mailWithMarker_Janino.xml)</p>
2798
2799 <span class="asGroovy" onclick="return asGroovy('mailWithMarker_Janino');">View as .groovy</span>
2800 <pre id="mailWithMarker_Janino" class="prettyprint source">&lt;configuration>
2801 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2802 &lt;evaluator class="ch.qos.logback.classic.boolex.JaninoEventEvaluator">
2803 &lt;expression>
2804 (marker != null) &amp;&amp;
2805 (marker.contains("NOTIFY_ADMIN") || marker.contains("TRANSACTION_FAILURE"))
2806 &lt;/expression>
2807 &lt;/evaluator>
2808 ... same as above
2809 &lt;/appender>
2810 &lt;/configuration></pre>
2811
2812 <h4 class="doAnchor" name="marker_GEventEvaluator">Marker-based
2813 triggering with GEventEvaluator</h4>
2814
2815 <p>Here is the equivalent evaluator using <a
2816 href="filters.html#GEventEvaluator">GEventEvaluator</a>.</p>
2817
2818 <p class="example">Example: the same with
2819 <code>GEventEvaluator</code> (logback-examples/src/main/resources/chapters/appenders/mail/mailWithMarker_GEvent.xml)</p>
2820 <span class="asGroovy" onclick="return asGroovy('mailWithMarker_GEventEvaluator');">View as .groovy</span>
2821
2822 <pre id="mailWithMarker_GEventEvaluator" class="prettyprint source">&lt;configuration>
2823 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2824 &lt;evaluator class="ch.qos.logback.classic.boolex.GEventEvaluator">
2825 &lt;expression>
2826 e.marker?.contains("NOTIFY_ADMIN") || e.marker?.contains("TRANSACTION_FAILURE")
2827 &lt;/expression>
2828 &lt;/evaluator>
2829 ... same as above
2830 &lt;/appender>
2831 &lt;/configuration></pre>
2832
2833 <p>Note that since the event may lack a marker, the value of
2834 e.marker can be null. Hence the use of Groovy's <a
2835 href="http://groovy.codehaus.org/Null+Object+Pattern">safe
2836 dereferencing operator</a>, that is the .? operator.
2837 </p>
2838
2839
2840 <h3 class="doAnchor" name="smtpAuthentication">Authentication/STARTTLS/SSL</h3>
2841
2842 <p><code>SMTPAppender</code> supports authentication via plain
2843 user passwords as well as both the STARTTLS and SSL
2844 protocols. Note that STARTTLS differs from SSL in that, in
2845 STARTTLS, the connection is initially non-encrypted and only after
2846 the STARTTLS command is issued by the client (if the server
2847 supports it) does the connection switch to SSL. In SSL mode, the
2848 connection is encrypted right from the start.
2849 </p>
2850
2851 <h3 class="doAnchor" name="gmailSSL">SMTPAppender configuration
2852 for Gmail (SSL)</h3>
2853
2854 <p>The next example shows you how to configure
2855 <code>SMTPAppender</code> for Gmail with the SSL protocol. </p>
2856
2857 <p class="example">Example:: <code>SMTPAppender</code> to Gmail
2858 using SSL
2859 (logback-examples/src/main/resources/chapters/appenders/mail/gmailSSL.xml)</p>
2860
2861 <span class="asGroovy" onclick="return asGroovy('gmailSSLExample');">View as .groovy</span>
2862 <pre id="gmailSSLExample" class="prettyprint source">&lt;configuration>
2863 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2864 <b>&lt;smtpHost>smtp.gmail.com&lt;/smtpHost></b>
2865 <b>&lt;smtpPort>465&lt;/smtpPort></b>
2866 <b>&lt;SSL>true&lt;/SSL></b>
2867 <b>&lt;username>[email protected]&lt;/username></b>
2868 <b>&lt;password>YOUR_GMAIL_PASSWORD&lt;/password></b>
2869
2870 &lt;to>EMAIL-DESTINATION&lt;/to>
2871 &lt;to>ANOTHER_EMAIL_DESTINATION&lt;/to> &lt;!-- additional destinations are possible -->
2872 &lt;from>[email protected]&lt;/from>
2873 &lt;subject>TESTING: %logger{20} - %m&lt;/subject>
2874 &lt;layout class="ch.qos.logback.classic.PatternLayout">
2875 &lt;pattern>%date %-5level %logger{35} - %message%n&lt;/pattern>
2876 &lt;/layout>
2877 &lt;/appender>
2878
2879 &lt;root level="DEBUG">
2880 &lt;appender-ref ref="EMAIL" />
2881 &lt;/root>
2882 &lt;/configuration></pre>
2883
2884
2885 <h3 class="doAnchor" name="gmailSTARTTLS">SMTPAppender for Gmail
2886 (STARTTLS)</h3>
2887
2888 <p>The next example shows you how to configure
2889 <code>SMTPAppender</code> for Gmail for the STARTTLS protocol. </p>
2890
2891 <p class="example">Example: <code>SMTPAppender</code> to GMAIL using STARTTLS (logback-examples/src/main/resources/chapters/appenders/mail/gmailSTARTTLS.xml)</p>
2892
2893 <span class="asGroovy" onclick="return asGroovy('gmailSTARTTLSExample');">View as .groovy</span>
2894 <pre id="gmailSTARTTLSExample" class="prettyprint source">&lt;configuration>
2895 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2896 &lt;smtpHost>smtp.gmail.com&lt;/smtpHost>
2897 &lt;smtpPort>587&lt;/smtpPort>
2898 &lt;STARTTLS>true&lt;/STARTTLS>
2899 &lt;username>[email protected]&lt;/username>
2900 &lt;password>YOUR_GMAIL_xPASSWORD&lt;/password>
2901
2902 &lt;to>EMAIL-DESTINATION&lt;/to>
2903 &lt;to>ANOTHER_EMAIL_DESTINATION&lt;/to> &lt;!-- additional destinations are possible -->
2904 &lt;from>[email protected]&lt;/from>
2905 &lt;subject>TESTING: %logger{20} - %m&lt;/subject>
2906 &lt;layout class="ch.qos.logback.classic.PatternLayout">
2907 &lt;pattern>%date %-5level %logger - %message%n&lt;/pattern>
2908 &lt;/layout>
2909 &lt;/appender>
2910
2911 &lt;root level="DEBUG">
2912 &lt;appender-ref ref="EMAIL" />
2913 &lt;/root>
2914 &lt;/configuration></pre>
2915
2916
2917 <h3 class="doAnchor" name="smtpDiscriminator">SMTPAppender with MDCDiscriminator</h3>
2918
2919
2920 <p>As mentioned earlier, by specifying a discriminator other than
2921 the default one, <code>SMTPAppender</code> will generate email
2922 messages containing events pertaining to a particular user, user
2923 session or client IP address, depending on the specified discriminator.
2924 </p>
2925
2926 <p>The next example illustrates the use of <a
2927 href="../xref/ch/qos/logback/classic/sift/MDCBasedDiscriminator.html">MDCBasedDiscriminator</a>
2928 in conjunction with the MDC key named "req.remoteHost", assumed to
2929 contain the IP address of the remote host accessing a fictitious
2930 application. In a web-application, you could use <a
2931 href="mdc.html#mis">MDCInsertingServletFilter</a> to populate MDC
2932 values.
2933 </p>
2934
2935 <p class="example">Example: <code>SMTPAppender</code> with
2936 MDCBasedDsicriminator
2937 (logback-examples/src/main/resources/chapters/appenders/mail/mailWithMDCBasedDiscriminator.xml)</p>
2938
2939 <span class="asGroovy" onclick="return asGroovy('mailWithMDCBasedDiscriminator');">View as .groovy</span>
2940 <pre id="mailWithMDCBasedDiscriminator" class="prettyprint source">&lt;configuration>
2941 &lt;appender name="EMAIL" class="ch.qos.logback.classic.net.SMTPAppender">
2942 &lt;smtpHost>ADDRESS-OF-YOUR-SMTP-HOST&lt;/smtpHost>
2943 &lt;to>EMAIL-DESTINATION&lt;/to>
2944 &lt;from>SENDER-EMAIL&lt;/from>
2945
2946 <b>&lt;discriminator class="ch.qos.logback.classic.sift.MDCBasedDiscriminator"></b>
2947 <b>&lt;key>req.remoteHost&lt;/key></b>
2948 <b>&lt;defaultValue>default&lt;/defaultValue></b>
2949 <b>&lt;/discriminator></b>
2950
2951 &lt;subject>${HOSTNAME} -- %X{req.remoteHost} %msg"&lt;/subject>
2952 &lt;layout class="ch.qos.logback.classic.html.HTMLLayout">
2953 &lt;pattern>%date%level%thread%X{req.remoteHost}%X{req.requestURL}%logger%msg&lt;/pattern>
2954 &lt;/layout>
2955 &lt;/appender>
2956
2957 &lt;root>
2958 &lt;level level="DEBUG"/>
2959 &lt;appender-ref ref="EMAIL" />
2960 &lt;/root>
2961 &lt;/configuration></pre>
2962
2963 <p>Thus, each outgoing email generated by
2964 <code>SMTPAppender</code> will belong to a <em>unique</em> remote
2965 host, greatly facilitating problem diagnosis.
2966 </p>
2967
2968 <h4 class="doAnchor" name= "bufferManagement">Buffer management in
2969 very busy systems</h4>
2970
2971 <p>Internally, each distinct value returned by the discriminator
2972 will cause the creation of a new cyclic buffer. However, at most
2973 <span class="prop">maxNumberOfBuffers</span> (by default 64)
2974 will be maintained. Whenever the number of buffers rises above
2975 <span class="prop">maxNumberOfBuffers</span>, the least recently
2976 updated buffer is automatically discarded. As a second safety
2977 measure, any buffer which has not been updated in the last 30
2978 minutes will be automatically discarded as well.</p>
2979
2980 <p>On systems serving a large number of transactions per minute,
2981 allowing only a small number for <span
2982 class="prop">maxNumberOfBuffers</span> (by default 64) will
2983 often cause the number of events in the outgoing email to be
2984 unnecessarily small. Indeed, in the presence of a large number of
2985 transactions, there will be more than one buffer associated with
2986 the same transaction as buffers will be killed and re-born in
2987 succession for the same discriminator value (or transaction). Note
2988 that in even such very busy systems, the maximum number of cyclic
2989 buffers is capped by <span
2990 class="prop">maxNumberOfBuffers</span>.
2991 </p>
2992
2993 <p>To avoid such yo-yo effects, <code>SMTPAppender</code> will
2994 release the buffer associated with a given discriminator key as
2995 soon as it sees an event marked as "FINALIZE_SESSION". This will
2996 cause the appropriate buffer to be discarded at the end of each
2997 transaction. You can then safely increase the value of <span
2998 class="prop">maxNumberOfBuffers</span> to a larger value such as
2999 512 or 1024 without risking running out of memory.
3000 </p>
3001
3002 <p>There are three distinct but complementary mechanisms working
3003 together to manage cyclic buffers. They ensure that only relevant
3004 buffers are kept alive at any given moment, even in very busy
3005 systems.</p>
3006
3007 <!-- =========================================================== -->
3008 <!-- =========================================================== -->
3009
3010
3011 <h3 class="doAnchor" name="DBAppender">DBAppender</h3>
3012
3013 <p>The <a
3014 href="../xref/ch/qos/logback/classic/db/DBAppender.html"><code>DBAppender</code></a>
3015 inserts logging events into three database tables in a format
3016 independent of the Java programming language.
3017 </p>
3018
3019 <p>These three tables are <em>logging_event</em>,
3020 <em>logging_event_property</em> and
3021 <em>logging_event_exception</em>. They must exist before
3022 <code>DBAppender</code> can be used. Logback ships with SQL
3023 scripts that will create the tables. They can be found under the
3024 <em>logback-classic/src/main/java/ch/qos/logback/classic/db/script</em>
3025 folder. There is a specific script for each of the most popular
3026 database systems. If the script for your particular type of
3027 database system is missing, it should be quite easy to write one,
3028 taking example on the already existing scripts. If you send them
3029 to us, we will gladly include missing scripts in future releases.
3030 </p>
3031
3032 <p>If your JDBC driver supports the <code>getGeneratedKeys</code>
3033 method introduced in JDBC 3.0 specification, assuming you have
3034 created the appropriate database tables as mentioned above, then
3035 no additional steps are required. Otherwise, there must be an
3036 <code>SQLDialect</code> appropriate for your database
3037 system. Currently, logback has dialects for H2, HSQL, MS SQL
3038 Server, MySQL, Oracle, PostgreSQL, SQLLite and Sybase. </p>
3039
3040 <p>The table below summarizes the database types and their support
3041 of the <code>getGeneratedKeys()</code> method.
3042 </p>
3043
3044 <table class="bodyTable striped" border="0" cellpadding="4">
3045 <tr>
3046 <th>RDBMS</th>
3047 <th>tested version(s)
3048 </th>
3049 <th>tested JDBC driver version(s)
3050 </th>
3051 <th>
3052 supports
3053 <br />
3054 <code>getGeneratedKeys()</code>
3055 method
3056 </th>
3057
3058 <th>is a dialect <br/>provided by logback</th>
3059 </tr>
3060
3061 <tr>
3062 <td>DB2</td>
3063 <td>untested</td>
3064 <td>untested</td>
3065 <td>unknown</td>
3066 <td>NO</td>
3067 </tr>
3068
3069 <tr>
3070 <td>H2</td>
3071 <td>1.2.132</td>
3072 <td>-</td>
3073 <td>unknown</td>
3074 <td>YES</td>
3075 </tr>
3076
3077 <tr>
3078 <td>HSQL</td>
3079 <td>1.8.0.7</td>
3080 <td>-</td>
3081 <td>NO </td>
3082 <td>YES</td>
3083 </tr>
3084
3085 <tr>
3086 <td>Microsoft SQL Server</td>
3087 <td>2005</td>
3088 <td>2.0.1008.2 (sqljdbc.jar)</td>
3089 <td>YES</td>
3090 <td>YES</td>
3091 </tr>
3092
3093 <tr>
3094 <td>MySQL</td>
3095 <td>5.0.22</td>
3096 <td>5.0.8 (mysql-connector.jar)</td>
3097 <td>YES</td>
3098 <td>YES</td>
3099 </tr>
3100
3101 <tr>
3102 <td>PostgreSQL</td>
3103 <td>8.x</td>
3104 <td>8.4-701.jdbc4</td>
3105 <td>NO</td>
3106 <td>YES</td>
3107
3108 </tr>
3109
3110 <tr>
3111 <td>Oracle</td>
3112 <td>10g</td>
3113 <td>10.2.0.1 (ojdbc14.jar)</td>
3114 <td>YES</td>
3115 <td>YES</td>
3116 </tr>
3117
3118 <tr>
3119 <td>SQLLite</td>
3120 <td>3.7.4</td>
3121 <td>-</td>
3122 <td>unknown</td>
3123 <td>YES</td>
3124 </tr>
3125
3126
3127 <tr>
3128 <td>Sybase SQLAnywhere</td>
3129 <td>10.0.1</td>
3130 <td>-</td>
3131 <td>unknown</td>
3132 <td>YES</td>
3133 </tr>
3134
3135 </table>
3136
3137 <p>Experiments show that writing a single event into the database
3138 takes approximately 10 milliseconds, on a "standard" PC. If pooled
3139 connections are used, this figure drops to around 1
3140 millisecond. Note that most JDBC drivers already ship with
3141 connection pooling support.
3142 </p>
3143
3144 <p>Configuring logback to use <code>DBAppender</code> can be done
3145 in several different ways, depending on the tools one has to
3146 connect to the database, and the database itself. The key issue in
3147 configuring <code>DBAppender</code> is about setting its
3148 <code>ConnectionSource</code> object, as we shall discover
3149 shortly.
3150 </p>
3151
3152 <p>Once <code>DBAppender</code> is configured for your database,
3153 logging events are sent to the specified database. As stated
3154 previously, there are three tables used by logback to store
3155 logging event data.
3156 </p>
3157
3158 <p>
3159 The <em>logging_event</em> table contains the following fields:
3160 </p>
3161 <table class="bodyTable striped">
3162 <tr>
3163 <th>Field</th>
3164 <th>Type</th>
3165 <th>Description</th>
3166 </tr>
3167 <tr>
3168 <td><b>timestamp</b></td>
3169 <td><code>big int</code></td>
3170 <td>The timestamp that was valid at the logging event's creation.</td>
3171 </tr>
3172 <tr>
3173 <td><b>formatted_message</b></td>
3174 <td><code>text</code></td>
3175
3176 <td>The message that has been added to the logging event,
3177 after formatting with
3178 <code>org.slf4j.impl.MessageFormatter</code>, in case objects
3179 were passed along with the message.</td>
3180 </tr>
3181 <tr>
3182 <td><b>logger_name</b></td>
3183 <td><code>varchar</code></td>
3184 <td>The name of the logger used to issue the logging request.</td>
3185 </tr>
3186 <tr>
3187 <td><b>level_string</b></td>
3188 <td><code>varchar</code></td>
3189 <td>The level of the logging event.</td>
3190 </tr>
3191 <tr>
3192 <td><b>reference_flag</b></td>
3193 <td><code>smallint</code></td>
3194 <td>
3195 <p>This field is used by logback to identify logging events
3196 that have an exception or <code>MDC</code>property values
3197 associated.
3198 </p>
3199
3200 <p>Its value is computed by
3201 <code>ch.qos.logback.classic.db.DBHelper</code>. A logging
3202 event that contains <code>MDC</code> or <code>Context</code>
3203 properties has a flag number of <em>1</em>. One that
3204 contains an exception has a flag number of <em>2</em>. A
3205 logging event that contains both elements has a flag number
3206 of <em>3</em>.
3207 </p>
3208 </td>
3209 </tr>
3210 <tr>
3211 <td><b>caller_filename</b></td>
3212 <td><code>varchar</code></td>
3213 <td>The name of the file where the logging request was issued.</td>
3214 </tr>
3215 <tr>
3216 <td><b>caller_class</b></td>
3217 <td><code>varchar</code></td>
3218 <td>The class where the logging request was issued.</td>
3219 </tr>
3220 <tr>
3221 <td><b>caller_method</b></td>
3222 <td><code>varchar</code></td>
3223 <td>The name of the method where the logging request was issued.</td>
3224 </tr>
3225 <tr>
3226 <td><b>caller_line</b></td>
3227 <td><code>char</code></td>
3228 <td>The line number where the logging request was issued.</td>
3229 </tr>
3230 <tr>
3231 <td><b>event_id</b></td>
3232 <td><code>int</code></td>
3233 <td>The database id of the logging event.</td>
3234 </tr>
3235 </table>
3236
3237 <p>
3238 The <em>logging_event_property</em> is used to store the keys and values
3239 contained in the <code>MDC</code> or the <code>Context</code>.
3240 It contains these fields:
3241 </p>
3242
3243 <table class="bodyTable striped">
3244 <tr>
3245 <th>Field</th>
3246 <th>Type</th>
3247 <th>Description</th>
3248 </tr>
3249 <tr>
3250 <td><b>event_id</b></td>
3251 <td><code>int</code></td>
3252 <td>The database id of the logging event.</td>
3253 </tr>
3254 <tr>
3255 <td><b>mapped_key</b></td>
3256 <td><code>varchar</code></td>
3257 <td>The key of the <code>MDC</code> property</td>
3258 </tr>
3259 <tr>
3260 <td><b>mapped_value</b></td>
3261 <td><code>text</code></td>
3262 <td>The value of the <code>MDC</code> property</td>
3263 </tr>
3264 </table>
3265
3266 <p>
3267 The <em>logging_event_exception</em> table contains the following fields:
3268 </p>
3269
3270 <table class="bodyTable striped">
3271 <tr>
3272 <th>Field</th>
3273 <th>Type</th>
3274 <th>Description</th>
3275 </tr>
3276 <tr>
3277 <td><b>event_id</b></td>
3278 <td><code>int</code></td>
3279 <td>The database id of the logging event.</td>
3280 </tr>
3281 <tr>
3282 <td><b>i</b></td>
3283 <td><code>smallint</code></td>
3284 <td>The index of the line in the full stack trace.</td>
3285 </tr>
3286 <tr>
3287 <td><b>trace_line</b></td>
3288 <td><code>varchar</code></td>
3289 <td>The corresponding line</td>
3290 </tr>
3291 </table>
3292
3293 <p>
3294 To give a more visual example of the work done by <code>DBAppender</code>, here
3295 is a screenshot of a MySQL database with content provided by <code>DBAppender</code>.
3296 </p>
3297
3298 <p>The <em>logging_event</em> table:</p>
3299
3300 <img src="images/chapters/appenders/dbAppenderLE.gif" alt="Logging Event table" />
3301
3302 <p>The <em>logging_event_exception</em> table:</p>
3303
3304 <img src="images/chapters/appenders/dbAppenderLEException.gif" alt="Logging Event Exception table" />
3305
3306 <p>The <em>logging_event_property</em> table:</p>
3307
3308 <img src="images/chapters/appenders/dbAppenderLEProperty.gif" alt="Logging Event Property table" />
3309
3310
3311 <h4>ConnectionSource</h4>
3312
3313 <p>The <code>ConnectionSource</code> interface provides a
3314 pluggable means of transparently obtaining JDBC connections for
3315 logback classes that require the use of a
3316 <code>java.sql.Connection</code>. There are currently three
3317 implementations of <code>ConnectionSource</code>, namely
3318 <code>DataSourceConnectionSource</code>,
3319 <code>DriverManagerConnectionSource</code> and
3320 <code>JNDIConnectionSource</code>.
3321 </p>
3322
3323 <p>
3324 The first example that we will review is a configuration using
3325 <code>DriverManagerConnectionSource</code> and a MySQL database.
3326 The following configuration file is what one would need.
3327 </p>
3328
3329 <p class="example">Example: <code>DBAppender</code> configuration (logback-examples/src/main/resources/chapters/appenders/db/append-toMySQL-with-driverManager.xml)</p>
3330 <span class="asGroovy" onclick="return asGroovy('append-toMySQL-with-driverManager');">View as .groovy</span>
3331 <pre id="append-toMySQL-with-driverManager" class="prettyprint source">&lt;configuration>
3332
3333 <b>&lt;appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
3334 &lt;connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
3335 &lt;driverClass>com.mysql.jdbc.Driver&lt;/driverClass>
3336 &lt;url>jdbc:mysql://host_name:3306/datebase_name&lt;/url>
3337 &lt;user>username&lt;/user>
3338 &lt;password>password&lt;/password>
3339 &lt;/connectionSource>
3340 &lt;/appender></b>
3341
3342 &lt;root level="DEBUG" >
3343 &lt;appender-ref ref="DB" />
3344 &lt;/root>
3345 &lt;/configuration></pre>
3346
3347 <p>
3348 The correct driver must be declared. Here, the <code>com.mysql.jdbc.Driver</code>
3349 class is used. The <span class="prop">url</span> must begin with <em>jdbc:mysql://</em>.
3350 </p>
3351
3352 <p>
3353 The
3354 <a href="../xref/ch/qos/logback/core/db/DriverManagerConnectionSource.html">
3355 <code>DriverManagerConnectionSource</code></a> is an implementation of
3356 <code>ConnectionSource</code> that obtains the connection in the
3357 traditional JDBC manner based on the connection URL.
3358 </p>
3359 <p>
3360 Note that this class will establish a new
3361 <code>Connection</code> for each call to
3362 <code>getConnection()</code>. It is recommended that you either
3363 use a JDBC driver that natively supports connection pooling or
3364 that you create your own implementation of
3365 <code>ConnectionSource</code> that taps into whatever pooling
3366 mechanism you are already using. If you have access to a JNDI
3367 implementation that supports <code>javax.sql.DataSource</code>,
3368 e.g. within a J2EE application server, see <a
3369 href="#JNDIConnectionSource"><code>JNDIConnectionSource</code></a>
3370 below.
3371 </p>
3372 <!--
3373
3374 HAS TO BE TESTED
3375
3376 <p>
3377 If you do not have another connection pooling mechanism built
3378 into your application, you can use the
3379 <a href="http://jakarta.apache.org/commons/dbcp/index.html">
3380 commons-dbcp </a> package from Apache:
3381 </p>
3382
3383 <pre class="prettyprint source">
3384 &lt;connectionSource
3385 class=&quot;ch.qos.logback.core.db.DriverManagerConnectionSource&quot;&gt;
3386 &lt;param name=&quot;driver&quot; value=&quot;org.apache.commons.dbcp.PoolingDriver&quot;/&gt;
3387 &lt;param name=&quot;url&quot; value=&quot;jdbc:apache:commons:dbcp:/myPoolingDriver&quot;/&gt;
3388 &lt;/connectionSource&gt;
3389 </pre>
3390
3391 <p>
3392 Then the configuration information for the commons-dbcp
3393 package goes into the file <em>myPoolingDriver.jocl</em> and is
3394 placed in the classpath. See the
3395 <a href="http://jakarta.apache.org/commons/dbcp/index.html"> commons-dbcp </a>
3396 documentation for details.
3397 </p>
3398 -->
3399
3400 <p>Connecting to a database using a <code>DataSource</code> is
3401 rather similar. The configuration now uses <a
3402 href="../xref/ch/qos/logback/core/db/DataSourceConnectionSource.html">
3403 <code>DataSourceConnectionSource</code></a>, which is an
3404 implementation of <code>ConnectionSource</code> that obtains the
3405 <code>Connection</code> in the recommended JDBC manner based on a
3406 <code>javax.sql.DataSource</code>.
3407 </p>
3408
3409 <p class="example">Example: <code>DBAppender</code> configuration (logback-examples/src/main/resources/chapters/appenders/db/append-with-datasource.xml)</p>
3410
3411
3412 <span class="asGroovy" onclick="return asGroovy('append-with-datasource');">View as .groovy</span>
3413 <pre id="append-with-datasource" class="prettyprint source">&lt;configuration debug="true">
3414
3415 &lt;appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
3416 <b>&lt;connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
3417
3418 &lt;dataSource class="${dataSourceClass}">
3419 </b>&lt;!-- Joran cannot substitute variables
3420 that are not attribute values. Therefore, we cannot
3421 declare the next parameter like the others.
3422 -->
3423 <b>&lt;param name="${url-key:-url}" value="${url_value}"/>
3424 &lt;serverName>${serverName}&lt;/serverName>
3425 &lt;databaseName>${databaseName}&lt;/databaseName>
3426 &lt;/dataSource></b>
3427
3428 &lt;user>${user}&lt;/user>
3429 &lt;password>${password}&lt;/password>
3430 &lt;/connectionSource>
3431 &lt;/appender>
3432
3433 &lt;root level="INFO">
3434 &lt;appender-ref ref="DB" />
3435 &lt;/root>
3436 &lt;/configuration></pre>
3437
3438 <p>Note that in this configuration sample, we make heavy use of
3439 substitution variables. They are sometimes handy when connection
3440 details have to be centralized in a single configuration file and
3441 shared by logback and other frameworks.
3442 </p>
3443
3444 <!-- TO BE TESTED
3445
3446 <p>The connection created by
3447 <code>DataSourceConnectionSource</code> can be placed in a JNDI
3448 context by using <code>BindDataSourceToJNDIAction</code>. In that
3449 case, one has to specify the use of this class by adding a new
3450 rule to Joran, logback's configuration framework. Here is an
3451 excerpt of such a configuration file. </p>
3452
3453 <div class="source"><pre>&lt;configuration>
3454 ..
3455 <b>&lt;newRule pattern="configuration/bindDataSourceToJNDI"
3456 actionClass="ch.qos.logback.core.db.BindDataSourceToJNDIAction"/>
3457
3458 &lt;bindDataSourceToJNDI /></b>
3459 ..
3460 &lt;/configuration></pre></div>
3461
3462 <p> The <em>newRule</em> element teaches Joran to use specified
3463 action class with the given pattern. Then, we simply declare the
3464 given element. The action class will be called and our connection
3465 source will be bound to a JNDI context. </p>
3466
3467 <p>This is a very powerful capability of Joran. If you'd like to
3468 read more about Joran, please see the <a
3469 href="onJoran.html">chapter to Joran</a>. </p>
3470
3471 -->
3472
3473 <h4 class="doAnchor"
3474 name="JNDIConnectionSource">JNDIConnectionSource</h4>
3475
3476 <p><a
3477 href="../xref/ch/qos/logback/core/db/JNDIConnectionSource.html">
3478 <code>JNDIConnectionSource</code></a> is another
3479 <code>ConnectionSource</code> implementation shipping in logback.
3480 As its name indicates, it retrieves a
3481 <code>javax.sql.DataSource</code> from a JNDI and then leverages
3482 it to obtain a <code>java.sql.Connection</code>
3483 instance. <code>JNDIConnectionSource</code> is primarily designed
3484 to be used inside J2EE application servers or by application
3485 server clients, assuming the application server supports remote
3486 access of <code>javax.sql.DataSource</code>. Thus, one can take
3487 advantage of connection pooling and whatever other goodies the
3488 application server provides. More importantly, your application
3489 will be <a
3490 href="http://en.wikipedia.org/wiki/Don't_repeat_yourself">dryer</a>
3491 as it will be no longer necessary to define a
3492 <code>DataSource</code> in <em>logback.xml</em>.</p>
3493
3494 <p>For example, here is a configuration snippet for Tomcat. It
3495 assumes PostgreSQL as the database although any of the supported
3496 database systems (listed above) would work.</p>
3497
3498 <pre class="prettyprint source">&lt;Context docBase="/path/to/app.war" path="/myapp">
3499 ...
3500 &lt;Resource <b>name="jdbc/logging"</b>
3501 auth="Container"
3502 type="javax.sql.DataSource"
3503 username="..."
3504 password="..."
3505 driverClassName="org.postgresql.Driver"
3506 url="jdbc:postgresql://localhost/..."
3507 maxActive="8"
3508 maxIdle="4"/>
3509 ...
3510 &lt;/Context></pre>
3511
3512 <p>Once a <code>DataSource</code> is defined in the J2EE server, it
3513 can be easily referenced by your logback configuration file, as
3514 shown in the next example.</p>
3515
3516 <p class="example">Example: <code>DBAppender</code> configuration
3517 by <code>JNDIConnectionSource</code>
3518 (logback-examples/src/main/resources/chapters/appenders/db/append-via-jndi.xml)</p>
3519
3520 <span class="asGroovy" onclick="return asGroovy('append-via-jndi');">View as .groovy</span>
3521
3522
3523 <pre id="append-via-jndi" class="prettyprint source">&lt;configuration debug="true">
3524 &lt;appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
3525 &lt;connectionSource class=&quot;ch.qos.logback.core.db.JNDIConnectionSource&quot;&gt;
3526 <b>&lt;!-- please note the "java:comp/env/" prefix --&gt;</b>
3527 <b>&lt;jndiLocation>java:comp/env/jdbc/logging&lt;/jndiLocation></b>
3528 &lt;/connectionSource&gt;
3529 &lt;/appender>
3530 &lt;root level="INFO">
3531 &lt;appender-ref ref="DB" />
3532 &lt;/root>
3533 &lt;/configuration></pre>
3534
3535 <p>
3536 Note that this class will obtain an
3537 <code>javax.naming.InitialContext</code>
3538 using the no-argument constructor. This will usually work
3539 when executing within a J2EE environment. When outside the
3540 J2EE environment, make sure that you provide a
3541 <em>jndi.properties</em>
3542 file as described by your JNDI provider's documentation.
3543 </p>
3544
3545 <h4 class="doAnchor">Connection pooling</h4>
3546
3547 <p>Logging events can be created at a rather fast pace. To keep up
3548 with the flow of events that must be inserted into a database, it
3549 is recommended to use connection pooling with
3550 <code>DBAppender</code>.
3551 </p>
3552
3553 <p>
3554 Experiment shows that using connection pooling with <code>DBAppender</code>
3555 gives a big performance boost. With the following
3556 configuration file, logging events are sent to a MySQL database,
3557 without any pooling.
3558 </p>
3559
3560 <p class="example">Example: <code>DBAppender</code> configuration
3561 without pooling
3562 (logback-examples/src/main/resources/chapters/appenders/db/append-toMySQL-with-datasource.xml)</p>
3563
3564 <span class="asGroovy" onclick="return asGroovy('append-toMySQL-with-datasource');">View as .groovy</span>
3565 <pre id="append-toMySQL-with-datasource" class="prettyprint source">&lt;configuration>
3566
3567 &lt;appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
3568 &lt;connectionSource class="ch.qos.logback.core.db.DataSourceConnectionSource">
3569 &lt;dataSource class="com.mysql.jdbc.jdbc2.optional.MysqlDataSource">
3570 &lt;serverName>${serverName}&lt;/serverName>
3571 &lt;port>${port$&lt;/port>
3572 &lt;databaseName>${dbName}&lt;/databaseName>
3573 &lt;user>${user}&lt;/user>
3574 &lt;password>${pass}&lt;/password>
3575 &lt;/dataSource>
3576 &lt;/connectionSource>
3577 &lt;/appender>
3578
3579 &lt;root level="DEBUG">
3580 &lt;appender-ref ref="DB" />
3581 &lt;/root>
3582 &lt;/configuration></pre>
3583
3584 <p>With this configuration file, sending 500 logging events to a
3585 MySQL database takes a whopping 5 seconds, that is 10 milliseconds
3586 per request. This figure is unacceptable when dealing with large
3587 applications.
3588 </p>
3589
3590 <p>A dedicated external library is necessary to use connection
3591 pooling with <code>DBAppender</code>. The next example uses <a
3592 href="http://sourceforge.net/projects/c3p0">c3p0</a>. To be able
3593 to use c3p0, one must download it and place
3594 <em>c3p0-VERSION.jar</em> in the classpath.
3595 </p>
3596
3597 <p class="example">Example: <code>DBAppender</code> configuration
3598 with pooling
3599 (logback-examples/src/main/resources/chapters/appenders/db/append-toMySQL-with-datasource-and-pooling.xml)</p>
3600 <span class="asGroovy" onclick="return asGroovy('append-toMySQL-with-datasource-and-pooling');">View as .groovy</span>
3601 <pre id="append-toMySQL-with-datasource-and-pooling" class="prettyprint source">&lt;configuration>
3602
3603 &lt;appender name="DB" class="ch.qos.logback.classic.db.DBAppender">
3604 &lt;connectionSource
3605 class="ch.qos.logback.core.db.DataSourceConnectionSource">
3606 <b>&lt;dataSource
3607 class="com.mchange.v2.c3p0.ComboPooledDataSource">
3608 &lt;driverClass>com.mysql.jdbc.Driver&lt;/driverClass>
3609 &lt;jdbcUrl>jdbc:mysql://${serverName}:${port}/${dbName}&lt;/jdbcUrl>
3610 &lt;user>${user}&lt;/user>
3611 &lt;password>${password}&lt;/password>
3612 &lt;/dataSource></b>
3613 &lt;/connectionSource>
3614 &lt;/appender>
3615
3616 &lt;root level="DEBUG">
3617 &lt;appender-ref ref="DB" />
3618 &lt;/root>
3619 &lt;/configuration></pre>
3620
3621 <p>With this new configuration, sending 500 logging requests to
3622 the aforementioned MySQL database takes around 0.5 seconds, for an
3623 average of 1 millisecond per request, that is a tenfold
3624 improvement in performance.
3625 </p>
3626
3627 <h3 class="doAnchor" name="SyslogAppender">SyslogAppender</h3>
3628
3629 <p>The syslog protocol is a very simple protocol: a syslog sender
3630 sends a small message to a syslog receiver. The receiver is
3631 commonly called <em>syslog daemon</em> or <em>syslog server</em>.
3632 Logback can send messages to a remote syslog daemon. This is
3633 achieved by using <a
3634 href="../xref/ch/qos/logback/classic/net/SyslogAppender.html"><code>SyslogAppender</code></a>.
3635 </p>
3636
3637 <p>Here are the properties you can pass to a SyslogAppender.</p>
3638
3639 <table class="bodyTable striped">
3640 <tr>
3641 <th>Property Name</th>
3642 <th>Type</th>
3643 <th>Description</th>
3644 </tr>
3645 <tr>
3646 <td><span class="prop" container="syslog">syslogHost</span></td>
3647 <td><code>String</code></td>
3648 <td>The host name of the syslog server.</td>
3649 </tr>
3650 <tr>
3651 <td><span class="prop" container="syslog">port</span></td>
3652 <td><code>String</code></td>
3653 <td>The port number on the syslog server to connect
3654 to. Normally, one would not want to change the default value
3655 of <em>514</em>.
3656 </td>
3657 </tr>
3658 <tr>
3659 <td><span class="prop" container="syslog">facility</span></td>
3660 <td><code>String</code></td>
3661 <td>
3662 <p>The <span class="prop">facility</span> is meant to identify
3663 the source of a message.</p>
3664 <p>The <span class="prop">facility</span> option must be set
3665 to one of the strings <em>KERN, USER, MAIL, DAEMON, AUTH,
3666 SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, NTP, AUDIT,
3667 ALERT, CLOCK, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4,
3668 LOCAL5, LOCAL6, LOCAL7</em>. Case is not important.</p>
3669 </td>
3670 </tr>
3671 <tr>
3672 <td><span class="prop" container="syslog">suffixPattern</span></td>
3673 <td><code>String</code></td>
3674 <td><p>The <span class="prop">suffixPattern</span> option
3675 specifies the format of the non-standardized part of the
3676 message sent to the syslog server. By default, its value is
3677 <em>[%thread] %logger %msg</em>. Any value that a
3678 <code>PatternLayout</code> could use is a correct <span
3679 class="prop">suffixPattern</span> value.
3680 </p>
3681 </td>
3682 </tr>
3683
3684 <tr>
3685 <td><span class="prop"
3686 container="syslog">stackTracePattern</span></td>
3687 <td><code>String</code></td>
3688 <td><p>The <span class="prop">stackTracePattern</span>
3689 property allows the customization of the string appearing just
3690 before each stack trace line. The default value for this
3691 property is "\t", i.e. the tab character. Any value accepted
3692 by <code>PatternLayout</code> is a valid value for <span
3693 class="prop">stackTracePattern</span>.</p>
3694 </td>
3695 </tr>
3696
3697 <tr>
3698 <td><span class="prop" container="syslog">throwableExcluded</span></td>
3699 <td><code>boolean</code></td>
3700 <td>Setting <span class="prop">throwableExcluded</span> to
3701 <code>true</code> will cause stack trace data associated with
3702 a Throwable to be omitted. By default, <span
3703 class="prop">throwableExcluded</span> is set to
3704 <code>false</code> so that stack trace data is sent to the
3705 syslog server. </td>
3706 </tr>
3707
3708
3709 </table>
3710
3711 <p>The syslog severity of a logging event is converted from the
3712 level of the logging event. The <em>DEBUG</em> level is converted
3713 to <em>7</em>, <em>INFO</em> is converted to <em>6</em>,
3714 <em>WARN</em> is converted to <em>4</em> and <em>ERROR</em> is
3715 converted to <em>3</em>.
3716 </p>
3717
3718 <p>Since the format of a syslog request follows rather strict
3719 rules, there is no layout to be used with
3720 <code>SyslogAppender</code>. However, using the <span
3721 class="prop">suffixPattern</span> option lets the user display
3722 whatever information she wishes.
3723 </p>
3724
3725 <p>Here is a sample configuration using a
3726 <code>SyslogAppender</code>.</p>
3727
3728 <p class="example">Example: <code>SyslogAppender</code> configuration (logback-examples/src/main/resources/chapters/appenders/conf/logback-syslog.xml)</p>
3729 <span class="asGroovy" onclick="return asGroovy('logback-syslog');">View as .groovy</span>
3730 <pre id="logback-syslog" class="prettyprint source">&lt;configuration>
3731
3732 &lt;appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender">
3733 &lt;syslogHost>remote_home&lt;/syslogHost>
3734 &lt;facility>AUTH&lt;/facility>
3735 &lt;suffixPattern>[%thread] %logger %msg&lt;/suffixPattern>
3736 &lt;/appender>
3737
3738 &lt;root level="DEBUG">
3739 &lt;appender-ref ref="SYSLOG" />
3740 &lt;/root>
3741 &lt;/configuration></pre>
3742
3743 <p>When testing this configuration, you should verify that the
3744 remote syslog daemon accepts requests from an external
3745 source. Experience shows that, by default, syslog daemons usually
3746 deny requests coming via a network connection.
3747 </p>
3748
3749
3750 <h3 class="doAnchor" name="SiftingAppender">SiftingAppender</h3>
3751
3752 <p>As its name implies, a <code>SiftingAppender</code> can be used
3753 to separate (or sift) logging according to a given runtime
3754 attribute. For example, <code>SiftingAppender</code> can separate
3755 logging events according to user sessions, so that the logs
3756 generated by different users go into distinct log files, one log
3757 file per user.
3758 </p>
3759
3760
3761
3762 <table class="bodyTable striped">
3763 <tr>
3764 <th>Property Name</th>
3765 <th>Type</th>
3766 <th>Description</th>
3767 </tr>
3768 <tr>
3769 <td><span class="prop" container="sift">timeout</span></td>
3770 <td><code><a
3771 href="../apidocs/ch/qos/logback/core/util/Duration.html">Duration</a></code></td>
3772 <td>A nested appender which has not been accessed beyond the
3773 <span class="prop">timeout</span> duration is deemed stale. A
3774 stale appender is closed and unreferenced by
3775 <code>SiftingAppender</code>. The default value for <span
3776 class="prop">timeout</span> is 30 minutes.</td>
3777 </tr>
3778 <tr>
3779 <td><span class="prop" container="sift">maxAppenderCount</span></td>
3780 <td><code>integer</code></td>
3781 <td>The maximum number of nested appenders
3782 <code>SiftingAppender</code> may create and track. Default
3783 value for <span class="prop">maxAppenderCount</span> is
3784 Integer.MAX_VALUE.</td>
3785 </tr>
3786 </table>
3787
3788 <p><code>SiftingAppender</code> achieves this feat by creating
3789 nested appenders on the fly. Nested appenders are created based on
3790 a template specified within the configuration of the
3791 <code>SiftingAppender</code> itself (enclosed within the
3792 <code>&lt;sift></code> element, see example
3793 below). <code>SiftingAppender</code> is responsible for managing
3794 the lifecycle of child appenders. For example,
3795 <code>SiftingAppender</code> will automatically close and remove
3796 any stale appender. A nested appender is considered stale when no
3797 accesses it beyond the duration specified by the <span
3798 class="prop">timeout</span> parameter.
3799 </p>
3800
3801 <p>When handling a logging event, <code>SiftingAppender</code>
3802 will select a child appender to delegate to. The selection
3803 criteria are computed at runtime by a discriminator. The user can
3804 specify the selection criteria with the help of a <code><a
3805 href="../xref/ch/qos/logback/core/sift/Discriminator.html">Discriminator</a></code>. Let
3806 us now study an example.
3807 </p>
3808
3809 <h4>Example</h4>
3810
3811 <p>The <a
3812 href="../xref/chapters/appenders/sift/SiftExample.html">SiftExample</a>
3813 application logs a message stating that the application has
3814 started. It then sets the MDC key "userid" to "Alice" and logs a
3815 message. Here is the salient code:</p>
3816
3817 <p class="source">logger.debug("Application started");
3818 MDC.put("userid", "Alice");
3819 logger.debug("Alice says hello"); </p>
3820
3821 <p>The template for the configuration file illustrates the use of
3822 <code>SiftingAppender</code>.</p>
3823
3824
3825 <p class="example">Example: <code>SiftingAppender</code>
3826 configuration
3827 (logback-examples/src/main/resources/chapters/appenders/sift/byUserid.xml)</p>
3828
3829 <span class="asGroovy" onclick="return asGroovy('byUserid');">View as .groovy</span>
3830
3831 <pre id="byUserid" class="prettyprint source">&lt;configuration>
3832
3833 <b>&lt;appender name="SIFT" class="ch.qos.logback.classic.sift.SiftingAppender"></b>
3834 &lt;!-- in the absence of the class attribute, it is assumed that the
3835 desired discriminator type is
3836 ch.qos.logback.classic.sift.MDCBasedDiscriminator -->
3837 <b>&lt;discriminator></b>
3838 <b>&lt;key><span class="green">userid</span>&lt;/key></b>
3839 <b>&lt;defaultValue>unknown&lt;/defaultValue></b>
3840 <b>&lt;/discriminator></b>
3841 <b>&lt;sift></b>
3842 <b>&lt;appender name="FILE-<span class="green">${userid}</span>" class="ch.qos.logback.core.FileAppender"></b>
3843 <b>&lt;file><span class="green">${userid}</span>.log&lt;/file></b>
3844 <b>&lt;append>false&lt;/append></b>
3845 <b>&lt;layout class="ch.qos.logback.classic.PatternLayout"></b>
3846 <b>&lt;pattern>%d [%thread] %level %mdc %logger{35} - %msg%n&lt;/pattern></b>
3847 <b>&lt;/layout></b>
3848 <b>&lt;/appender></b>
3849 <b>&lt;/sift></b>
3850 &lt;/appender>
3851
3852 &lt;root level="DEBUG">
3853 &lt;appender-ref ref="SIFT" />
3854 &lt;/root>
3855 &lt;/configuration></pre>
3856
3857
3858 <p>In the absence of a class attribute, it is assumed that the
3859 discriminator type is <a
3860 href="../xref/ch/qos/logback/classic/sift/MDCBasedDiscriminator.html">MDCBasedDiscriminator</a>.
3861 The discriminating value is the MDC value associated with the key
3862 given by the <span class="prop">key</span> property. However, if
3863 that MDC value is null, then <span
3864 class="prop">defaultValue</span> is used as the discriminating
3865 value.
3866 </p>
3867
3868 <p>The <code>SiftingAppender</code> is unique in its capacity to
3869 reference and configure child appenders. In the above example,
3870 <code>SiftingAppender</code> will create multiple
3871 <code>FileAppender</code> instances, each
3872 <code>FileAppender</code> instance identified by the value
3873 associated with the "userid" MDC key. Whenever the "userid" MDC
3874 key is assigned a new value, a new <code>FileAppender</code>
3875 instance will be built from scratch. The
3876 <code>SiftingAppender</code> keeps track of the appenders it
3877 creates. Appenders unused for 30 minutes will be automatically
3878 closed and discarded.
3879 </p>
3880
3881 <p><span class="label notice">Variable export</span> It is not
3882 enough to have different appender instances; each instance must
3883 output to a distinct target resource. To allow such
3884 differentiation, within the appender template, the key passed to
3885 the discriminator, "userid" in the above example, is exported and
3886 becomes a <a
3887 href="configuration.html#variableSubstitution">variable</a>. Consequently,
3888 this variable can be used to differentiate the actual resource
3889 used by a given child appender.
3890 </p>
3891
3892 <p>Running the <code>SiftExample</code> application with the
3893 "byUserid.xml" configuration file shown above, will result in two
3894 distinct log files, "unknown.log" and "Alice.log".
3895 </p>
3896
3897 <p><span class="label">local-scoped variables</span> As of version
3898 1.0.12, properties defined in local scope within the configuration
3899 file will be available to nested appenders. Moreover, you can <a
3900 href="configuration.html#definingProps">define variables</a> or <a
3901 href="configuration.html#definingPropsOnTheFly">dynamically
3902 compute</a> variables from <em>within</em> the the
3903 <code>&lt;sift></code> element. Combining a variable from parts
3904 defined outside and within the <code>&lt;sift></code> element is
3905 also supported.
3906 </p>
3907
3908 <h4 class="doAnchor" name="siftGettingTimeoutRight">Getting the
3909 <span class="prop">timeout</span> right</h4>
3910
3911 <p>For certain types of applications, it may be difficult to get
3912 the <span class="prop">timeout</span> parameter right. If the
3913 <span class="prop">timeout</span> is too small, a nested appender
3914 might be removed just to be created anew a few seconds later. This
3915 phenomenon is called <em>trashing</em>. If the <span
3916 class="prop">timeout</span> is too long and appenders are created
3917 in quick succession, you might run out of resources. Similarly,
3918 setting <span class="prop">maxAppenderCount</span> too low might
3919 cause trashing as well.
3920 </p>
3921
3922 <p>In many case, it may be easier to pinpoint a location in your
3923 code after which a nested appender is no longer needed. If such a
3924 location exists, even approximately, log from that location using
3925 the <a
3926 href="../apidocs/ch/qos/logback/classic/ClassicConstants.html#FINALIZE_SESSION_MARKER">FINALIZE_SESSION</a>
3927 marker. Whenever SiftingAppender sees a logging event marked as
3928 <code>FINALIZE_SESSION</code> it will end-of-life the associated
3929 nested appender. Upon reaching its end-of-life, a nested appender
3930 will linger for a few seconds to process any late coming events
3931 (if any) and then will be closed.
3932 </p>
3933
3934 <pre class="prettyprint source">import org.slf4j.Logger;
3935 import static ch.qos.logback.classic.ClassicConstants.FINALIZE_SESSION_MARKER;
3936
3937 void job(String jobId) {
3938
3939 MDC.put("jobId", jobId);
3940 logger.info("Starting job.");
3941
3942 ... do whather the job needs to do
3943
3944 // will cause the nested appender reach end-of-life. It will
3945 // linger for a few seconds.
3946 logger.info(FINALIZE_SESSION_MARKER, "About to end the job");
3947
3948 try {
3949 .. perform clean up
3950 } catch(Exception e);
3951 // This log statement will be handled by the lingering appender.
3952 // No new appender will be created.
3953 logger.error("unexpected error while cleaning up", e);
3954 }
3955 }
3956
3957 </pre>
3958
3959 <h3 class="doAnchor" name="AsyncAppender">AsyncAppender</h3>
3960
3961 <p>AsyncAppender logs <a
3962 href="../apidocs/ch/qos/logback/classic/spi/ILoggingEvent.html">ILoggingEvent</a>s
3963 asynchronously. It acts solely as an event dispatcher and must
3964 therefore reference another appender in order to do anything
3965 useful.</p>
3966
3967 <p><span class="label notice">Lossy by default if 80% full</span>
3968 AsyncAppender buffers events in a <a
3969 href="http://docs.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/BlockingQueue.html">
3970 BlockingQueue</a>. A worker thread created by
3971 <code>AsyncAppender</code> takes events from the head of the
3972 queue, and dispatches them to the single appender attached to
3973 <code>AsyncAppender</code>. Note that by default,
3974 <code>AsyncAppender</code> will drop events of level TRACE, DEBUG
3975 and INFO if its queue is 80% full. This strategy has an amazingly
3976 favorable effect on performance at the cost of event loss.
3977 </p>
3978
3979 <p><span class="label">Application stop/redeploy</span> Upon
3980 application shutdown or redeploy, <code>AsyncAppender</code> must
3981 be stopped in order to stop and reclaim the worker thread and to
3982 flush the logging events from the queue. This can be achieved by
3983 <a href="configuration.html#stopContext">stopping the
3984 LoggerContext</a> which will close all appenders, including any
3985 <code>AsyncAppender</code> instances. <code>AsyncAppender</code>
3986 will wait for the worker thread to flush up to the timeout specified
3987 in <span class="prop">maxFlushTime</span>. If you find that queued events
3988 are being discarded during close of the <code>LoggerContext</code>, you
3989 may need to increase the time out. Specifying a value of 0 for
3990 <span class="prop">maxFlushTime</span> will force the <code>AsyncAppender</code>
3991 to wait for all queued events to be flushed before returning from
3992 the stop method.
3993 </p>
3994
3995 <p><span class="label">Post shutdown cleanup</span>
3996 Depending on the mode of JVM shutdown, the worker thread processing the
3997 queued events can be interrupted causing events to be strandeds in the
3998 queue. This generally occurs when the <code>LoggerContext</code> is not
3999 stopped cleanly or when the JVM terminates outside of the typical control
4000 flow. In order to avoid interrupting the worker thread under these
4001 conditions, a shutdown hook can be inserted to the JVM runtime that
4002 <a href="configuration.html#stopContext">stops the LoggerContext properly</a>
4003 after JVM shutdown has been initiated. A shutdown hook may also be the
4004 preferred method for cleanly shutting down Logback when other shutdown hooks
4005 attempt to log events.
4006 </p>
4007
4008
4009 <p>Here is the list of properties admitted by
4010 <code>AsyncAppender:</code></p>
4011
4012 <table class="bodyTable striped">
4013 <tr>
4014 <th>Property Name</th>
4015 <th>Type</th>
4016 <th>Description</th>
4017 </tr>
4018 <tr>
4019 <td><span class="prop" container="async">queueSize</span></td>
4020 <td><code>int</code></td>
4021 <td>The maximum capacity of the blocking queue. By default,
4022 <span class="prop">queueSize</span> is set to 256.
4023 </td>
4024 </tr>
4025 <tr>
4026 <td><span class="prop" container="async">discardingThreshold</span></td>
4027 <td><code>int</code></td>
4028 <td>By default, when the blocking queue has 20% capacity
4029 remaining, it will drop events of level TRACE, DEBUG and INFO,
4030 keeping only events of level WARN and ERROR. To keep all
4031 events, set <span class="prop">discardingThreshold</span> to
4032 0.
4033 </td>
4034 </tr>
4035 <tr>
4036 <td><span class="prop" container="async">includeCallerData</span></td>
4037 <td><code>boolean</code></td>
4038 <td>Extracting caller data can be rather expensive. To improve
4039 performance, by default, caller data associated with an event
4040 is not extracted when the event added to the event queue. By
4041 default, only "cheap" data like the thread name and the <a
4042 href="mdc.html">MDC</a> are copied. You can direct this
4043 appender to include caller data by setting the <span
4044 class="prop">includeCallerData</span> property to true.
4045 </td>
4046 </tr>
4047 <tr>
4048 <td><span class="prop" container="async">maxFlushTime</span></td>
4049 <td><code>int</code></td>
4050 <td>Depending on the queue depth and latency to the referenced appender,
4051 the <code>AsyncAppender</code> may take an unacceptable amount of
4052 time to fully flush the queue. When the <code>LoggerContext</code> is
4053 stopped, the <code>AsyncAppender stop</code> method waits
4054 up to this timeout for the worker thread to complete. Use
4055 <span class="prop">maxFlushTime</span> to specify a maximum queue flush
4056 timeout in milliseconds. Events that cannot be processed within this
4057 window are discarded. Semantics of this value are identical to that of
4058 <a href="http://docs.oracle.com/javase/7/docs/api/java/lang/Thread.html#join(long)">Thread.join(long)</a>.
4059 </td>
4060 </tr>
4061 <tr>
4062 <td><span class="prop" container="async">neverBlock</span></td>
4063 <td><code>boolean</code></td>
4064 <td>If <code>false</code> (the default) the appender will block on
4065 appending to a full queue rather than losing the message. Set to
4066 <code>true</code> and the appender will just drop the message and
4067 will not block your application.</td>
4068 </tr>
4069 </table>
4070
4071 <p>By default, event queue is configured with a maximum capacity
4072 of 256 events. If the queue is filled up, then application
4073 threads are blocked from logging new events until the worker
4074 thread has had a chance to dispatch one or more events. When the
4075 queue is no longer at its maximum capacity, application threads
4076 are able to start logging events once again. Asynchronous logging
4077 therefore becomes pseudo-synchronous when the appender is
4078 operating at or near the capacity of its event buffer. This is not
4079 necessarily a bad thing. The appender is designed to allow the
4080 application to keep on running, albeit taking slightly more time
4081 to log events until the pressure on the appenders buffer eases.
4082 </p>
4083
4084 <p>Optimally tuning the size of the appenders event queue for
4085 maximum application throughput depends upon several factors. Any
4086 or all of the following factors are likely to cause
4087 pseudo-synchronous behavior to be exhibited:</p>
4088
4089 <ul>
4090 <li>Large numbers of application threads</li>
4091 <li>Large numbers of logging events per application call</li>
4092 <li>Large amounts of data per logging event</li>
4093 <li>High latency of child appenders</li>
4094 </ul>
4095
4096 <p>To keep things moving, increasing the size of the queue will
4097 generally help, at the expense of heap available to the
4098 application.
4099 </p>
4100
4101
4102 <p><span class="label notice">Lossy behavior</span> In light of
4103 the discussion above and in order to reduce blocking, by default,
4104 when less than 20% of the queue capacity remains,
4105 <code>AsyncAppender</code> will drop events of level TRACE, DEBUG
4106 and INFO keeping only events of level WARN and ERROR. This
4107 strategy ensures non-blocking handling of logging events (hence
4108 excellent performance) at the cost loosing events of level TRACE,
4109 DEBUG and INFO when the queue has less than 20% capacity. Event
4110 loss can be prevented by setting the <span
4111 class="prop">discardingThreshold</span> property to 0 (zero).
4112 </p>
4113
4114 <p class="example">Example: <code>AsyncAppender</code>
4115 configuration
4116 (logback-examples/src/main/resources/chapters/appenders/conc/logback-async.xml)</p>
4117
4118 <span class="asGroovy" onclick="return asGroovy('asyncAppender');">View as .groovy</span>
4119
4120 <pre id="asyncAppender" class="prettyprint source">&lt;configuration>
4121 &lt;appender name="<b>FILE</b>" class="ch.qos.logback.core.FileAppender">
4122 &lt;file>myapp.log&lt;/file>
4123 &lt;encoder>
4124 &lt;pattern>%logger{35} - %msg%n&lt;/pattern>
4125 &lt;/encoder>
4126 &lt;/appender>
4127
4128 <b>&lt;appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender"></b>
4129 <b>&lt;appender-ref ref="FILE" /></b>
4130 <b>&lt;/appender></b>
4131
4132 &lt;root level="DEBUG">
4133 &lt;appender-ref ref="<b>ASYNC</b>" />
4134 &lt;/root>
4135 &lt;/configuration></pre>
4136
4137
4138 <h3 class="doAnchor" name="WriteYourOwnAppender">Writing your own
4139 Appender</h3>
4140
4141
4142 <p>You can easily write your appender by subclassing
4143 <code>AppenderBase</code>. It handles support for filters, status
4144 messages and other functionality shared by most appenders. The
4145 derived class only needs to implement one method, namely
4146 <code>append(Object eventObject)</code>.
4147 </p>
4148
4149 <p>The <code>CountingConsoleAppender</code>, which we list next,
4150 appends a limited number of incoming events on the console. It
4151 shuts down after the limit is reached. It uses a
4152 <code>PatternLayoutEncoder</code> to format the events and accepts
4153 a parameter named <code>limit</code>. Therefore, a few more
4154 methods beyond <code>append(Object eventObject)</code> are
4155 needed. As shown below, these parameters are handles
4156 auto-magically by logback's various configuration mechanisms.
4157 </p>
4158
4159 <em>Example 4.<span class="autoExec"/>:
4160 <code>CountingConsoleAppender</code>
4161 (logback-examples/src/main/java/chapters/appenders/CountingConsoleAppender.java)</em>
4162 <pre class="prettyprint source">package chapters.appenders;
4163
4164 import java.io.IOException;
4165
4166 import ch.qos.logback.classic.encoder.PatternLayoutEncoder;
4167 import ch.qos.logback.classic.spi.ILoggingEvent;
4168 import ch.qos.logback.core.AppenderBase;
4169
4170
4171 public class CountingConsoleAppender extends AppenderBase&lt;ILoggingEvent> {
4172 static int DEFAULT_LIMIT = 10;
4173 int counter = 0;
4174 int limit = DEFAULT_LIMIT;
4175
4176 PatternLayoutEncoder encoder;
4177
4178 public void setLimit(int limit) {
4179 this.limit = limit;
4180 }
4181
4182 public int getLimit() {
4183 return limit;
4184 }
4185
4186 @Override
4187 public void start() {
4188 if (this.encoder == null) {
4189 addError("No encoder set for the appender named ["+ name +"].");
4190 return;
4191 }
4192
4193 try {
4194 encoder.init(System.out);
4195 } catch (IOException e) {
4196 }
4197 super.start();
4198 }
4199
4200 public void append(ILoggingEvent event) {
4201 if (counter >= limit) {
4202 return;
4203 }
4204 // output the events as formatted by our layout
4205 try {
4206 this.encoder.doEncode(event);
4207 } catch (IOException e) {
4208 }
4209
4210 // prepare for next event
4211 counter++;
4212 }
4213
4214 public PatternLayoutEncoder getEncoder() {
4215 return encoder;
4216 }
4217
4218 public void setEncoder(PatternLayoutEncoder encoder) {
4219 this.encoder = encoder;
4220 }
4221 }</pre>
4222
4223 <p>The <code>start()</code> method checks for the presence of a
4224 <code>PatternLayoutEncoder</code>. In case the encoder is not
4225 set, the appender fails to start and emits an error message.
4226 </p>
4227
4228 <p>This custom appender illustrates two points:</p>
4229
4230 <ul>
4231
4232 <li>All properties that follow the setter/getter JavaBeans
4233 conventions are handled transparently by logback
4234 configurators. The <code>start()</code> method, which is called
4235 automatically during logback configuration, has the
4236 responsibility of verifying that the various properties of the
4237 appender are set and are coherent.
4238 </li>
4239
4240 <li>The <code>AppenderBase.doAppend()</code> method invokes the
4241 append() method of its derived classes. Actual output
4242 operations occur in the <code>append</code>() method. In
4243 particular, it is in this method that appenders format events by
4244 invoking their layouts.
4245 </li>
4246 </ul>
4247
4248 <p>The <a
4249 href="../xref/chapters/appenders/CountingConsoleAppender.html"><code>CountingConsoleAppender</code></a>
4250 can be configured like any other appender. See sample
4251 configuration file
4252 <em>logback-examples/src/main/resources/chapters/appenders/countingConsole.xml</em>
4253 for an example.
4254 </p>
4255
4256
4257 <h2 class="doAnchor" name="logback_access">Logback Access</h2>
4258
4259 <p>Most of the appenders found in logback-classic have their
4260 equivalent in logback-access. These work essentially in the same
4261 way as their logback-classic counterparts. In the next section, we
4262 will cover their use.
4263 </p>
4264
4265 <h3 class="doAnchor" name="AccessSocketAppender">SocketAppender
4266 and SSLSocketAppender</h3>
4267
4268 <p>The <a
4269 href="../xref/ch/qos/logback/access/net/SocketAppender.html">
4270 <code>SocketAppender</code></a> is designed to log to a remote
4271 entity by transmitting serialized <code>AccessEvent</code> objects
4272 over the wire. Remote logging is non-intrusive as far as the
4273 access event is concerned. On the receiving end after
4274 deserialization, the event can be logged as if it were generated
4275 locally.
4276 </p>
4277
4278 <p>The <a href="../xref/ch/qos/logback/access/net/SSLSocketAppender.html">
4279 <code>SSLSocketAppender</code></a> extends the basic
4280 <code>SocketAppender</code> allowing logging to a remote entity over
4281 the Secure Sockets Layer (SSL).
4282 </p>
4283
4284 <p>
4285 The properties of access' <code>SocketAppender</code> are the same as those available
4286 for classic's <code>SocketAppender</code>.
4287 </p>
4288
4289 <h3 class="doAnchor"
4290 name="AccessServerSocketAppender">ServerSocketAppender and
4291 SSLServerSocketAppender</h3>
4292
4293 <p>Like <code>SocketAppender</code>, the <a
4294 href="../xref/ch/qos/logback/access/net/server/ServerSocketAppender.html">
4295 <code>ServerSocketAppender</code></a> is designed to log to a remote
4296 entity by transmitting serialized <code>AccessEvent</code> objects
4297 over the wire. However, when using <code>ServerSocketAppender</code>
4298 the appender acts as a server, passively listening on a TCP socket awaiting
4299 inbound connections from interested clients. Logging events delivered
4300 to the appender are distributed to all connected clients.
4301 </p>
4302
4303 <p>The <a href="../xref/ch/qos/logback/access/net/server/SSLServerSocketAppender.html">
4304 <code>SSLSocketAppender</code></a> extends the basic
4305 <code>ServerSocketAppender</code> allowing logging to a remote entity
4306 over the Secure Sockets Layer (SSL).
4307 </p>
4308
4309 <p>The properties of access' <code>ServerSocketAppender</code> are
4310 the same as those available for classic's
4311 <code>ServerSocketAppender</code>.
4312 </p>
4313
4314
4315 <h3 class="doAnchor" name="AccessSMTPAppender">SMTPAppender</h3>
4316
4317 <p>Access' <a
4318 href="../xref/ch/qos/logback/access/net/SMTPAppender.html">
4319 <code>SMTPAppender</code></a> works in the same way as its Classic
4320 counterpart. However, the <span class="prop">evaluator</span>
4321 option is rather different. By default, a
4322 <code>URLEvaluator</code> object is used by
4323 <code>SMTPAppender</code>. This evaluator contains a list of URLs
4324 that are checked against the current request's URL. When one of
4325 the pages given to the <code>URLEvaluator</code> is requested,
4326 <code>SMTPAppender</code> sends an email.
4327 </p>
4328
4329 <p>
4330 Here is a sample configuration of a <code>SMTPAppender</code> in the access environment.
4331 </p>
4332 <p class="example">Example: <code>SMTPAppender</code>
4333 configuration
4334 (logback-examples/src/main/resources/chapters/appenders/conf/access/logback-smtp.xml)</p>
4335
4336 <pre class="prettyprint source">&lt;appender name="SMTP"
4337 class="ch.qos.logback.access.net.SMTPAppender">
4338 &lt;layout class="ch.qos.logback.access.html.HTMLLayout">
4339 &lt;pattern>%h%l%u%t%r%s%b&lt;/pattern>
4340 &lt;/layout>
4341
4342 <b>&lt;Evaluator class="ch.qos.logback.access.net.URLEvaluator">
4343 &lt;URL>url1.jsp&lt;/URL>
4344 &lt;URL>directory/url2.html&lt;/URL>
4345 &lt;/Evaluator></b>
4346 &lt;from>[email protected]&lt;/from>
4347 &lt;smtpHost>mail.domain.com&lt;/smtpHost>
4348 &lt;to>[email protected]&lt;/to>
4349 &lt;/appender></pre>
4350
4351 <p>This way of triggering the email lets users select pages that
4352 are important steps in a specific process, for example. When such
4353 a page is accessed, the email is sent with the pages that were
4354 accessed previously, and any information the user wants to be
4355 included in the email.
4356 </p>
4357
4358 <h3 class="doAnchor" name="AccessDBAppender">DBAppender</h3>
4359
4360 <p><a
4361 href="../xref/ch/qos/logback/access/db/DBAppender.html"><code>DBAppender</code></a>
4362 is used to insert the access events into a database.
4363 </p>
4364
4365 <p>Two tables are used by <code>DBAppender</code>:
4366 <em>access_event</em> and <em>access_event_header</em>. They both
4367 must exist before <code>DBAppender</code> can be used. Logback
4368 ships with SQL scripts that will create the tables. They can be
4369 found in the
4370 <em>logback-access/src/main/java/ch/qos/logback/access/db/script</em>
4371 directory. There is a specific script for each of the most popular
4372 database systems. If the script for your particular type of
4373 database system is missing, it should be quite easy to write one,
4374 taking as example one of the existing scripts. You are encouraged
4375 to contribute such missing scripts back to the project.
4376 </p>
4377
4378 <p>The <em>access_event</em> table's fields are described below:</p>
4379
4380 <table class="bodyTable striped">
4381 <tr>
4382 <th>Field</th>
4383 <th>Type</th>
4384 <th>Description</th>
4385 </tr>
4386 <tr>
4387 <td><b>timestamp</b></td>
4388 <td><code>big int</code></td>
4389 <td>The timestamp that was valid at the access event's creation.</td>
4390 </tr>
4391 <tr>
4392 <td><b>requestURI</b></td>
4393 <td><code>varchar</code></td>
4394 <td>The URI that was requested.</td>
4395 </tr>
4396 <tr>
4397 <td><b>requestURL</b></td>
4398 <td><code>varchar</code></td>
4399 <td>The URL that was requested. This is a string composed of the request method,
4400 the request URI and the request protocol.
4401 </td>
4402 </tr>
4403 <tr>
4404 <td><b>remoteHost</b></td>
4405 <td><code>varchar</code></td>
4406 <td>The name of the remote host.</td>
4407 </tr>
4408 <tr>
4409 <td><b>remoteUser</b></td>
4410 <td><code>varchar</code></td>
4411 <td>
4412 The name of the remote user.
4413 </td>
4414 </tr>
4415 <tr>
4416 <td><b>remoteAddr</b></td>
4417 <td><code>varchar</code></td>
4418 <td>The remote IP address.</td>
4419 </tr>
4420 <tr>
4421 <td><b>protocol</b></td>
4422 <td><code>varchar</code></td>
4423 <td>The request protocol, like <em>HTTP</em> or <em>HTTPS</em>.</td>
4424 </tr>
4425 <tr>
4426 <td><b>method</b></td>
4427 <td><code>varchar</code></td>
4428 <td>The request method, usually <em>GET</em> or <em>POST</em>.</td>
4429 </tr>
4430 <tr>
4431 <td><b>serverName</b></td>
4432 <td><code>varchar</code></td>
4433 <td>The name of the server that issued the request.</td>
4434 </tr>
4435 <tr>
4436 <td><b>event_id</b></td>
4437 <td><code>int</code></td>
4438 <td>The database id of the access event.</td>
4439 </tr>
4440 </table>
4441
4442 <p>
4443 The <em>access_event_header</em> table contains the header of each
4444 request. The information is organised as shown below:
4445 </p>
4446
4447 <table class="bodyTable striped">
4448 <tr>
4449 <th>Field</th>
4450 <th>Type</th>
4451 <th>Description</th>
4452 </tr>
4453 <tr>
4454 <td><b>event_id</b></td>
4455 <td><code>int</code></td>
4456 <td>The database id of the corresponding access event.</td>
4457 </tr>
4458 <tr>
4459 <td><b>header_key</b></td>
4460 <td><code>varchar</code></td>
4461 <td>The header name, for example <em>User-Agent</em>.</td>
4462 </tr>
4463 <tr>
4464 <td><b>header_value</b></td>
4465 <td><code>varchar</code></td>
4466 <td>The header value, for example <em>Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.1) Gecko/20061010 Firefox/2.0</em></td>
4467 </tr>
4468 </table>
4469
4470 <p>All properties of classic's <code>DBAppender</code> are available
4471 in access's <code>DBAppender</code>. The latter offers one more option,
4472 described below.
4473 </p>
4474
4475 <table class="bodyTable striped">
4476 <tr>
4477 <th>Property Name</th>
4478 <th>Type</th>
4479 <th>Description</th>
4480 </tr>
4481 <tr>
4482 <td>
4483 <b>
4484 <span class="prop">insertHeaders</span>
4485 </b>
4486 </td>
4487 <td>
4488 <code>boolean</code>
4489 </td>
4490 <td>
4491 Tells the <code>DBAppender</code> to populate the database with the header
4492 information of all incoming requests.
4493 </td>
4494 </tr>
4495 </table>
4496
4497 <p>Here is a sample configuration that uses <code>DBAppender</code>.</p>
4498
4499 <p class="example">Example: DBAppender configuration <em>(logback-examples/src/main/resources/chapters/appenders/conf/access/logback-DB.xml)</em></p>
4500
4501 <pre class="prettyprint source">&lt;configuration>
4502
4503 &lt;appender name="DB" class="ch.qos.logback.access.db.DBAppender">
4504 &lt;connectionSource class="ch.qos.logback.core.db.DriverManagerConnectionSource">
4505 &lt;driverClass>com.mysql.jdbc.Driver&lt;/driverClass>
4506 &lt;url>jdbc:mysql://localhost:3306/logbackdb&lt;/url>
4507 &lt;user>logback&lt;/user>
4508 &lt;password>logback&lt;/password>
4509 &lt;/connectionSource>
4510 &lt;insertHeaders>true&lt;/insertHeaders>
4511 &lt;/appender>
4512
4513 &lt;appender-ref ref="DB" />
4514 &lt;/configuration></pre>
4515
4516
4517 <h3 class="doAnchor"
4518 name="AccessSiftingAppender">SiftingAppender</h3>
4519
4520 <p>The SiftingAppender in logback-access is quite similar to its
4521 logback-classic counterpart. The main difference is that in
4522 logback-access the default discriminator, namely <a
4523 href="../xref/ch/qos/logback/access/sift/AccessEventDiscriminator.html">AccessEventDiscriminator</a>,
4524 is not MDC based. As its name suggests, AccessEventDiscriminator,
4525 uses a designated field in AccessEvent as the basis for selecting a
4526 nested appender. If the value of the designated field is null,
4527 then the value specified in the <span
4528 class="prop">defaultValue</span> property is used.
4529 </p>
4530
4531 <p>The designated AccessEvent field can be one of COOKIE,
4532 REQUEST_ATTRIBUTE, SESSION_ATTRIBUTE, REMOTE_ADDRESS, LOCAL_PORT,
4533 REQUEST_URI. Note that the first three fields require that the
4534 <span class="prop">AdditionalKey</span> property also be
4535 specified.</p>
4536
4537 <p>Below is an example configuration file.</p>
4538
4539 <p class="example">Example: SiftingAppender configuration (logback-examples/src/main/resources/chapters/appenders/conf/sift/access-siftingFile.xml)</p>
4540
4541 <pre class="prettyprint source">&lt;configuration>
4542 &lt;appender name="SIFTING" class="ch.qos.logback.access.sift.SiftingAppender">
4543 &lt;Discriminator class="ch.qos.logback.access.sift.AccessEventDiscriminator">
4544 &lt;Key>id&lt;/Key>
4545 &lt;FieldName>SESSION_ATTRIBUTE&lt;/FieldName>
4546 &lt;AdditionalKey>username&lt;/AdditionalKey>
4547 &lt;defaultValue>NA&lt;/defaultValue>
4548 &lt;/Discriminator>
4549 &lt;sift>
4550 &lt;appender name="${id}" class="ch.qos.logback.core.FileAppender">
4551 &lt;file>byUser/${id}.log&lt;/file>
4552 &lt;layout class="ch.qos.logback.access.PatternLayout">
4553 &lt;pattern>%h %l %u %t \"%r\" %s %b&lt;/pattern>
4554 &lt;/layout>
4555 &lt;/appender>
4556 &lt;/sift>
4557 &lt;/appender>
4558 &lt;appender-ref ref="SIFTING" />
4559 &lt;/configuration></pre>
4560
4561
4562 <p>In the above configuration file, a <code>SiftingAppender</code>
4563 nests <code>FileAppender</code> instances. The key "id" is
4564 designated as a variable which will be available to the nested
4565 <code>FileAppender</code> instances. The default discriminator,
4566 namely <code>AccessEventDiscriminator</code>, will search for a
4567 "username" session attribute in each <code>AccessEvent</code>. If
4568 no such attribute is available, then the default value "NA" will
4569 be used. Thus, assuming the session attribute named "username"
4570 contains the username of each logged on user, there will be a log
4571 file under the <em>byUser/</em> folder (of the current folder)
4572 named after each user containing the access logs for that user.
4573 </p>
4574
4575
4576 <script src="../templates/footer.js" type="text/javascript"></script>
4577
4578
4579 </div>
4580
4581 </body>
4582 </html>