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>
