Author: ceki Date: Wed Mar 14 22:32:01 2007 New Revision: 1429 Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html Log: improved text, ongoing work Modified: logback/trunk/logback-site/src/site/pages/manual/layouts.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/layouts.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/layouts.html Wed Mar 14 22:32:01 2007 @@ -22,6 +22,14 @@ <h1>Chapter 5: Layouts</h1> + <div class="quote"> + <p>TCP implementations will follow a general principle of + robustness: be conservative in what you do, be liberal in what + you accept from others. + </p> + <p>-- JON POSTEL, RFC 793</p> + </div> + <script src="../templates/creative.js"></script> <div class="highlight"> @@ -935,23 +943,26 @@ </tr> </table> - <p>Here are some examples of the format modifier truncation:</p> + <p>The table below list examples for format modifier + truncation. Please note that the brackets, i.e the pair of "[]" + characters, are not part of the output. They are used to delimit + the width of output.</p> <table class="bodyTable" BORDER="0" CELLPADDING="8"> <th>Format modifier</th> <th>Logger name</th> - <th>Result</th> - <tr class="a"> - <td align="center">[%-20.20logger]</td> - <td align="center">main.Name</td> - <td align="center"><pre>[main.Name ]</pre></td> - </tr> + <th>Result</th> <tr class="b"> <td align="center">[%20.20logger]</td> <td align="center">main.Name</td> <td align="center"><pre>[ main.Name]</pre></td> </tr> + <tr class="a"> + <td align="center">[%-20.20logger]</td> + <td align="center">main.Name</td> + <td align="center"><pre>[main.Name ]</pre></td> + </tr> <tr class="a"> <td align="center">[%10.10logger]</td> <td align="center">main.foo.foo.bar.Name</td> @@ -964,18 +975,20 @@ </tr> </table> - <h3>Option handling</h3> + <h3>Options</h3> <p> - A conversion specifier can be followed by options between - braces. We have already seen some of the - possibilities offered by logback's option handling with, for - example, the MDC conversion specifier: + A conversion specifier can be followed by options. The are + always declared between braces. We have already seen some of the + possibilities offered by options, for instance in conjunction + with the MDC conversion specifier, as in: <em>%mdc{someKey}</em>. </p> - <p>A conversion specifier might have more than one options. For example, - a conversion specifier that uses evaluators, which we will cover very soon, - simply adds the evaluator names to the option list, as shown below:</p> + + <p>A conversion specifier might have more than one option. For + example, a conversion specifier that makes use of evaluators, + which will be covered soon, may add evaluator names to the option + list, as shown below:</p> <div class="source"><pre> <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> @@ -986,43 +999,30 @@ </appender></pre></div> - XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + <h3>Evaluators</h3> - <h4>Evaluators</h4> - <p> - Another use case for adding options to a conversion - specifier is when - <code>PatternLayout</code> - is used with - <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> - <code>EventEvaluator</code></a> objects. - </p> - <p> - <code>EventEvaluator</code> objects - have the responsability to check wether a given event - matches a given criteria. - </p> - <p> - Let's look at an example using - <code>EventEvaluator</code> objects. - The following configuration file outputs the logging - events to the console, displaying date, thread, level, - message and caller data. - </p> - <p> - Since displaying the caller data of a logging event is rather - expensive, this information will be displayed only when the - logging request comes from a specific logger, and whose - message contains a certain string. By doing that, we make - sure that only the specific logging requests will have - their caller information generated and displayed, without - penalizing application performance. + <p>As mentioned above, option lists come in handy when a + conversion specifier is required to behave dynamically based on + one or more + <a href="../xref/ch/qos/logback/core/boolex/EventEvaluator.html"> + <code>EventEvaluator</code></a> objects. + <code>EventEvaluator</code> objects have the responsibility to + determine whether a given logging event matches the criteria of the + evaluator. + </p> + + <p>Let us review an example with <code>EventEvaluator</code> + objects. The following configuration file outputs the logging + events to the console, displaying date, thread, level, message and + caller data. Given that extracting the caller data of a logging + event is on expensive side, we will do so only when the logging + request originates from a specific logger, and whose message + contains a certain string. Thus, we make sure that only specific + logging requests will have their caller information generated and + displayed. In other cases, where the caller data is superfluous, + we will not penalize application performance. </p> - <p> - Here is how to configure logback to behave like we - described: - </p> <em> Example 5.2: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/callerEvaluatorConfig.xml) @@ -1045,14 +1045,19 @@ <appender-ref ref="STDOUT" /> </root> </configuration></pre></div> - <p>Please note that the & value cannot be written like one would do in a java - class, because of XML encoding rules.</p> - <p>Let us test this configuration with the following code.</p> - <em> + + <p>Due to XML encoding rules, the & character cannot be + written as is, and needs to be escaped as &.</p> + + <p>The above configuration file is designed to be accompanied by + the following custom-tailored code.</p> + + <p><em> Example 5.2: Sample usage of EventEvaluators <a href="../xref/chapter5/CallerEvaluatorExample.html"> (logback-examples/src/main/java/chapter5/CallerEvaluatorExample.java)</a> </em> + </p> <div class="source"><pre>package chapter5; import org.slf4j.Logger; @@ -1087,51 +1092,58 @@ } }</pre></div> <p> - The above application does nothing too fancy. Five logging - requests are issued, the third one being different from the - others. + The <em>CallerEvaluatorExample</em> application does nothing particularly + fancy. Five logging requests are issued, the third one being + different from the others. </p> <p> - When a logging request is sent, the corresponding logging event - will pass through the evaluation process. Here, the third - request will match the evaluation criteria, causing its caller - data to be displayed. + When a logging request is issued, the corresponding logging + event goes through the evaluation process. The third request + matches the evaluation criteria, causing its caller data to be + displayed. </p> + <p> Here is the output of the <code>CallerEvaluatorExample</code> class. </p> + <div class="source"><pre>0 [main] DEBUG - I know me 0 0 [main] DEBUG - I know me 1 0 [main] DEBUG - I know me 2 0 [main] DEBUG - who calls thee? Caller+0 at chapter5.CallerEvaluatorExample.main(CallerEvaluatorExample.java:28) - 0 [main] DEBUG - I know me 4</pre></div> - <p>One can change the expression to match a real world - situation. An expression testing logger name and request level - could also be meaningful: all logging requests of level - <em>WARN</em> and up, coming from a sensible part of an - application like a financial transaction module, would have their - caller data displayed. + <p>One can change the expression to correspond a real world + scenario. For instance, one could combine the logger name and + request level. Thus, logging requests of level <em>WARN</em> and + up, originating from a sensitive part of an application, e.g. a + financial transaction module, would have their caller data + displayed. </p> <p><b>Important:</b> With the <em>caller</em> conversion specifier, the data is displayed when <em>the expression evaluates to <b>true</b>.</em></p> - <p>Now, let us look at a different situation. When exceptions are + <p>Let us consider at a different situation. When exceptions are included in a logging request, their stack trace is usually displayed. However, in some cases, one might want to supress the - stack trace of specific exception. + stack trace of some specific exception. </p> - <p>The java code shown below creates five log requests, each one - with an exception. However, we do not want to have the stack trace - of the third request to be output.</p> + <p>The java code shown below creates five log requests, each with + an exception. However, it so happends that we do not wish the + stack trace of the third request to be output.</p> + <p><em> + Example 5.2: Sample usage of EventEvaluators + <a href="../xref/chapter5/ExceptionEvaluatorExample.html"> + (logback-examples/src/main/java/chapter5/ExceptionEvaluatorExample.java)</a> + </em> + </p> <div class="source"><pre>package chapter5; import org.slf4j.Logger; @@ -1166,7 +1178,8 @@ } }</pre></div> - <p>The following configuration will allow that.</p> + <p>The following configuration will supress the stack trace of the + third logging request.</p> <em> Example 5.3: Sample usage of EventEvaluators (logback-examples/src/main/java/chapter5/exceptionEvaluatorConfig.xml) @@ -1193,31 +1206,38 @@ </root> </configuration></pre></div> - <p> - With this configuration, each time an instance of the - <em>chapter5.TestException</em> - is included within a logging request, no stack trace will be displayed. + <p>With this configuration, each time an instance of the + <em>chapter5.TestException</em> is included within a logging + request, the stack trace will be suppressed. </p> - <p><b>Important:</b> With the <b><em>%ex</em></b> conversion specifier, the data is - displayed when <em>the expression evaluates to <b>false</b>.</em></p> + + <p><b>Important:</b> With the <b><em>%ex</em></b> conversion + specifier, the stack trace is displayed when <em>the expression + evaluates to <b>false</b>.</em></p> <h3>Creating a custom conversion specifier</h3> - <p>We've seen up to here quite a lot of possibilities with conversion specifier and - <code>PatternLayout</code> objects. But what if somebody wants to make her own conversion - specifier?</p> - - <p>In that case, two steps are needed.</p> - - <p>First, one must implement her own <code>Converter</code> - class. <a href="../xref/ch/qos/logback/core/pattern/Converter.html"> - <code>Converter</code></a> objects are responsible to extract a specific information out of - a <code>LoggingEvent</code>. When <em>%logger</em> is used, a - <a href="../xref/ch/qos/logback/classic/pattern/LoggerConverter.html"> - <code>LoggerConverter</code></a> - is called to extract the name of the logger from the <code>LoggingEvent</code>.</p> + + <p>Up to this point we have presented the built-inconversion + specifiers of <code>PatternLayout</code>. But it is also possible + to use a conversion specifier of your own making.</p> + + <p>Building a custom conversion specifier consists of two steps. + </p> - <p>Let us say that our customized <code>Converter</code> will output the level of the logging - event, colored following ANSI rules. Here is the necessary implementation:</p> + <p>First, you must sub-class the <code>Converter</code> class. <a + href="../xref/ch/qos/logback/core/pattern/Converter.html"> + <code>Converter</code></a> objects are responsible for extracting + information out of <code>LoggingEvent</code> objects and returning + it as String. For example, the + <a href="../xref/ch/qos/logback/classic/pattern/LoggerConverter.html"> + <code>LoggerConverter</code></a>, the converter underlying the + %logger conversion word, extracts the name of the logger from the + <code>LoggingEvent</code> and returns it as a String. It might + abbreviate the logger name in the process.</p> + + <p>Let us say that our customized <code>Converter</code> colors + the level of the logging event, according to ANSI terminal + conventions. Here is a possible implementation:</p> <em> Example 5.4: Sample Converter Example <a href="../xref/chapter5/MySampleConverter.html"> @@ -1261,14 +1281,19 @@ } </pre></div> - <p>This implementation is quite straightforward. The <code>MySampleConverter</code> class - extends <code>ClassicConverter</code>, and implements the <code>convert</code> method. - In that method, all it has to do is return the appropriate information. + +java chapter5.SampleLogging src/main/java/chapter5/mySampleConverterConfig.xml + + <p>This implementation is relatively straightforward. The + <code>MySampleConverter</code> class extends + <code>ClassicConverter</code>, and implements the + <code>convert</code> method where it returns a level string + decorated with ANSI coloring codes. </p> - <p>The second step, once the <code>Converter</code> class done, is to let logback know about - the new <code>Converter</code>. For this task, we just need to declare the new - conversion word in the configuration file, as shown below:</p> + <p>In the second step, we must let logback know about the new + <code>Converter</code>. For this purpose, we need to declare the + new conversion word in the configuration file, as shown below:</p> <em> Example 5.4: Sample Converter Example (src/main/java/chapter5/mySampleConverterConfig.xml)</em> <div class="source"><pre><configuration> @@ -1288,17 +1313,37 @@ </root> </configuration></pre></div> - <p>In this configuration file, once the new conversion word has been declared, we - just use it within a <code>PatternLayout</code> pattern element, as if - our custom conversion word had always been here.</p> - - <p>The intersted reader might want to take a look at other <code>Converter</code> implementations - like + <p>In this configuration file, once the new conversion word has + been declared, we can refert to it within a + <code>PatternLayout</code> pattern, as if the custom conversion + word had always been here.</p> + + <p>Given that ANSI terminal codes do not work on Windows, you can + view the results on non-Windows platforms such as Linux or + Mac. The following command:</p> + + <div class="source">java chapter5.SampleLogging src/main/java/chapter5/mySampleConverterConfig.xml </div> + + <p>should yield:</p> + +<div class="source">0 [main] DEBUG - Everything's going well +3 [main] <span class="red">ERROR</span> - maybe not quite... </div> + +XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXxxxx + + <p>Please note that the string "ERROR" is highlighted in red, + which is basically the whole point of the exercise.</p> + + <p>The intersted reader might want to take a look at other + <code>Converter</code> implementations such as <a href="../xref/ch/qos/logback/classic/pattern/MDCConverter.html"> - <code>MDCConverter</code></a> to learn how to implement more complex behaviours, involving - the use of options, in her custom <code>Converter</code> objects. + <code>MDCConverter</code></a> to learn how to implement more + complex behaviour, such as option handling. </p> + + + <a name="ClassicHTMLLayout"></a> <h3>HTMLLayout</h3> <p><a href="../xref/ch/qos/logback/classic/html/HTMLLayout.html">