Author: seb Date: Fri Oct 20 18:42:32 2006 New Revision: 734 Modified: logback/trunk/logback-classic/examples/src/chapter5/callerEvaluatorConfig.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Log: Work in progress - Removed mentions of DATE and ABSOLUTE keywords - Added truncation examples - Added %ex examples - other fixes... Modified: logback/trunk/logback-classic/examples/src/chapter5/callerEvaluatorConfig.xml ============================================================================== --- logback/trunk/logback-classic/examples/src/chapter5/callerEvaluatorConfig.xml (original) +++ logback/trunk/logback-classic/examples/src/chapter5/callerEvaluatorConfig.xml Fri Oct 20 18:42:32 2006 @@ -8,7 +8,7 @@ class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> <param name="Pattern" - value="%-4relative [%thread] %-5level - %msg %caller{2, DISPLAY_CALLER_EVAL}%n" /> + value="%-4relative [%thread] %-5level - %msg%n %caller{2, DISPLAY_CALLER_EVAL}" /> </layout> </appender> Modified: logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Fri Oct 20 18:42:32 2006 @@ -274,25 +274,40 @@ <b>date</b>{<em>pattern</em>} <br /> </td> <td> - <p> - Used to output the date of the logging event. - The date conversion word may be followed by - a set of braces containing a date and time - pattern strings used by - <code>java.text.SimpleDateFormat</code>, - <em>ABSOLUTE</em>, <em>DATE</em> or - <em>ISO8601</em> can also be used. - </p> - <b>Tableau 2 colonnes, pattern -> result, date fixée.</b> - <p> - For example, - <b>%d{HH:mm:ss,SSS}</b>, - <b> - %d{dd MMM yyyy ;HH:mm:ss,SSS} - </b> - or <b>%d{DATE}</b>. If no date format specifier is given then - ISO8601 format is assumed. <b>Reprendre du texte du livre.</b> - </p> + <p>Used to output the date of the logging event. + The date conversion word may be followed by an option + enclosed between braces.</p> + <p>The option admits the same syntax as the time pattern + string of the <code>java.text.SimpleDateFormat</code>.</p> + <p>A shortcut to the ISO8601 format is available by + specifying <em>ISO8601</em> in the braces. If no option is set, + the converter uses <em>ISO8601</em> as a default value.</p> + <p>Here are some sample option values. They assume + that the actual date is Friday 20th of October, 2006 and that + the reader finished her meal a short while ago.</p> + + <table BORDER="1" CELLPADDING="8"> + <tr> + <th>Conversion Pattern</th> + <th>Result</th> + </tr> + <tr> + <td>%date</td> + <td>2006-10-20 14:46:49,812</td> + </tr> + <tr> + <td>%date{ISO8601}</td> + <td>2006-10-20 14:46:49,812</td> + </tr> + <tr> + <td>%date{HH:mm:ss.SSS}</td> + <td>14:46:49.812</td> + </tr> + <tr> + <td>%date{dd MMM yyyy ;HH:mm:ss.SSS}</td> + <td>20 oct. 2006;14:46:49.812 </td> + </tr> + </table> </td> </tr> @@ -307,10 +322,9 @@ request was issued. </p> <p> - <b>WARNING</b> - Generating caller file information is extremely - slow. Its use should be avoided unless execution - speed is not an issue. + Generating the file information is not particularly fast. + Thus, it's use should be avoided unless + execution speed is not an issue. </p> </td> </tr> @@ -375,10 +389,9 @@ logging request was issued. </p> <p> - <b>WARNING</b> - Generating caller location information is - extremely slow. It's use should be avoided - unless execution speed is not an issue. + Generating the line number information is not particularly fast. + Thus, it's use should be avoided unless + execution speed is not an issue. </p> </td> </tr> @@ -405,10 +418,9 @@ request was issued. </p> <p> - <b>WARNING</b> - Generating caller location information is - extremely slow. It's use should be avoided - unless execution speed is not an issue. + Generating the method name is not particularly fast. + Thus, it's use should be avoided unless + execution speed is not an issue. </p> </td> </tr> @@ -507,7 +519,8 @@ </tr> <tr> <td align="center"> - <b>ex / throwable</b> + <b>ex</b>{<em>length</em>} <br /> + <b>throwable</b>{<em>length</em>} <br /> </td> <td> @@ -516,20 +529,55 @@ with the logging event, if any. By default the full stack trace will be output. </p> - <p>If - <em>throwable</em> conversion word is followed by an - option in the form - <b>%throwable{short}</b> - which will only output the first line of the - ThrowableInformation. - </p> + <p>The <em>throwable</em> conversion word can followed by one of + the following options:$ + </p> + <ul> + <p><em>short</em>: prints the first line of the stack trace</p> + <p><em>full</em>: prints the full stack trace</p> + <p>Any integer: prints the given number of lines of the stack trace</p> + </ul> + + <p>Here are some examples:</p> + + <table BORDER="1" CELLPADDING="8"> + <tr> + <th>Conversion Pattern</th> + <th>Result</th> + </tr> + <tr> + <td>%ex</td> + <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem + at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) + at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17) + at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)</pre></td> + </tr> + <tr> + <td>%ex{short}</td> + <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem + at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22)</pre></td> + </tr> + <tr> + <td>%ex{full}</td> + <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem + at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) + at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17) + at mainPackage.ExceptionLauncher.main(ExceptionLauncher.java:38)</pre></td> + </tr> + <tr> + <td>%ex{2}</td> + <td><pre>mainPackage.foo.bar.TestException: Houston we have a problem + at mainPackage.foo.bar.TestThrower.fire(TestThrower.java:22) + at mainPackage.foo.bar.TestThrower.readyToLaunch(TestThrower.java:17)</pre></td> + </tr> + </table> <p> This conversion word can also use evaluators to test logging events against a given criteria before creating the output. For example, using <b>%ex{full, EX_DISPLAY_EVAL}</b> will display the full stacktrace of the exception, only if the evaluator called <em>EX_DISPLAY_EVAL</em> - returns a <b>negative</b> answer. This behaviour comes from the fact that + returns a <b>negative</b> answer. This behaviour is justified by the fact that throwable data is generally displayed unless the evaluator would return a positive value. Evaluators are described further down this document. @@ -579,15 +627,21 @@ modifier which is designated by a period followed by a decimal constant. If the data item is longer than the maximum field, then the extra characters are removed from - the - <em>beginning</em> - of the data item and not from the end. For example, it the + the <em>beginning</em> + of the data item. For example, if the maximum field width is eight and the data item is ten characters long, then the first two characters of the data item are dropped. This behavior deviates from the printf function in C where truncation is done from the end. </p> <p> + Truncation from the end is possible by appending a minus + character right after the period. In that case, if the + maximum field width is eight and the data item is ten + characters long, then the last two characters of the data + item are dropped. + </p> + <p> Below are various format modifier examples for the logger conversion specifier. </p> @@ -600,7 +654,7 @@ <th>Comment</th> <tr> - <td align="center">%20l</td> + <td align="center">%20logger</td> <td align="center">false</td> <td align="center">20</td> <td align="center">none</td> @@ -610,7 +664,7 @@ </td> </tr> <tr> - <td align="center">%-20l</td> + <td align="center">%-20logger</td> <td align="center">true</td> <td align="center">20</td> <td align="center">none</td> @@ -620,7 +674,7 @@ </td> </tr> <tr> - <td align="center">%.30l</td> + <td align="center">%.30logger</td> <td align="center">NA</td> <td align="center">none</td> <td align="center">30</td> @@ -630,7 +684,7 @@ </td> </tr> <tr> - <td align="center">%20.30l</td> + <td align="center">%20.30logger</td> <td align="center">false</td> <td align="center">20</td> <td align="center">30</td> @@ -642,7 +696,7 @@ </td> </tr> <tr> - <td align="center">%-20.30l</td> + <td align="center">%-20.30logger</td> <td align="center">true</td> <td align="center">20</td> <td align="center">30</td> @@ -653,8 +707,46 @@ beginning. </td> </tr> + <tr> + <td align="center">%.-30logger</td> + <td align="center">NA</td> + <td align="center">none</td> + <td align="center">30</td> + <td> + Truncate from the end if the logger name is + longer than 30 characters. + </td> + </tr> </table> + + <p>Here are some examples of the format modifier truncation:</p> + + <table BORDER="1" CELLPADDING="8"> + <th>Format modifier</th> + <th>Logger name</th> + <th>Result</th> + <tr> + <td align="center">[%-20.20logger]</td> + <td align="center">main.Name</td> + <td align="center"><pre>[main.Name ]</pre></td> + </tr> + <tr> + <td align="center">[%20.-20logger]</td> + <td align="center">main.Name</td> + <td align="center"><pre>[ main.Name]</pre></td> + </tr> + <tr> + <td align="center">[%-10.10logger]</td> + <td align="center">main.foo.foo.bar.Name</td> + <td align="center"><pre>[o.bar.Name]</pre></td> + </tr> + <tr> + <td align="center">[%10.-10logger]</td> + <td align="center">main.foo.foo.bar.Name</td> + <td align="center"><pre>[main.foo.f]</pre></td> + </tr> + </table> <h3>Option handling</h3> @@ -663,8 +755,7 @@ braces. We have already seen some of the possibilities offered by logback's option handling with, for example, the MDC conversion specifier: - <em>%mdc{someKey}</em> - . + <em>%mdc{someKey}</em>. </p> <p>However, there is more to it than that.</p> @@ -692,7 +783,7 @@ message and caller data. </p> <p> - Since displaying the caller data of a logging event is very + 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 @@ -717,7 +808,7 @@ <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> <layout class="ch.qos.logback.classic.PatternLayout"> - <param name="Pattern" value="%-4relative [%thread] %-5level - %msg \ + <param name="Pattern" value="%-4relative [%thread] %-5level - %msg%n \ <b>%caller{2, DISP_CALLER_EVAL}</b>%n" /> </layout> </appender>