- logback-dev - mailman3.qos.ch

[GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-76-gd355c18
by git-noreply＠pixie.qos.ch 10 Mar '10

10 Mar '10

This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via d355c186d801151469afedc107ae35c338468f6d (commit) via 79ac28a4b828346f8cd71c7bbf5721baaca75461 (commit) via e0739bf394a138ddf90b7f737c604ded3c91379e (commit) via f247362915590b43cfb96c236856b6d2800c9f34 (commit) from e20cdafefc3bbe45dd3c39735e6c84a7f23feba2 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=d355c186d801151469afedc1… http://github.com/ceki/logback/commit/d355c186d801151469afedc107ae35c338468… commit d355c186d801151469afedc107ae35c338468f6d Author: Ceki Gulcu <ceki(a)qos.ch> Date: Wed Mar 10 23:54:49 2010 +0100 - working on the docs diff --git a/logback-classic/src/main/java/ch/qos/logback/classic/pattern/CallerDataConverter.java b/logback-classic/src/main/java/ch/qos/logback/classic/pattern/CallerDataConverter.java index fdccdfa..7ba7b0e 100644 --- a/logback-classic/src/main/java/ch/qos/logback/classic/pattern/CallerDataConverter.java +++ b/logback-classic/src/main/java/ch/qos/logback/classic/pattern/CallerDataConverter.java @@ -48,7 +48,7 @@ public class CallerDataConverter extends ClassicConverter { try { depth = Integer.parseInt(depthStr); } catch (NumberFormatException nfe) { - addError(""); + addError("Failed to parse depth option [" + depthStr + "]", nfe); } final List optionList = getOptionList(); diff --git a/logback-site/src/site/pages/css/common.css b/logback-site/src/site/pages/css/common.css index 95db3c3..d3a58aa 100644 --- a/logback-site/src/site/pages/css/common.css +++ b/logback-site/src/site/pages/css/common.css @@ -151,6 +151,12 @@ table.bodyTable tr.alt { background-color: #eee; } +/* we don't want the first p under td to appear indented */ +table.bodyTable tr td p:first-child { + padding-top: 0px; + margin-top: 0px; +} + /* EOF =============== bodyTable =============== */ .author { diff --git a/logback-site/src/site/pages/manual/layouts.html b/logback-site/src/site/pages/manual/layouts.html index 079f75a..c5dc7d5 100644 --- a/logback-site/src/site/pages/manual/layouts.html +++ b/logback-site/src/site/pages/manual/layouts.html @@ -370,10 +370,13 @@ public class PatternSample { In the above example, the conversion pattern is set to be "%-5level [%thread]: %message%n". A synopssis of conversion word included in logback will be given shortly. Running - <code>PatternSample</code> application will yield the following - output on the console. + <code>PatternSample</code> application as: + java java chapters.layouts.PatternSample + + will yield the following output on the console. + DEBUG [main]: Message 1 WARN [main]: Message 2 @@ -388,26 +391,24 @@ WARN [main]: Message 2 will be explained below. - In PatternLayout, parenthesis can be used to group conversion - patterns. It follows that the '(' and ')' carry special meaning - and need to be escaped to be used as literals. Parentheses - can be escaped by preceding the the opening and closing - parenthesis by a backslash, but since the backslash itself carries - special meaning in Java, we need two backslashes, as in "\$" and - "\$". Note that strictly speaking, only the closing parenthesis - needs to be escaped to be used as a literal. + In <code>PatternLayout</code>, parenthesis can be used to group + conversion patterns. It follows that the '(' and ')' carry + special meaning and need to be escaped if intended to be used as + literals. The special nature of parenthesis is further <a + href="#Parentheses">explained below</a>. - As mentioned previously, certain conversion specifiers can - include optional parameters which are passed between braces - following the conversion word. A sample conversion specifier with - options could be <code>%logger{10}</code>. Here "logger" is the - conversion word, and 10 is the option. + As mentioned previously, certain conversion specifiers may + include optional parameters passed between braces. A sample + conversion specifier with options could be + <code>%logger{10}</code>. Here "logger" is the conversion word, + and 10 is the option. Options are <a href="#cwOptions">further + discussed below</a>. The recognized conversions words along with their options are described in the table below. When multiple conversion words are - listed on the left column, they should be considered as aliases. + listed in the same table cell, they are considered as aliases. <table class="bodyTable properties" border="0"> @@ -424,18 +425,18 @@ WARN [main]: Message 2 </td> <td> - Used to output the name of the logger at the origin of - the logging event. - + Outputs the name of the logger at the origin of the logging + event. + This conversion word can take an integer as its first and only option. The converter's abbreviation algorithm will shorten the logger name, usually without significant loss of meaning. Setting the value of this option to zero has - special meaning. It will cause the conversoin specifier to - return the string right to the rightmost dot character. The - next table provides examples of the abbreviation algorithm - in action. + special meaning. It will cause the conversion word to return + the sub-string right to the rightmost dot character in the + logger name. The next table provides examples of the + abbreviation algorithm in action. <table class="bodyTable dark" border="0" cellpadding="8"> @@ -502,15 +503,15 @@ WARN [main]: Message 2 </td> <td> - Used to output the fully-qualified class name of the - caller issuing the logging request. + Outputs the fully-qualified class name of the caller + issuing the logging request. - Just like the %logger conversion word above, - this word can take an integer as its first option and use - its abbreviation algorithm to shorten the class name. Zero - carries special meaning and will cause the simple class name - to be printed without its package name prefix. By default - the class name is printed in full. + + Just like the %logger conversion word above, + this conversion admits an integer as an option to shorten + the class name. Zero carries special meaning and will cause + the simple class name to be printed without the package name + prefix. By default the class name is printed in full. Generating the caller class information is not @@ -525,51 +526,54 @@ WARN [main]: Message 2 contextName cn </td> <td>Outputs the name of the logger context to which the - logger at the origin of the logging event is attached - to. </td> + logger at the origin of the event was attached to. </td> </tr> <tr class="alt"> <td align="center"> d{pattern} date{pattern} </td> - <td > + <td> Used to output the date of the logging event. The date - conversion word may be followed by an option enclosed - between braces. - - The option admits the same syntax as the time pattern - string of the <code>java.text.SimpleDateFormat</code>. + conversion word admits a pattern string as an option. The + pattern syntax is compatible with the format accepted by <a + href="http://java.sun.com/j2se/1.4.2/docs/api/java/text/SimpleDateFormat.html"><code>java.text.SimpleDateFormat</code></a>. - A shortcut to the ISO8601 format is available by - specifying the String "ISO8601" in the braces. If - no option is set, the converter uses "ISO8601" as - the default value. + You can specify the string "ISO8601" for the + ISO8601 date format. Note that the %date conversion word + defaults to the <a + href="http://en.wikipedia.org/wiki/ISO_8601">ISO 8601 date + format</a> in the absence of a pattern option. Here are some sample option values. They assume that the actual date is Friday 20th of October, 2006 and that the - author finished his meal a short while ago. + author has returned to working on this document just after + lunch. <table class="bodyTable dark" cellpadding="8"> <tr> <th>Conversion Pattern</th> <th>Result</th> </tr> + <tr> + <td>%d</td> + <td>2006-10-20 14:06:49,812</td> + </tr> <tr> <td>%date</td> - <td>2006-10-20 14:46:49,812</td> + <td>2006-10-20 14:06:49,812</td> </tr> <tr> <td>%date{ISO8601}</td> - <td>2006-10-20 14:46:49,812</td> + <td>2006-10-20 14:06:49,812</td> </tr> <tr> <td>%date{HH:mm:ss.SSS}</td> - <td>14:46:49.812</td> + <td>14:06:49.812</td> </tr> <tr> <td>%date{dd MMM yyyy ;HH:mm:ss.SSS}</td> - <td>20 oct. 2006;14:46:49.812 </td> + <td>20 oct. 2006;14:06:49.812 </td> </tr> </table> </td> @@ -581,8 +585,8 @@ WARN [main]: Message 2 </td> <td> - Used to output the file name of the Java source file - where the logging request was issued. + Outputs the file name of the Java source file where the + logging request was issued. Generating the file information is not particularly fast. @@ -599,7 +603,7 @@ WARN [main]: Message 2 </td> <td> - Used to output location information of the caller which + Outputs location information of the caller which generated the logging event. @@ -647,7 +651,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the line number from where the logging + Outputs the line number from where the logging request was issued. @@ -664,8 +668,9 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> m / msg / message </td> <td> - Used to output the application-supplied message associated - with the logging event. + Outputs the application-supplied message associated with + the logging event. + </td> </tr> @@ -676,7 +681,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> <td> - Used to output the method name where the logging + Outputs the method name where the logging request was issued. @@ -712,7 +717,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> <td align="center"> p / le / level </td> - <td>Used to output the level of the logging event.</td> + <td>Outputs the level of the logging event.</td> </tr> <tr class="alt"> @@ -722,7 +727,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the number of milliseconds elapsed + Outputs the number of milliseconds elapsed since the start of the application until the creation of the logging event. </td> @@ -735,7 +740,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the name of the thread that generated + Outputs the name of the thread that generated the logging event. </td> @@ -750,7 +755,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> <td> - Used to output the MDC (mapped diagnostic + Outputs the MDC (mapped diagnostic context) associated with the thread that generated the logging event. @@ -764,8 +769,8 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> will be output in the format "key1=val1, key2=val2". - See <a href="mdc.html">Chapter 7</a> for more details on - the MDC. + See the <a href="mdc.html">chapter on MDC</a> for more + details. </td> @@ -782,20 +787,11 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the stack trace of the exception + Outputs the stack trace of the exception associated with the logging event, if any. By default the full stack trace will be output. - If you do not specify the %ex conversion word (or one of - its aliases) in the conversion pattern, - <code>PatternLayout</code> will automatically add it as the - last conversion word, on account of the importance of stack - trace information. The $nopex conversion word can be - substituted for %ex, in case you do not wish stack trace - information to be displayed. See also %nopex conversion word. - - The throwable conversion word can followed by one of the following options: @@ -862,9 +858,19 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Same as the %exception conversion keyword with the + Same as the %throwable conversion word above with the addition of class packaging information. - + + If you do not specify %xThrowable or another + throwable-related conversion word in the conversion pattern, + <code>PatternLayout</code> will automatically add it as the + last conversion word, on account of the importance of stack + trace information. The $nopex conversion word can be + substituted for %xThrowable, in case you do not wish stack + trace information to be displayed. See also %nopex + conversion word. + + At the end of each stack frame of the exception, a string consisting of the jar file containing the relevant class followed by the "Implementation-Version" as found in that @@ -892,7 +898,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> Logback goes to great lengths to ensure that the class packaging information it displays is correct, even in arbirarily complex class loader hierarchies. However, when - it is not able to guarantee the absolute correctness of the + it is unable to guarantee the absolute correctness of the information, then it will prefix the data with a tilde, i.e. the '~' character. Thus, it is theoretically possible for the printed class packaging information to differ from the @@ -913,15 +919,15 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Altough it pretends to handle stack trace data, this - conversion word does not output any data, thus, effectively - ignoring exceptions. + Altough it pretends to handle stack trace data, + this conversion word does not output any data, thus, + effectively ignoring exceptions. The %nopex conversion word allows the user to override - PatternLayout's internal safety mechanism which silently - adds %ex conversion keyword, even it was not specified in - the conversion pattern. + <code>PatternLayout</code>'s internal safety mechanism which + silently adds the %xThrowable conversion keyword in the absence of + another conversion word handling exceptions. </td> </tr> @@ -932,7 +938,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the marker associated with the logger + Outputs the marker associated with the logger request. In case the marker contains children markers, the @@ -952,7 +958,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </td> <td> - Used to output the value associated with a context + Outputs the value associated with a context property named key. If key is not a property of the logger context, then key will be looked up in the System properties. @@ -977,12 +983,13 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> - <h2>Format modifiers</h2> + <h2><a name="formatModifiers" href="#formatModifiers">Format + modifiers</a></h2> By default the relevant information is output as is. However, with the aid of format modifiers it is possible to change the - minimum field width, the maximum field width as well as - justification. + minimum and maximum width and the justifications of each data + field. The optional format modifier is placed between the percent sign @@ -1131,7 +1138,22 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </tr> </table> - <h3>Parentheses are special</h3> + <h3><a name="oneLetterLevel" href="#oneLetterLevel">Output just + one letter for the level</a></h3> + + Instead of printing TRACE, DEBUG, WARN, INFO or ERROR for the + level, you may want to print just T, D, W, I and E. You could + write a <a href="#customConversionSpecifier">custom converter</a> + for this purpose, or simply make use of format modifiers (just + discussed) to shorten the level value to a single character. The + appropriate conversion specifier would be + "<code>%.-1level</code>". + + + + + <h2><a name="Parentheses" href="#Parentheses">Parentheses are + special</a></h2> In logback, parentheses within the pattern string are treated as grouping tokens. Thus, it is possible to group a sub-pattern @@ -1175,17 +1197,18 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> The latter form is more comfortable to read, especially for long log files. - If you need to treat the parenthesis character as a literal, - they needs to be escaped by preceding each parenthesis with a + If you need to treat the parenthesis character as a literal, it + needs to be escaped by preceding each parenthesis with a backslash. As in, $%d{HH:mm:ss.SSS} - [%thread]$. Strictly speaking, only the closing parentesis - needs to be escaped. Thus, "%d [%thread]\)" is - equivalent to "$%d [%thread]$". + [%thread]\). Strictly speaking, only the closing parenthesis + needs to be escaped. Thus, "(%d [%thread]\)" is + equivalent to "$%d [%thread]$". But since it + is not easy to recall which parenthesis needs escaping and which + doesn't necessarily, you can escape both so that they are + interpreted as literals. - - - <h3>Options</h3> + <h3><a name="cwOptions" href="#cwOptions">Options</a></h3> A conversion specifier can be followed by options. The are @@ -1209,7 +1232,7 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> </appender></pre> - <h3>Evaluators</h3> + <h2><a name="Evaluators" href="#Evaluators">Evaluators</a></h2> As mentioned above, option lists come in handy when a conversion specifier is required to behave dynamically based on @@ -1221,16 +1244,16 @@ Caller+2 at mainPackage.ConfigTester.main(ConfigTester.java:38)</pre> evaluator. - 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. + Let us review an example involving a + <code>EventEvaluator</code>. The next 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 the 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. @@ -1900,7 +1923,7 @@ public class TrivialMain { <tr class="b"> <td align="center">t / date</td> <td> - Used to output the date of the logging event. The date + Outputs 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 used by <code>java.text.SimpleDateFormat</code>. ABSOLUTE, http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=79ac28a4b828346f8cd71c7b… http://github.com/ceki/logback/commit/79ac28a4b828346f8cd71c7bbf5721baaca75… commit 79ac28a4b828346f8cd71c7bbf5721baaca75461 Author: walterjwhite <WalterWhite(a)walterjwhite.com> Date: Wed Mar 10 13:10:43 2010 -0700 fixed spelling error (specifying) diff --git a/logback-site/src/site/pages/access.html b/logback-site/src/site/pages/access.html index 2f078c3..5170e52 100644 --- a/logback-site/src/site/pages/access.html +++ b/logback-site/src/site/pages/access.html @@ -106,7 +106,7 @@ 21:56:10,015 |-INFO in c.q.lb.core.j.a.AppenderRefAction - Attaching appender named [STDOUT] to ch.qos.logback.access.tomcat.LogbackValve[Catalina] 21:56:10,015 |-INFO in c.q.lb.access.j.a.ConfigurationAction - End of configuration. - It is possible to override default status printing by specifing + It is possible to override default status printing by specifying the "quiet" attribute in the <code>Valve</code> element. Similarly, it is also possible to set the filename for the logback-access configuration file. Here is an example. http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=e0739bf394a138ddf90b7f73… http://github.com/ceki/logback/commit/e0739bf394a138ddf90b7f737c604ded3c913… commit e0739bf394a138ddf90b7f737c604ded3c91379e Author: walterjwhite <WalterWhite(a)walterjwhite.com> Date: Wed Mar 10 13:07:51 2010 -0700 fixed spelling error (downloading) diff --git a/logback-site/src/site/pages/access.html b/logback-site/src/site/pages/access.html index d6ce208..2f078c3 100644 --- a/logback-site/src/site/pages/access.html +++ b/logback-site/src/site/pages/access.html @@ -149,7 +149,7 @@ <a name="jetty"></a> <h1>Logback-access under Jetty</h1> - After downlading the logback distribution, place the files + After downloading the logback distribution, place the files logback-core-VERSION.jar and logback-access-VERSION.jar under $JETTY_HOME/lib directory, where $JETTY_HOME is the folder where you have http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=f247362915590b43cfb96c23… http://github.com/ceki/logback/commit/f247362915590b43cfb96c236856b6d2800c9… commit f247362915590b43cfb96c236856b6d2800c9f34 Author: walterjwhite <WalterWhite(a)walterjwhite.com> Date: Wed Mar 10 13:02:31 2010 -0700 fixed spelling error (downloading) diff --git a/logback-site/src/site/pages/access.html b/logback-site/src/site/pages/access.html index de0002c..d6ce208 100644 --- a/logback-site/src/site/pages/access.html +++ b/logback-site/src/site/pages/access.html @@ -44,7 +44,7 @@ <a name="tomcat"></a> <h1>Logback-access under Tomcat</h1> - To use logback-access with Tomcat, after downlading the logback + To use logback-access with Tomcat, after downloading the logback distribution, place the files logback-core-${project.version}.jar and logback-access-${project.version}.jar under $TOMCAT_HOME/server/lib/ directory, where $TOMCAT_HOME is ----------------------------------------------------------------------- Summary of changes: .../classic/pattern/CallerDataConverter.java | 2 +- logback-site/src/site/pages/access.html | 6 +- logback-site/src/site/pages/css/common.css | 6 + logback-site/src/site/pages/manual/layouts.html | 235 +++++++++++--------- 4 files changed, 139 insertions(+), 110 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.

1 0

[JIRA] Created: (LBCORE-141) Document the efect of parenthesis in PatternLayout
by Ceki Gulcu (JIRA) 10 Mar '10

10 Mar '10

Document the efect of parenthesis in PatternLayout -------------------------------------------------- Key: LBCORE-141 URL: http://jira.qos.ch/browse/LBCORE-141 Project: logback-core Issue Type: Task Components: Layout Reporter: Ceki Gulcu Assignee: Logback dev list See also http://stackoverflow.com/questions/2393675/java-library-that-does-nice-form… -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

1 2

[JIRA] Created: (LBCLASSIC-169) Customizing table names used by DbAppender
by Tomasz Nurkiewicz (JIRA) 10 Mar '10

10 Mar '10

Customizing table names used by DbAppender ------------------------------------------ Key: LBCLASSIC-169 URL: http://jira.qos.ch/browse/LBCLASSIC-169 Project: logback-classic Issue Type: Improvement Components: appender Affects Versions: 0.9.18 Reporter: Tomasz Nurkiewicz Assignee: Logback dev list Priority: Minor ch.qos.logback.classic.db.DBAppender uses hard-coded table names for logging events: logging_event, logging_event_property and logging_event_exception. Allowing to change these default names has two benefits: * There are systems where database table names must follow some naming conventions (prefixes, using underscores vs. camel case) * One could create several Db appenders, each operating on different set of tables (for performance reasons or more fine grained logging and filtering) Each table name would be configured using a property in logback.xml. Default values for table names would be the same as present ones to maintain backward compatibility. If you are interested in this feature let me know, I can implement it and provide a patch. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

5 16

[GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-72-ge20cdaf
by git-noreply＠pixie.qos.ch 10 Mar '10

10 Mar '10

This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via e20cdafefc3bbe45dd3c39735e6c84a7f23feba2 (commit) from 2fa846f25248559a413214c5ef2188af2ff7fe45 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=e20cdafefc3bbe45dd3c3973… http://github.com/ceki/logback/commit/e20cdafefc3bbe45dd3c39735e6c84a7f23fe… commit e20cdafefc3bbe45dd3c39735e6c84a7f23feba2 Author: Ceki Gulcu <ceki(a)qos.ch> Date: Wed Mar 10 18:42:08 2010 +0100 - documentation improvements diff --git a/logback-site/src/site/pages/manual/layouts.html b/logback-site/src/site/pages/manual/layouts.html index b4b176f..079f75a 100644 --- a/logback-site/src/site/pages/manual/layouts.html +++ b/logback-site/src/site/pages/manual/layouts.html @@ -152,8 +152,9 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> { Custom layouts are configured as any other component. As mentioned earlier, <code>FileAppender</code> and its sub-classes - expect an encoder which we provide in the form of - <code>LayoutWrappingEncoder</code> which wraps + expect an encoder. In order to fulfill this requirement, we pass + to <code>FileAppender</code> an instance of + <code>LayoutWrappingEncoder</code> which wraps our <code>MySampleLayout</code>. Here is the configuration file: Example: Configuration of MySampleLayout @@ -173,12 +174,11 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> { The sample application <a href="../xref/chapters/layouts/SampleLogging.html"> - <code>chapters.layouts.SampleLogging</code></a> configures logback with - the configuration script supplied as a parameter and then logs a - debug message, followed by an error message. + <code>chapters.layouts.SampleLogging</code></a> configures logback + with the configuration script passed as its first argument and + then logs a debug message, followed by an error message. - - To run this example issue the following command from within the + To run this example issue the following command from within the logback-examples directory. @@ -193,21 +193,24 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> { insists that nothing is certain except perhaps uncertainty itself, which is by no means certain either, might ask: how about a layout with options? The reader shall find a slightly modified version - of our custom layout in <code>MySampleLayout2.java</code>. She - will discover that adding an option to a layout is as simple as - declaring a setter method for the option. + of our custom layout in <a + href="../xref/chapters/layouts/MySampleLayout2.html"><code>MySampleLayout2.java</code></a>. As + mentioned throughout this manual, adding a property to a layout or + any other logback component is as simple as declaring a setter + method for the property. - - The - <a href="../xref/chapters/layouts/MySampleLayout2.html"><code>MySampleLayout2</code> - </a> - class contains two attributes. The first one is a prefix that - can be added to the output. The second attribute is used to - choose whether to display the name of the thread from which - the logging request was sent. - - Here is the implementation of this class: + The <a + href="../xref/chapters/layouts/MySampleLayout2.html"><code>MySampleLayout2</code></a> + class contains two properties. The first one is a prefix that can + be added to the output. The second property is used to choose + whether to display the name of the thread from which the logging + request was sent. + + + Here is a copy of the <a + href="../xref/chapters/layouts/MySampleLayout2.html"><code>MySampleLayout2</code></a> + class : <pre class="prettyprint source">package chapters.layouts; @@ -252,12 +255,14 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { The addition of the corresponding setter method is all that is - needed to enable the configuration of an option. Note that the - <code>PrintThreadName</code> option is boolean and not + needed to enable the configuration of a property. Note that the + <code>PrintThreadName</code> property is a boolean and not a <code>String</code>. Configuration of logback components was - covered in detail in <a href="configuration.html">"Chapter 3: - Logback configuration"</a>. Here is the configuration - file tailor-made for use with <code>MySampleLayout2</code>. + covered in detail in the chapter on <a + href="configuration.html">configuration</a>. The chapter <a + href="onJoran.html">on joran</a> provides further detail. Here is + the configuration file tailor made for + <code>MySampleLayout2</code>. @@ -289,31 +294,38 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { <code>PatternLayout</code></a>. As all layouts, <code>PatternLayout</code> takes a logging event and returns a <code>String</code>. However, this <code>String</code> can be - customized at will by tweaking the conversion pattern of - <code>PatternLayout</code>. + customized at will by tweaking <code>PatternLayout</code>'s + conversion pattern. The conversion pattern of <code>PatternLayout</code> is closely related to the conversion pattern of the <code>printf()</code> function in the C programming language. A conversion pattern is composed of literal text and format control expressions called - conversion specifiers. You are free to insert any literal text - within the conversion pattern. Each conversion specifier starts - with a percent sign '%' and is followed by optional format - modifiers, a conversion word and optional parameters between - braces. The conversion word controls the type of data to use, e.g. - logger name, level, date, thread name. The format modifiers - control such things as field width, padding, and left or right - justification. + conversion specifiers. You are free to insert any literal + text within the conversion pattern. Each conversion specifier + starts with a percent sign '%' and is followed by optional + format modifiers, a conversion word and optional + parameters between braces. The conversion word controls the data + field to convert, e.g. logger name, level, date or thread + name. The format modifiers control field width, padding, and left + or right justification. - Given that <code>FileAppender</code> and sub-classes expect an - encoder, the <code>PatternLayout</code> instance must be wrapped - within an encoder before being used as a sub-component of - <code>FileAppender</code>. <code>PatternLayoutEncoder</code> is - designed solely for the purpose of wrapping a - <code>PatternLayout</code> instance so that it can be seen as - encoder. Here is an example: + As already mentioned on several occasions, + <code>FileAppender</code> and sub-classes expect an + encoder. Consequently, when used in conjuction with + <code>FileAppender</code> or its subclasses a + <code>PatternLayout</code> must be wrapped within an + encoder. Given that the + <code>FileAppender</code>/<code>PatternLayout</code> combination + is so common, logback ships with an encoder named + <code>PatternLayoutEncoder</code>, designed solely for the purpose + of wrapping a <code>PatternLayout</code> instance so that it can + be seen as encoder. Below is an example which programmatically + configures a <code>ConsoleAppender</code> with a + <code>PatternLayoutEncoder</code>: + Example 5.1: Sample usage of a PatternLayout @@ -355,8 +367,10 @@ public class PatternSample { } }</pre> - The conversion pattern is set to be "%-5level [%thread]: - %message%n". Running PatternSample will yield the following + In the above example, the conversion pattern is set to be + "%-5level [%thread]: %message%n". A synopssis of conversion + word included in logback will be given shortly. Running + <code>PatternSample</code> application will yield the following output on the console. ----------------------------------------------------------------------- Summary of changes: logback-site/src/site/pages/manual/layouts.html | 102 +++++++++++++---------- 1 files changed, 58 insertions(+), 44 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.

1 0

[GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-71-g2fa846f
by git-noreply＠pixie.qos.ch 10 Mar '10

10 Mar '10

This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via 2fa846f25248559a413214c5ef2188af2ff7fe45 (commit) from ac15c8a5283067333e65bd772f75b5bbb2e0230e (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=2fa846f25248559a413214c5… http://github.com/ceki/logback/commit/2fa846f25248559a413214c5ef2188af2ff7f… commit 2fa846f25248559a413214c5ef2188af2ff7fe45 Author: Ceki Gulcu <ceki(a)qos.ch> Date: Wed Mar 10 15:49:27 2010 +0100 - added a link to the article on making contributions. diff --git a/logback-site/src/site/pages/templates/footer.js b/logback-site/src/site/pages/templates/footer.js index c94810b..fc60fd3 100644 --- a/logback-site/src/site/pages/templates/footer.js +++ b/logback-site/src/site/pages/templates/footer.js @@ -21,7 +21,7 @@ AAT = '@' DOOTT = '.' document.write('<tr>') document.write('<td align="left" colspan="2">') -document.write('We are actively looking for volunteers to proofread the documentation. Please send your corrections or suggestions for improvement to "corrections' + AAT +'qos'+DOOTT+'ch".'); +document.write('We are actively looking for volunteers to proofread the documentation. Please send your corrections or suggestions for improvement to "corrections' + AAT +'qos'+DOOTT+'ch". See also the <a href="http://articles.qos.ch/contributing.html">instructions for contributors</a>.'); document.write('</td>') document.write('</table>') ----------------------------------------------------------------------- Summary of changes: logback-site/src/site/pages/templates/footer.js | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.

1 0

[JIRA] Commented: (LBCLASSIC-57) SyslogAppender fails sporadically
by Ingo Siebert (JIRA) 10 Mar '10

10 Mar '10

[ http://jira.qos.ch/browse/LBCLASSIC-57?page=com.atlassian.jira.plugin.syste… ] Ingo Siebert commented on LBCLASSIC-57: --------------------------------------- Ok, thank you. I've used 0.9.13 so far, so I guess I have another problem. > SyslogAppender fails sporadically > --------------------------------- > > Key: LBCLASSIC-57 > URL: http://jira.qos.ch/browse/LBCLASSIC-57 > Project: logback-classic > Issue Type: Bug > Environment: $ uname -a > Linux ... 2.6.9-67.ELsmp #1 SMP Wed Nov 7 13:56:44 EST 2007 x86_64 x86_64 x86_64 GNU/Linux > $ java -version > java version "1.6.0_03" > Java(TM) SE Runtime Environment (build 1.6.0_03-b05) > Java HotSpot(TM) Server VM (build 1.6.0_03-b05, mixed mode) > multiprocessor PC box > Reporter: Anton Tagunov > Assignee: Logback dev list > Fix For: 0.9.12 > > > * several JVM-s per Linux box > * 5 SyslogAppender-s logging to syslog-ng on 127.0.0.1 > Once in a while one of the SyslogAppender-s (the busiest one with longest messages) stops logging completely > Other SyslogAppender-ss continue working fine. > /usr/sbin/tcpdump has confirmed upd packets reach > syslog-ng port via 'lo' network interface for remaining appends > /usr/sbin/tcpdump has confirmed NO udp packets reach > syslog-ng port via 'lo' network interface for the failing appender > We have JMX enabled. JConsole does show StatusManager messages. > There are no error messages there. > Just the messages emitted during initial logback configuration > from logback.xml on the classpath. > We had invoked 'reload()' method via JMX. > StatusMananger messages observed via JMX show that reload had happened. > Full re-configuration had happened. > All 5 SyslogAppenders had been apparently re-created. > Yet NO udp messages had come from the SyslogAppender > replacing those which had previously failed. > Reloading did not help at all. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

1 0

[GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-70-gac15c8a
by git-noreply＠pixie.qos.ch 10 Mar '10

10 Mar '10

This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via ac15c8a5283067333e65bd772f75b5bbb2e0230e (commit) from 4af0b83eac54b45fb9d7e78697b2c222a8ef1845 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=ac15c8a5283067333e65bd77… http://github.com/ceki/logback/commit/ac15c8a5283067333e65bd772f75b5bbb2e02… commit ac15c8a5283067333e65bd772f75b5bbb2e0230e Author: Ceki Gulcu <ceki(a)qos.ch> Date: Wed Mar 10 09:48:06 2010 +0100 No point in printing the errors twice. diff --git a/logback-examples/src/main/java/chapters/appenders/mail/EMail.java b/logback-examples/src/main/java/chapters/appenders/mail/EMail.java index 5ac9e05..7c9ce34 100644 --- a/logback-examples/src/main/java/chapters/appenders/mail/EMail.java +++ b/logback-examples/src/main/java/chapters/appenders/mail/EMail.java @@ -40,7 +40,6 @@ public class EMail { lc.reset(); configurator.setContext(lc); configurator.doConfigure(configFile); - StatusPrinter.printInCaseOfErrorsOrWarnings(lc); Logger logger = LoggerFactory.getLogger(EMail.class); ----------------------------------------------------------------------- Summary of changes: .../main/java/chapters/appenders/mail/EMail.java | 1 - 1 files changed, 0 insertions(+), 1 deletions(-) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.

1 0

[GIT] Logback: the generic, reliable, fast and flexible logging framework. branch, master, updated. v0.9.18-69-g4af0b83
by git-noreply＠pixie.qos.ch 08 Mar '10

08 Mar '10

This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "Logback: the generic, reliable, fast and flexible logging framework.". The branch, master has been updated via 4af0b83eac54b45fb9d7e78697b2c222a8ef1845 (commit) from 9a9462cf0af145a7c80fc655ff8298416393b3bd (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below. - Log ----------------------------------------------------------------- http://git.qos.ch/gitweb/?p=logback.git;a=commit;h=4af0b83eac54b45fb9d7e786… http://github.com/ceki/logback/commit/4af0b83eac54b45fb9d7e78697b2c222a8ef1… commit 4af0b83eac54b45fb9d7e78697b2c222a8ef1845 Author: Ceki Gulcu <ceki(a)qos.ch> Date: Mon Mar 8 22:13:05 2010 +0100 Ongoing work on the documentation diff --git a/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java index 42a46d9..4379580 100644 --- a/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java +++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/Encoder.java @@ -19,9 +19,50 @@ import java.io.OutputStream; import ch.qos.logback.core.spi.ContextAware; import ch.qos.logback.core.spi.LifeCycle; +/** + * Encoders are responsible for transform an incoming event into a byte array + * *and* writing out the byte array onto the appropriate {@link OutputStream}. + * Thus, encoders have total control of what and when gets written to the + * {@link OutputStream} maintained by the owning appender. + * + * + * @author Ceki Gülcü + * @author Joen Huxhorn + * @author Maarten Bosteels + * + * @param <E> + * event type + * @since 0.9.19 + */ public interface Encoder<E> extends ContextAware, LifeCycle { + /** + * This method is called when the owning appender starts or whenever output + * needs to be directed to a new OutputStream, for instance as a result of a + * rollover. Implementing encoders should at the very least remember the + * OutputStream passed as argument and use it in future operations. + * + * @param os + * @throws IOException + */ void init(OutputStream os) throws IOException; + + /** + * Encode and write an event to the appropriate {@link OutputStream}. + * Implementations are free to differ writing out of the encoded event and + * instead write in batches. + * + * @param event + * @throws IOException + */ void doEncode(E event) throws IOException; + + /** + * This method is called prior to the closing of the underling + * {@link OutputStream}. Implementations MUST not close the underlying + * {@link OutputStream} which is the responsibility of the owning appender. + * + * @throws IOException + */ void close() throws IOException; } diff --git a/logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java similarity index 97% rename from logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java rename to logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java index ed91af0..0c3f2bf 100644 --- a/logback-core/src/main/java/ch/qos/logback/core/html/LayoutWrappingEncoder.java +++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/LayoutWrappingEncoder.java @@ -1,4 +1,4 @@ -package ch.qos.logback.core.html; +package ch.qos.logback.core.encoder; import java.io.IOException; import java.io.OutputStream; @@ -6,7 +6,6 @@ import java.nio.charset.Charset; import ch.qos.logback.core.CoreConstants; import ch.qos.logback.core.Layout; -import ch.qos.logback.core.encoder.EncoderBase; public class LayoutWrappingEncoder<E> extends EncoderBase<E> { diff --git a/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java b/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java index 036e498..c97c139 100644 --- a/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java +++ b/logback-core/src/main/java/ch/qos/logback/core/encoder/ObjectStreamEncoder.java @@ -83,7 +83,8 @@ public class ObjectStreamEncoder<E> extends EncoderBase<E> { int offset = 2*CoreConstants.BYTES_PER_INT; ByteArrayUtil.writeInt(byteArray,offset, byteArray.length-offset); } - + + @Override public void init(OutputStream os) throws IOException { super.init(os); bufferList.clear(); diff --git a/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java b/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java index da84cb9..1128459 100644 --- a/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java +++ b/logback-core/src/main/java/ch/qos/logback/core/pattern/PatternLayoutEncoderBase.java @@ -1,7 +1,7 @@ package ch.qos.logback.core.pattern; import ch.qos.logback.core.Layout; -import ch.qos.logback.core.html.LayoutWrappingEncoder; +import ch.qos.logback.core.encoder.LayoutWrappingEncoder; public class PatternLayoutEncoderBase<E> extends LayoutWrappingEncoder<E> { diff --git a/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java b/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java index 0d475c8..1774d0a 100644 --- a/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java +++ b/logback-core/src/test/java/ch/qos/logback/core/OutputStreamAppenderTest.java @@ -22,7 +22,7 @@ import org.junit.After; import org.junit.Before; import org.junit.Test; -import ch.qos.logback.core.html.LayoutWrappingEncoder; +import ch.qos.logback.core.encoder.LayoutWrappingEncoder; import ch.qos.logback.core.pattern.parser.SamplePatternLayout; public class OutputStreamAppenderTest { diff --git a/logback-examples/src/main/java/chapters/layouts/PatternSample.java b/logback-examples/src/main/java/chapters/layouts/PatternSample.java index d4d7786..8b8ec89 100644 --- a/logback-examples/src/main/java/chapters/layouts/PatternSample.java +++ b/logback-examples/src/main/java/chapters/layouts/PatternSample.java @@ -16,6 +16,7 @@ package chapters.layouts; import org.slf4j.LoggerFactory; import ch.qos.logback.classic.Logger; +import ch.qos.logback.classic.LoggerContext; import ch.qos.logback.classic.encoder.PatternLayoutEncoder; import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.ConsoleAppender; @@ -24,14 +25,17 @@ public class PatternSample { static public void main(String[] args) throws Exception { Logger rootLogger = (Logger) LoggerFactory.getLogger("root"); + LoggerContext loggerContext = rootLogger.getLoggerContext(); + loggerContext.reset(); - PatternLayoutEncoder layout = new PatternLayoutEncoder(); - layout.setPattern("%-5level [%thread]: %message%n"); - layout.start(); + PatternLayoutEncoder encoder = new PatternLayoutEncoder(); + encoder.setContext(loggerContext); + encoder.setPattern("%-5level [%thread]: %message%n"); + encoder.start(); ConsoleAppender<ILoggingEvent> appender = new ConsoleAppender<ILoggingEvent>(); - appender.setContext(rootLogger.getLoggerContext()); - appender.setEncoder(layout); + appender.setContext(loggerContext); + appender.setEncoder(encoder); appender.start(); rootLogger.addAppender(appender); diff --git a/logback-examples/src/main/java/chapters/layouts/SampleLogging.java b/logback-examples/src/main/java/chapters/layouts/SampleLogging.java index 8a694cc..5e7d55c 100644 --- a/logback-examples/src/main/java/chapters/layouts/SampleLogging.java +++ b/logback-examples/src/main/java/chapters/layouts/SampleLogging.java @@ -23,20 +23,17 @@ import ch.qos.logback.core.util.StatusPrinter; public class SampleLogging { - public static void main(String[] args) { + public static void main(String[] args) throws JoranException { Logger logger = LoggerFactory.getLogger(SampleLogging.class); LoggerContext lc = (LoggerContext) LoggerFactory.getILoggerFactory(); - try { - JoranConfigurator configurator = new JoranConfigurator(); - lc.reset(); - configurator.setContext(lc); - configurator.doConfigure(args[0]); - } catch (JoranException je) { - StatusPrinter.print(lc); - } - + JoranConfigurator configurator = new JoranConfigurator(); + lc.reset(); + configurator.setContext(lc); + configurator.doConfigure(args[0]); + StatusPrinter.printInCaseOfErrorsOrWarnings(lc); + logger.debug("Everything's going well"); logger.error("maybe not quite..."); } diff --git a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml index 9cff3bb..22a13f9 100644 --- a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml +++ b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml @@ -1,11 +1,12 @@ -<configuration> +<configuration debug="true"> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="chapters.layouts.MySampleLayout" /> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"> + <layout class="chapters.layouts.MySampleLayout" /> + </encoder> </appender> - <root level="debug"> + <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration> \ No newline at end of file diff --git a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml index 5c302fb..776b085 100644 --- a/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml +++ b/logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig2.xml @@ -1,11 +1,13 @@ <configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="chapters.layouts.MySampleLayout2"> - <prefix>MyPrefix</prefix> - <printThreadName>false</printThreadName> - </layout> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + + <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"> + <layout class="chapters.layouts.MySampleLayout2"> + <prefix>MyPrefix</prefix> + <printThreadName>false</printThreadName> + </layout> + </encoder> </appender> <root level="debug"> diff --git a/logback-site/src/site/pages/manual/encoders.html b/logback-site/src/site/pages/manual/encoders.html index 9b2ccad..fcb07d4 100644 --- a/logback-site/src/site/pages/manual/encoders.html +++ b/logback-site/src/site/pages/manual/encoders.html @@ -7,7 +7,7 @@ <link rel="stylesheet" type="text/css" href="../css/common.css" /> <link rel="stylesheet" type="text/css" href="../css/screen.css" media="screen" /> <link rel="stylesheet" type="text/css" href="../css/_print.css" media="print" /> - <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" / + <link rel="stylesheet" type="text/css" href="../css/prettify.css" media="screen" /> </head> <body onload="prettyPrint()"> <script type="text/javascript">prefix='../';</script> @@ -23,7 +23,168 @@ <div id="content"> - <h1>Chapter 6: Encoders</h1> + <h1>Chapter 5: Encoders</h1> + + <div class="quote"> + ACTION THIS DAY Make sure they have all they want on + extreme priority and report to me that this has been done. + + —CHURCHILL on October 1941 to General Hastings Ismay in + response to a request for more resources signed by Alan Turing + and his cryptanalyst colleagues at Bletchley Park + </div> + + <script src="../templates/creative.js" type="text/javascript"></script> + <script src="../templates/setup.js" type="text/javascript"></script> + + + <h2>What is an encoder</h2> + + Encoders are responsible for transforming an event into a byte + array as well as writing out that byte array into an + <code>OutputStream</code>. Encoders were introduced in logback + version 0.9.19. In previous versions, most appenders relied on a + layout to transform an event into a string and write it out using + a <code>java.io.Writer</code>. In previous versions of logback, + users would nest a <code>PatternLayout</code> within + <code>FileAppender</code>. As for logback 0.9.19, + <code>FileAppender</code> and sub-classes <a + href="../codes.html#layoutInsteadOfEncoder">expect an encoder and no + longer admit a layout</a>. + + + Why the breaking change? + + + Layouts, as discussed in detail in the next chapter, are only + able to transform an event into a String. Moreover, given that a + layout has no control over when events get written out, layouts + cannot aggregate events into batches. Contrast this with encoders + which not only have total control over the format of the bytes + written out, also control when (and if) those bytes get written + out. + + + At present time (2010-03-08), <code>PatternLayotEncoder</code> + is the only really useful encoder. It merely wraps a + <code>PatternLayout</code> which does most of the work. Thus, may + seem that encoders do not bring much to the table except needless + complexity. However, we hope that with the advent of new and + powerful encoders this impression will change. + + <h2><a name="interface" href="#interface">Encoder + interface</a></h2> + + Encoders are responsible for transforming an incoming event + into a byte array and writing out the resulting byte array + onto the appropriate OutputStream. Thus, encoders have total + control of what and when bytes gets written to the + <code>OutputStream</code> maintained by the owning appender. Here + is the <a + href="../xref/ch/qos/logback/core/encoder/Encoder.html">Encoder + interface:</a> + + + <pre class="prettyprint source">package ch.qos.logback.core.encoder; + +public interface Encoder<E> extends ContextAware, LifeCycle { + + /** + * This method is called when the owning appender starts or whenever output + * needs to be directed to a new OutputStream, for instance as a result of a + * rollover. + */ + void init(OutputStream os) throws IOException; + + /** + * Encode and write an event to the appropriate {@link OutputStream}. + * Implementations are free to differ writing out of the encoded event and + * instead write in batches. + */ + void doEncode(E event) throws IOException; + + + /** + * This method is called prior to the closing of the underling + * {@link OutputStream}. Implementations MUST not close the underlying + * {@link OutputStream} which is the responsibility of the owning appender. + */ + void close() throws IOException; +}</pre> + + As you can see, the Encoder interface consists of few method + but surprisingly enough many useful things can be accomplished with + those methods. + + + <h2><a name="LayoutWrappingEncoder" + href="#LayoutWrappingEncoder">LayoutWrappingEncoder</a></h2> + + Until logback version 0.9.19, appenders which offered + flexibility with respect to the output format relied on + layouts. As there exists a substantial body of code based on the + layout interface, we need a way for encoders inter-operate with + layouts. <a + href="../xref/ch/qos/logback/core/encoder/LayoutWrappingEncoder.html">LayoutWrappingEncoder</a> + bridges the gap between encoders and layouts. It implements the + encoder interface and wraps a layout to which it delegates the + work of transforming an event into string. + + + Below is an excerpt from the <code>LayoutWrappingEncoder</code> + class illustrating how delegation to the wrapped layout instance + is done. + + <pre class="prettyprint source">package ch.qos.logback.core.encoder; + +public class LayoutWrappingEncoder<E> extends EncoderBase<E> { + + protected Layout<E> layout; + private Charset charset; + + public void doEncode(E event) throws IOException { + String txt = layout.doLayout(event); + outputStream.write(convertToBytes(txt)); + outputStream.flush(); + } + + private byte[] convertToBytes(String s) { + if (charset == null) { + return s.getBytes(); + } else { + return s.getBytes(charset); + } + } +}</pre> + + The <code>doEncode</code>() method starts by having the wrapped + layout convert the incoming event into string. The resulting text + string is converted to bytes according to the charset encoding + chosen by the user. Those bytes are then written to the + <code>OutputStream</code> given by the owning appender and the + <code>OutputStream</code> is immediately flushed. + + + + <h2><a name="PatternLayoutEncoder" + href="#PatternLayoutEncoder">PatternLayoutEncoder</a></h2> + + Given that <code>PatternLayout</code> is the most commonly used + layout, logback caters for this common use case with + <code>PatternLayoutEncoder</code>, an extension of + <code>LayoutWrappingEncoder</code> restricted to wrapping + instances of <code>PatternLayout</code>. + + + As of logback version 9.9.19, whenever a + <code>FileAppender</code> or one of its sub-classes was configured + with a <code>PatternLayout</code>, a + <code>PatternLayoutEncoder</code> must be used instead. This is + explained in the <a + href="../codes.html#layoutInsteadOfEncoder">relevant entry in the + logback error codes</a>. + + </div> </body> </html> diff --git a/logback-site/src/site/pages/manual/index.html b/logback-site/src/site/pages/manual/index.html index e8d7e21..8b832d0 100644 --- a/logback-site/src/site/pages/manual/index.html +++ b/logback-site/src/site/pages/manual/index.html @@ -47,8 +47,8 @@ <li>discussion of best logback practices and anti-patterns</li> <li>logback configuration scripts in XML format</li> <li>appenders</li> - <li>layouts</li> <li>encoders</li> + <li>layouts</li> <li>filters</li> <li>mapped diagnostic contexts</li> <li>joran, logback's configuration system</li> @@ -85,13 +85,13 @@ <li> <a href="appenders.html">Chapter 4: Appenders</a> </li> - + + <li><a href="encoders.html">Chapter 5: + Encoders</a> + </li> + <li> - <a href="layouts.html">Chapter 5: Layouts</a> - </li> - - <li> - <a href="encoders.html">Chapter 6: Encoders</a> + <a href="layouts.html">Chapter 6: Layouts</a> </li> <li> diff --git a/logback-site/src/site/pages/manual/layouts.html b/logback-site/src/site/pages/manual/layouts.html index 35e165a..b4b176f 100644 --- a/logback-site/src/site/pages/manual/layouts.html +++ b/logback-site/src/site/pages/manual/layouts.html @@ -24,7 +24,7 @@ </div> <div id="content"> - <h1>Chapter 5: Layouts</h1> + <h1>Chapter 6: Layouts</h1> <div class="quote"> TCP implementations will follow a general principle of @@ -39,10 +39,9 @@ <h2>What is a layout?</h2> - 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, layouts have - nothing to do with large estates in Florida. The + In case you were wondering, layouts have nothing to do with + large estates in Florida. Layouts are logback components + responsible for transforming an incoming event into a String. The <code>format()</code> method in the <a href="../xref/ch/qos/logback/core/Layout.html"><code>Layout</code></a> interface takes an object that represents an event (of any type) @@ -53,13 +52,15 @@ <pre class="prettyprint source">public interface Layout<E> extends ContextAware, LifeCycle { String doLayout(E event); - String getHeader(); - String getFooter(); + String getFileHeader(); + String getPresentationHeader(); + String getFileFooter(); + String getPresentationFooter(); String getContentType(); }</pre> This interface is rather simple and yet is sufficent for many - formatting needs. The Texan developer from Texas, who you might + formatting needs. The Texan developer from Texas, whom you might know from Joseph Heller's Catch-22, might exclaim: it just takes five methods to implement a layout!!? @@ -71,7 +72,9 @@ <code>ch.qos.logback.classic.spi.ILoggingEvent</code></a>. This fact will be apparent throughout this section. - <h3>Writing your own Layout</h3> + <h2><a name="writingYourOwnLayout" + href="#writingYourOwnLayout">Writing your own custom + Layout</a></h2> Let us implement a simple yet functional layout for the logback-classic module that prints the time elapsed since the @@ -114,14 +117,13 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> { Note that <code>MySampleLayout</code> extends <a href="../xref/ch/qos/logback/core/LayoutBase.html"> - <code>LayoutBase</code></a>. This class manages state shared by - all <code>Layout</code> classes, such as whether the layout is - started or stopped, header, footer and content type data. It - allows the developer to concentrate on the formatting expected - from his/her <code>Layout</code>. Note that the - <code>LayoutBase</code> class is generic. In its class - declaration, <code>MySampleLayout</code> extends - <code>LayoutBase<ILoggingEvent></code>. + <code>LayoutBase</code></a>. This class manages state common to + all layout instances, such as whether the layout is started or + stopped, header, footer and content type data. It allows the + developer to concentrate on the formatting expected from his/her + <code>Layout</code>. Note that the <code>LayoutBase</code> class + is generic. In its class declaration, <code>MySampleLayout</code> + extends <code>LayoutBase<ILoggingEvent></code>. The <code>doLayout(ILoggingEvent event)</code> method, i.e. the @@ -144,21 +146,27 @@ public class MySampleLayout extends LayoutBase<ILoggingEvent> { contents of exceptions as well. - <h3>Configuring your custom layout</h3> + <h3><a name="configuringYourOwnLayout" + href="#configuringYourOwnLayout">Configuring your custom + layout</a></h3> - Custom layouts are configured as any other layout. Here is as - example: + Custom layouts are configured as any other component. As + mentioned earlier, <code>FileAppender</code> and its sub-classes + expect an encoder which we provide in the form of + <code>LayoutWrappingEncoder</code> which wraps + <code>MySampleLayout</code>. Here is the configuration file: - Example 5.0: Configuration of MySampleLayout - (logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml) + Example: Configuration of MySampleLayout + (logback-examples/src/main/java/chapters/layouts/sampleLayoutConfig.xml) <pre class="prettyprint source"><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="chapters.layouts.MySampleLayout" /> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"> + <layout class="chapters.layouts.MySampleLayout" /> + </encoder> </appender> - <root level="debug"> + <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration></pre> @@ -255,15 +263,16 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { <pre class="prettyprint source"><configuration> - <appender name="STDOUT" - class="ch.qos.logback.core.ConsoleAppender"> - <layout class="chapters.layouts.MySampleLayout2"> - <prefix>MyPrefix</prefix> - <printThreadName>false</printThreadName> - </layout> + <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> + <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder"> + <layout class="chapters.layouts.MySampleLayout2"> + <prefix>MyPrefix</prefix> + <printThreadName>false</printThreadName> + </layout> + </encoder> </appender> - <root level="debug"> + <root level="DEBUG"> <appender-ref ref="STDOUT" /> </root> </configuration></pre> @@ -272,8 +281,8 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { - <h3><a name="ClassicPatternLayout" - href="#ClassicPatternLayout">PatternLayout</a></h3> + <h2><a name="ClassicPatternLayout" + href="#ClassicPatternLayout">PatternLayout</a></h2> Logback classic ships with a flexible layout called <a href="../xref/ch/qos/logback/classic/PatternLayout.html"> @@ -295,8 +304,17 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { braces. The conversion word controls the type of data to use, e.g. logger name, level, date, thread name. The format modifiers control such things as field width, padding, and left or right - justification. The following is a simple example. + justification. + + Given that <code>FileAppender</code> and sub-classes expect an + encoder, the <code>PatternLayout</code> instance must be wrapped + within an encoder before being used as a sub-component of + <code>FileAppender</code>. <code>PatternLayoutEncoder</code> is + designed solely for the purpose of wrapping a + <code>PatternLayout</code> instance so that it can be seen as + encoder. Here is an example: + Example 5.1: Sample usage of a PatternLayout <a href="../xref/chapters/layouts/PatternSample.html"> @@ -307,21 +325,28 @@ public class MySampleLayout2 extends LayoutBase<ILoggingEvent> { import org.slf4j.LoggerFactory; import ch.qos.logback.classic.Logger; -import ch.qos.logback.classic.PatternLayout; +import ch.qos.logback.classic.LoggerContext; +import ch.qos.logback.classic.encoder.PatternLayoutEncoder; +import ch.qos.logback.classic.spi.ILoggingEvent; import ch.qos.logback.core.ConsoleAppender; public class PatternSample { static public void main(String[] args) throws Exception { - Logger rootLogger = (Logger)LoggerFactory.getLogger("root"); + Logger rootLogger = (Logger)LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME); + LoggerContext loggerContext = rootLogger.getLoggerContext(); + // we are not interested in auto-configuration + loggerContext.reset(); - PatternLayout layout = new PatternLayout(); - layout.setPattern("%-5level [%thread]: %message%n"); - layout.start(); + PatternLayoutEncoder encoder = new PatternLayoutEncoder(); + encoder.setContext(loggerContext); + encoder.setPattern("%-5level [%thread]: %message%n"); + encoder.start(); ConsoleAppender<ILoggingEvent> appender = new ConsoleAppender<ILoggingEvent>(); - appender.setContext(rootLogger.getLoggerContext()); - appender.setLayout(layout); appender.start(); + appender.setContext(loggerContext); + appender.setEncoder(encoder); + appender.start(); rootLogger.addAppender(appender); @@ -1731,7 +1756,8 @@ public class TrivialMain { modules address different needs, but in general offer comparable functionality. - <h3>Writing your own Layout</h3> + <h2>Writing your own Layout</h2> + Writing a custom <code>Layout</code> for logback access is nearly identical to its sibling<code>Layout</code> in logback-classic. diff --git a/logback-site/src/site/pages/manual/menu.js b/logback-site/src/site/pages/manual/menu.js index c41b284..d7679cb 100644 --- a/logback-site/src/site/pages/manual/menu.js +++ b/logback-site/src/site/pages/manual/menu.js @@ -4,8 +4,8 @@ document.write('<a href="introduction.html">Ch1: Introduction document.write('<a href="architecture.html">Ch2: Architecture</a>'); document.write('<a href="configuration.html">Ch3: Configuration</a>'); document.write('<a href="appenders.html">Ch4: Appenders</a>'); -document.write('<a href="layouts.html">Ch5: Layouts</a>'); -document.write('<a href="encoders.html">Ch6: Encoders</a>'); +document.write('<a href="encoders.html">Ch5: Encoders</a>'); +document.write('<a href="layouts.html">Ch6: Layouts</a>'); document.write('<a href="filters.html">Ch7: Filters</a>'); document.write('<a href="mdc.html">Ch8: Mapped Diagnostic Contexts</a>'); document.write('<a href="loggingSeparation.html">Ch9: Logging Separation</a>'); ----------------------------------------------------------------------- Summary of changes: .../java/ch/qos/logback/core/encoder/Encoder.java | 41 +++++ .../{html => encoder}/LayoutWrappingEncoder.java | 3 +- .../logback/core/encoder/ObjectStreamEncoder.java | 3 +- .../core/pattern/PatternLayoutEncoderBase.java | 2 +- .../qos/logback/core/OutputStreamAppenderTest.java | 2 +- .../main/java/chapters/layouts/PatternSample.java | 14 +- .../main/java/chapters/layouts/SampleLogging.java | 17 +-- .../java/chapters/layouts/sampleLayoutConfig.xml | 11 +- .../java/chapters/layouts/sampleLayoutConfig2.xml | 14 +- logback-site/src/site/pages/manual/encoders.html | 165 +++++++++++++++++++- logback-site/src/site/pages/manual/index.html | 14 +- logback-site/src/site/pages/manual/layouts.html | 114 ++++++++----- logback-site/src/site/pages/manual/menu.js | 4 +- 13 files changed, 318 insertions(+), 86 deletions(-) rename logback-core/src/main/java/ch/qos/logback/core/{html => encoder}/LayoutWrappingEncoder.java (97%) hooks/post-receive -- Logback: the generic, reliable, fast and flexible logging framework.

1 0

[JIRA] Created: (LBCLASSIC-190) Allow programmatic traversal of the logger tree
by Robert Elliot (JIRA) 08 Mar '10

08 Mar '10

Allow programmatic traversal of the logger tree ----------------------------------------------- Key: LBCLASSIC-190 URL: http://jira.qos.ch/browse/LBCLASSIC-190 Project: logback-classic Issue Type: Improvement Components: Other Affects Versions: 0.9.19 Reporter: Robert Elliot Assignee: Logback dev list I'm interested in writing a module for logback to allow on the fly changes to the logger tree - changing levels, adding appenders, maybe adding filters with code supplied dynamically. My vision for the gui is to show the logger tree like a folder tree. However, now I come to look at it it seems neither the child loggers nor the parent logger of a logger are exposed, which rather blows this whole concept out of the water. Is there a particularly strong reason for this? If not, I've forked logback here: http://github.com/Mahoney/logback and exposed the data. As part of the same thing I changed the children from a List to a Set as it seems more semantically correct and cleans up the code slightly. -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

2 3

[JIRA] Created: (CONSPLUG-23) double-click on console log message doesn't open editor when message came from an inner class
by Joe Kearney (JIRA) 08 Mar '10

08 Mar '10

double-click on console log message doesn't open editor when message came from an inner class --------------------------------------------------------------------------------------------- Key: CONSPLUG-23 URL: http://jira.qos.ch/browse/CONSPLUG-23 Project: Console Plugin Issue Type: Bug Environment: Eclipse 3.5.2, Logback console 1.1.0, logback 0.9.0, slf4j 1.5.11 Reporter: Joe Kearney Assignee: Logback dev list Example below. All three log messages are logged, but only the first goes to the log statement on double click. {code:title=Scratch.java} package logback.console.bug.demo; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class Scratch { private static final Logger LOGGER = LoggerFactory.getLogger(Scratch.class.getName()); public static void main(String[] args) { LOGGER.info("hello from main()"); new InnerClass().someMethod(); } private static class InnerClass { private static final Logger LOCAL_LOGGER = LoggerFactory.getLogger(Scratch.InnerClass.class.getName()); public void someMethod() { LOGGER.info("Hello from inner class through outer logger"); LOCAL_LOGGER.info("Hello from inner class through inner logger"); } } } {code} -- This message is automatically generated by JIRA. - If you think it was sent incorrectly contact one of the administrators: http://jira.qos.ch/secure/Administrators.jspa - For more information on JIRA, see: http://www.atlassian.com/software/jira

1 0