Author: seb Date: Thu Oct 12 18:31:33 2006 New Revision: 669 Added: logback/trunk/logback-classic/examples/src/chapter5/EventEvaluatorExample.java logback/trunk/logback-classic/examples/src/chapter5/eventEvaluatorConfig.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/ logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml - copied, changed from r668, /logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml Removed: logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/joran/EvaluatorJoranTest.java logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Log: Work in progress on layouts.xml and corresponding examples. - minor javadoc fix on PatternLayout.java - added a test to EvaluatorJoranTest.java - supressed sysout call in Interpreter.java - added manual directory to contain manual chapters Added: logback/trunk/logback-classic/examples/src/chapter5/EventEvaluatorExample.java ============================================================================== --- (empty file) +++ logback/trunk/logback-classic/examples/src/chapter5/EventEvaluatorExample.java Thu Oct 12 18:31:33 2006 @@ -0,0 +1,32 @@ +package chapter5; + +import org.slf4j.LoggerFactory; + +import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.joran.JoranConfigurator; +import ch.qos.logback.core.util.StatusPrinter; + +public class EventEvaluatorExample { + + public static void main(String[] args) throws InterruptedException { + Logger logger = (Logger) LoggerFactory.getLogger(EventEvaluatorExample.class); + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + + JoranConfigurator configurator = new JoranConfigurator(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + + StatusPrinter.print(lc); + + for (int i = 0; i < 5; i++) { + if (i == 3) { + logger.debug("stacktrace logging statement" + i); + } else { + logger.debug("logging statement" + i); + } + } + + StatusPrinter.print(lc); + } +} \ No newline at end of file Added: logback/trunk/logback-classic/examples/src/chapter5/eventEvaluatorConfig.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-classic/examples/src/chapter5/eventEvaluatorConfig.xml Thu Oct 12 18:31:33 2006 @@ -0,0 +1,20 @@ +<configuration> + + <evaluator name="DISPLAY_CALLER_EVAL"> + <!-- >Expression>(logger.name.contains("chapter5"))</Expression--> + <Expression>message.contains("stacktrace") && message.contains("logging")</Expression> + </evaluator> + + <appender name="STDOUT" + 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" /> + </layout> + </appender> + + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration> \ No newline at end of file Modified: logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java ============================================================================== --- logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java (original) +++ logback/trunk/logback-classic/src/main/java/ch/qos/logback/classic/PatternLayout.java Thu Oct 12 18:31:33 2006 @@ -240,7 +240,7 @@ * </tr> * * <tr> - * <td align=center><b>X</b></td> + * <td align=center><b>X / mdc</b></td> * * <td> * @@ -402,7 +402,7 @@ * * <tr> * <th>Conversion Pattern</th> - * <th>Class name</th> + * <th>Logger name</th> * <th>Result</th> * </tr> * Modified: logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/joran/EvaluatorJoranTest.java ============================================================================== --- logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/joran/EvaluatorJoranTest.java (original) +++ logback/trunk/logback-classic/src/test/java/ch/qos/logback/classic/joran/EvaluatorJoranTest.java Thu Oct 12 18:31:33 2006 @@ -20,7 +20,6 @@ import ch.qos.logback.classic.Logger; import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.boolex.JaninoEventEvaluator; -import ch.qos.logback.classic.joran.JoranConfigurator; import ch.qos.logback.classic.spi.LoggingEvent; import ch.qos.logback.classic.util.Constants; import ch.qos.logback.core.CoreGlobal; @@ -65,11 +64,14 @@ Logger logger = loggerContext.getLogger("xx"); - //LoggingEvent event = new LoggingEvent("foo", logger, Level.DEBUG, "Hello world",null); - //StatusPrinter.print(loggerContext.getStatusManager()); - //assertTrue(evaluator.evaluate(event)); + JaninoEventEvaluator evaluator = (JaninoEventEvaluator) evalMap.get("IGNORE_EVAL"); + LoggingEvent event = new LoggingEvent("foo", logger, Level.DEBUG, "Hello world",null, null); + StatusPrinter.print(loggerContext.getStatusManager()); Marker ignoreMarker = MarkerFactory.getMarker("IGNORE"); + event.setMarker(ignoreMarker); + assertTrue(evaluator.evaluate(event)); + logger.debug("hello", new Exception("test")); logger.debug(ignoreMarker, "hello ignore", new Exception("test")); @@ -77,4 +79,22 @@ StatusPrinter.print(loggerContext.getStatusManager()); } + + public void testMultipleConditionsInExpression() throws NullPointerException, EvaluationException { + LoggerContext loggerContext = new LoggerContext(); + Logger logger = loggerContext.getLogger("xx"); + JaninoEventEvaluator ee = new JaninoEventEvaluator(); + ee.setName("testEval"); + ee.setContext(loggerContext); + //&& + //&& + ee.setExpression("message.contains(\"stacktrace\") && message.contains(\"logging\")"); + ee.start(); + StatusPrinter.print(loggerContext); + + String message = "stacktrace bla bla logging"; + LoggingEvent event = new LoggingEvent(this.getClass().getName(), logger, Level.DEBUG, message, null, null); + + assertTrue(ee.evaluate(event)); + } } Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/spi/Interpreter.java Thu Oct 12 18:31:33 2006 @@ -128,7 +128,7 @@ body = body.trim(); } if(body.length() > 0) { - System.out.println("calling body method with ["+body+ "]"); + //System.out.println("calling body method with ["+body+ "]"); callBodyAction(applicableActionList, body); } } Modified: logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml ============================================================================== --- logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/documentation.xml Thu Oct 12 18:31:33 2006 @@ -8,7 +8,7 @@ <body> - <h2>logback documentation</h2> + <h2>Logback documentation</h2> <p>Below is a list of documentaiton currently available for the logback project.</p> @@ -20,19 +20,21 @@ <li> <a href="accessLogJetty.html"><b>A short introduction to access logging with logback-access and Jetty</b></a> </li> - - <li> - <a href="layouts.html"><b>Layout reference</b></a> - </li> - <li> <a href="apidocs/index.html"><b>Javadoc</b></a> </li> - <li> <a href="joran.html"><b>A introduction to Joran</b></a> </li> </ul> + + <p>A complete manual about logback is in the works at the moment. Each chapter will be + put online as soon as it's complete. You can access the manual page by following the link + below.</p> + + <ul> + <li><a href="manual/index.html"><b>Complete logback manual</b></a></li> + </ul> </body> </document> \ No newline at end of file Added: logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml ============================================================================== --- (empty file) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/index.xml Thu Oct 12 18:31:33 2006 @@ -0,0 +1,24 @@ +<?xml version="1.0"?> +<document> + + <properties> + <author email="ceki at qos ddoott ch ">Ceki Gulcu</author> + <title>Documentations</title> + </properties> + + <body> + + <h2>Logback manual</h2> + + <p>Welcome to the main page of the logback manual.</p> + + <p>At the moment, only one chapter is available. More to come.</p> + + <ul> + <li> + <a href="layouts.html"><b>Manual Chapter 5: Layout reference</b></a> + </li> + </ul> + + </body> +</document> \ No newline at end of file Copied: logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml (from r668, /logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml) ============================================================================== --- /logback/trunk/logback-site/src/site/xdocTemplates/layouts.xml (original) +++ logback/trunk/logback-site/src/site/xdocTemplates/manual/layouts.xml Thu Oct 12 18:31:33 2006 @@ -9,7 +9,7 @@ <body> - <h2>Layouts</h2> + <h2>Chapter 5: Layouts</h2> <div class="author"> Authors: Ceki Gülcü, Sébastien Pennec </div> @@ -48,10 +48,10 @@ While appenders are responsible for writing logging output to an appender dependent device, layouts are responsible for the format of the output. In case you were wondering, - lay-outs have nothing to do with large estates in Florida. + layouts have nothing to do with large estates in Florida. The <code>format()</code> - method in the Layout class takes in a object that represents + method in the Layout class takes a object that represents the logging event and returns a String. A synopsis of the Layout interface is shown below. </p> @@ -79,7 +79,7 @@ As we've seen, a Layout implementation takes as a parameter an object that represents a logging event. The typing of the parameter to <code>Object</code> - is because logging events may have different way of being + is because logging events may have different ways of being designed. In logback classic, a logging event is represented by the <code>ch.qos.logback.classic.LoggingEvent</code> class. Therefore, all layouts in logback classic implement a @@ -104,8 +104,8 @@ <p> Logback ships with a flexible layout called <code>PatternLayout</code>. - As all layouts, <code>PatternLayout</code> - takes in a logging event and returns a String. However, the + As all classic layouts, <code>PatternLayout</code> + takes a logging event and returns a String. However, the returned String can be modified at will by tweaking its conversion pattern. </p> @@ -238,7 +238,7 @@ <b>d / date</b> </td> <td> - Used to output the date of the logging event. The + <p>Used to output the date of the logging event. The date conversion specifier may be followed by a set of braces containing a date and time pattern strings {@link java.text.SimpleDateFormat}, @@ -247,7 +247,9 @@ <em>DATE</em> or <em>ISO8601</em> - . For example, + . + </p> + <p>For example, <b>%d{HH:mm:ss,SSS}</b> , <b>%d{dd MMM yyyy ;HH:mm:ss,SSS}</b> @@ -255,6 +257,7 @@ <b>%d{DATE}</b> . If no date format specifier is given then ISO8601 format is assumed. + </p> </td> </tr> @@ -301,6 +304,10 @@ slow. It's use should be avoided unless execution speed is not an issue. </p> + <p> + A precision specifier can be appended to the <em>caller</em> conversion + specifier to configure the depth of the information to be displayed. + </p> </td> </tr> @@ -409,7 +416,7 @@ <tr> <td align="center"> - <b>X</b> + <b>X / mdc</b> </td> <td> @@ -417,7 +424,10 @@ <p> Used to output the MDC (mapped diagnostic context) associated with the thread that - generated the logging event. The + generated the logging event. + </p> + <p> + The <b>X</b> conversion character can be followed by the key for the map placed between braces, as in @@ -425,7 +435,10 @@ where <code>clientNumber</code> is the key. The value in the MDC corresponding - to the key will be output. If no additional + to the key will be output. + </p> + <p> + If no additional sub-option is specified, then the entire contents of the MDC key value pair set is output using a format key1=val1, key2=val2 @@ -579,18 +592,150 @@ </td> </tr> </table> + + + <h3>Option handling</h3> + + <p>A conversion specifier can be followed by options between curled brackets. + 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>. + </p> + <p> + However, there is much more to it than that. + </p> + <p> + The logger name conversion specifier can take an integer as a first option. + This will use logback's abbreviation mechanism to display a shorter logger name, + without loosing it's meaning. + </p> + + <p> + The next table should clear things up. + </p> + <table BORDER="1" CELLPADDING="8"> + + <tr> + <th>Conversion Pattern</th> + <th>Logger name</th> + <th>Result</th> + </tr> + <tr> + <td>%logger{10}</td> + <td>mainPackage.sub.sample.Bar</td> + <td>m.s.s.Bar</td> + </tr> + <tr> + <td>%logger{15}</td> + <td>mainPackage.sub.sample.Bar</td> + <td>m.s.sample.Bar</td> + </tr> + <tr> + <td>%logger{16}</td> + <td>mainPackage.sub.sample.Bar</td> + <td>m.sub.sample.Bar</td> + </tr> + <tr> + <td>%logger{26}</td> + <td>mainPackage.sub.sample.Bar</td> + <td>mainPackage.sub.sample.Bar</td> + </tr> + </table> + + <p> + Another very useful way of adding options to a conversion specifier is + when <code>PatternLayout</code> is used with <code>EventEvaluators</code>. + </p> + <p> + <code>EventEvaluators</code> have the responsability to check wether a give event + matches a give criteria. + </p> + <p> + Let's look at an example using <code>EventEvaluators</code>. 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 very expensive, this + information will be displayed only when the logging request is combined with + a specific marker. By doing that, we make sure that only the most important + logging requests will have their caller information generated and displayed, + without penalizing application performance. + </p> + <p> + Here is how to configure logback to behave like we described: + </p> +<em>Example 5.2: Sample usage of EventEvaluators (examples/chapter5/eventEvaluatorConfig.xml)</em> +<div class="source"> +<configuration> + <b><evaluator name="DISPLAY_EVAL"> + <Expression>(marker.contains("DISPLAY"))</Expression> + </evaluator></b> + + <appender name="STDOUT" + class="ch.qos.logback.core.ConsoleAppender"> + <layout class="ch.qos.logback.classic.PatternLayout"> + <param name="Pattern" + value="%-4relative [%thread] %-5level - %msg <b>%caller{2, DISPLAY_EVAL}</b>%n" /> + </layout> + </appender> + <root> + <level value="debug" /> + <appender-ref ref="STDOUT" /> + </root> +</configuration> +</div> + <p> + Let's test this configuration with the following code: + </p> +<em>Example 5.2: Sample usage of EventEvaluators (examples/chapter5/EventEvaluatorExample.java)</em> +<div class="source">public class EventEvaluatorExample { + public static void main(String[] args) throws InterruptedException { + Logger logger = (Logger) LoggerFactory.getLogger(EventEvaluatorExample.class); + LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); + JoranConfigurator configurator = new JoranConfigurator(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + for (int i = 0; i < 5; i++) { + if (i == 3) { + Marker displayMarker = MarkerFactory.getMarker("DISPLAY"); + logger.debug(displayMarker, "logging statement" + i); + } else { + logger.debug("logging statement" + i); + } + } + } +}</div> + <p> + This class configures logback with the file given as an argument of + <code>main()</code> and sends 5 logging requests. The third one + is associated with a marker named <em>DISPLAY</em>. + </p> + <p> + When a logging request is sent, the corresponding logging event + will pass through the evaluation process. Here, obviously, the + third request will match the evaluation, causing its caller data + to be displayed. + </p> + <p> + Here is the output of the <code>EventEvaluatorExample</code> class. + </p> +<div class="source">0 [main] DEBUG - logging statement0 +0 [main] DEBUG - logging statement1 +0 [main] DEBUG - logging statement2 +0 [main] DEBUG - logging statement3 Caller+0 at chapter5.EventEvaluatorExample.main(EventEvaluatorExample.java:25) +16 [main] DEBUG - logging statement4 </div>