Author: ceki Date: Sun Aug 9 00:55:28 2009 New Revision: 2425 Added: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/TimestampAction.java Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ParamAction.java logback/trunk/logback-site/src/site/pages/manual/appenders.html Log: - Started working on LBCORE-91 with TimestampAction - improved docs on TimeBasedRollingPolicy Modified: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ParamAction.java ============================================================================== --- logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ParamAction.java (original) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/ParamAction.java Sun Aug 9 00:55:28 2009 @@ -1,13 +1,14 @@ /** - * LOGBack: the generic, reliable, fast and flexible logging framework. + * Logback: the generic, reliable, fast and flexible logging framework. * - * Copyright (C) 1999-2006, QOS.ch + * Copyright (C) 2000-2009, QOS.ch * * This library is free software, you can redistribute it and/or modify it under * the terms of the GNU Lesser General Public License as published by the Free * Software Foundation. */ + package ch.qos.logback.core.joran.action; Added: logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/TimestampAction.java ============================================================================== --- (empty file) +++ logback/trunk/logback-core/src/main/java/ch/qos/logback/core/joran/action/TimestampAction.java Sun Aug 9 00:55:28 2009 @@ -0,0 +1,44 @@ +package ch.qos.logback.core.joran.action; + +import java.text.SimpleDateFormat; +import java.util.Date; + +import org.xml.sax.Attributes; + +import ch.qos.logback.core.joran.spi.ActionException; +import ch.qos.logback.core.joran.spi.InterpretationContext; +import ch.qos.logback.core.util.OptionHelper; + +public class TimestampAction extends Action { + static String DATE_PATTERN_ATTRIBUTE = "datePattern"; + + boolean inError = false; + + @Override + public void begin(InterpretationContext ec, String name, Attributes attributes) throws ActionException { + String nameStr = attributes.getValue(NAME_ATTRIBUTE); + if(OptionHelper.isEmpty(nameStr)) { + addError("["+NAME_ATTRIBUTE+"] attribute cannot be empty"); + inError = true; + } + String datePatternStr = attributes.getValue(DATE_PATTERN_ATTRIBUTE); + if(OptionHelper.isEmpty(datePatternStr)) { + addError("["+DATE_PATTERN_ATTRIBUTE+"] attribute cannot be empty"); + inError = true; + } + + if(inError) + return; + + SimpleDateFormat sdf = new SimpleDateFormat(datePatternStr); + String val = sdf.format(new Date()); + + addInfo("Adding property ["+nameStr+"] with value ["+val+"] to the context"); + context.putProperty(nameStr, val); + } + + @Override + public void end(InterpretationContext ec, String name) throws ActionException { + } + +} Modified: logback/trunk/logback-site/src/site/pages/manual/appenders.html ============================================================================== --- logback/trunk/logback-site/src/site/pages/manual/appenders.html (original) +++ logback/trunk/logback-site/src/site/pages/manual/appenders.html Sun Aug 9 00:55:28 2009 @@ -927,7 +927,7 @@ href="../xref/ch/qos/logback/core/rolling/TimeBasedRollingPolicy.html"> <code>TimeBasedRollingPolicy</code></a> is possibly the most popular rolling policy. It defines a rollover policy based on time, - say by day or by month. + for example by day or by month. </p> <p><code>TimeBasedRollingPolicy</code>'s admits two properties, the @@ -935,15 +935,30 @@ the optional <span class="option">MaxHistory</span> property. </p> - <p><span class="option">FileNamePattern</span> option defines the + <p><span class="option">FileNamePattern</span> property defines the name of the rolled (archived) log files. Its value should consist of the name of the file, plus a suitably placed <em>%d</em> conversion specifier. The <em>%d</em> conversion specifier may contain a date-and-time pattern as specified by the <code>java.text.SimpleDateFormat</code> class. If the date-and-time pattern is omitted, then the default pattern - <em>yyyy-MM-dd</em> is assumed. The following examples should - clarify the point. + <em>yyyy-MM-dd</em> is assumed. The <span + class="option">File</span> property in + <code>RollingFileAppender</code> (the parent of + <code>TimeBasedRollingPolicy</code>) can be either set or omitted. + + </p> + + <p>By setting the <span class="option">File</span> property you can + decouple the location of the active log file and the location of + the archived log files. The current logs will be always targeted at + the file specified by the <span class="option">File</span> + property. It follows that the name of the currently active log file + will not change over time. However, if you choose to omit the <span + class="option">File</span> property, then the active file will be + computed anew for each period based on the value of <span + class="option">FileNamePattern</span>. The following examples + should clarify the point. </p> <table class="bodyTable"> @@ -951,7 +966,7 @@ <th> <span class="option">FileNamePattern</span> </th> - <th>Roll-over schedule</th> + <th>Rollover schedule</th> <th>Example</th> </tr> <tr class="b"> @@ -963,34 +978,52 @@ specifier, the default pattern of <em>yyyy-MM-dd</em> is assumed, which corresponds to daily rollover. </td> + <td> - <p>Assuming the <span class="option">File</span> property is - not set, during November 23rd, 2006, logging output will go - to the file <em>/wombat/foo.2006-11-23</em>. At midnight and - for the rest of the 24th, logging output will be directed to + <p><span class="option">File</span> property not set: During November + 23rd, 2006, logging output will go to the file + <em>/wombat/foo.2006-11-23</em>. At midnight and for the + rest of the 24th, logging output will be directed to <em>/wombat/foo.2006-11-24</em>. </p> + + <p><span class="option">File</span> property set to + <em>/wombat/foo.txt</em>: During November 23rd, 2006, logging + output will go to the file <em>/wombat/foo.txt</em>. At + midnight, <em>foo.txt</em> will be renamed as + <em>/wombat/foo.2006-11-23</em>. A new + <em>/wombat/foo.txt</em> file will be created and for the + rest of November 24th logging output will be directed to + <em>foo.txt</em>. + </p> + </td> </tr> <tr class="a"> <td class="small"> - <em>/wombat/%d{yyyy/MM}/log.txt</em> + <em>/wombat/%d{yyyy/MM}/foo.txt</em> </td> <td>Rollover at the beginning of each month.</td> <td> - <p>During the month of October 2006, logging output will go - to <em>/wombat/2006/10/log.txt</em>. After midnight of - October 31st and for the rest of November, logging output - will be directed to <em>/wombat/2006/11/log.txt</em>. + <p><span class="option">File</span> property not set: During the + month of October 2006, logging output will go to + <em>/wombat/2006/10/foo.txt</em>. After midnight of October + 31st and for the rest of November, logging output will be + directed to <em>/wombat/2006/11/foo.txt</em>. </p> - <p>However, if the <span class="option">File</span> property is - set, for example to <em>log.txt</em>, then logging will always - written to <em>log.txt</em>. At midnight and - for the rest of the 24th, logging output will be directed to - <em>/wombat/foo.2006-11-24</em> + <p><span class="option">File</span> property set to + <em>/wombat/foo.txt</em>: The active log file will always be + <em>/wombat/foo.txt</em>. During the month of October 2006, + logging output will go to <em>/wombat/foo.txt</em>. At + midnight of October 31st, <em>/wombat/foo.txt</em> will be + renamed as <em>/wombat/2006/10/foo.txt</em>. A new + <em>/wombat/foo.txt</em> file will be created where logging + output will go for the rest of November. At midnight of + November 30th, <em>/wombat/foo.txt</em> will be renamed as + <em>/wombat/2006/11/foo.txt</em> and so on. </p> </td> </tr> @@ -1002,23 +1035,17 @@ <td>Rollover at the first day of each week. Note that the first day of the week depends on the locale.</td> - <td>During the 23rd week of 2006, the file - <em>/wombat/foo.2006-23.log</em> will contain the actual logging - output. Logging for the 24th week of 2006 will be output to - <em>/wombat/foo.2006-24.log</em> until it is rolled over at the - beginning of the next week. - </td> + <td>Similar to previous cases, except that rollover will occur + at the beginning of every new week. + </td> </tr> <tr class="a"> <td class="small"> <em>/wombat/foo.   /<br/>%d{yyyy-MM-dd_HH}.log</em> </td> <td>Rollover at the top of each hour.</td> - <td>Between 11.00,001 and 11.59,999, on November 3rd, 2006, the - logging will be output to - <em>/wombat/foo.2006-11-03_11.log</em>. After that, and until - 12.59,999, the logging will be output to - <em>/wombat/foo.2006-11-03_12.log</em>. + <td>Similar to previous cases, except that rollover will occur + at the top of every hour. </td> </tr> <tr class="b"> @@ -1026,16 +1053,21 @@ <em>/wombat/foo.    /<br/>%d{yyyy-MM-dd_HH-mm}.log</em> </td> <td>Rollover at the beginning of every minute.</td> - <td>Between 11.32,001 and 11.32,999, on November 3rd, 2006, the - logging will be output to - <em>/wombat/foo.2006-11-03_11-32.log</em>. After that, and - until 12.33,999, the logging will be output to - <em>/wombat/foo.2006-11_12-33.log</em>. - </td> + <td>Similar to previous cases, except that rollover will occur + at the beginning of every minute. + </td> </tr> </table> - <p>Any characters in the pattern outside the ranges + <p>Any forward or backward slash characters are interpreted as + folder (directory) separators. Any required folder will be created + as necessary. You can thus easily place your log files in separate + folders. + </p> + + <p>The date-and-time pattern, as found within accolades in %d{} + follow java.text.SimpleDateFormat conventions. This any characters + within the date-and-time pattern outside the ranges <em>['a'..'z']</em> and <em>['A'..'Z']</em> will be treated as quoted text. For instance, characters like <em>'.'</em>, <em>' '</em>, <em>'#'</em> and <em>'@'</em> will appear in the resulting @@ -1044,13 +1076,15 @@ <em>":"</em> character anywhere within the <span class="option">FileNamePattern</span> option. The text before the colon is interpreted as the protocol specification of a URL, which - is most probably not what you intend. The slash <em>"/"</em> - character, a common date field separator, must also be avoided. It - is taken as a file separator causing the rollover operation to fail - because the target file cannot be created. Although less common, - the backslash character <em>"\"</em> is equally troublesome. + is most probably not what you intend. The forward-slash + <em>"/"</em> or backward slash <em>"\"</em> characters anywhere + within the <span class="option">FileNamePattern</span> property or + within the date-and-time pattern will be interpreted as directory + separators and any missing directories will be created as + necessary. </p> + <p>Just like <code>FixedWindowRollingPolicy</code>, <code>TimeBasedRollingPolicy</code> supports automatic file compression. This feature is enabled if the value of the <span @@ -1067,12 +1101,27 @@ <td><em>/wombat/foo.%d.gz</em></td> <td>Daily rollover (at midnight) with automatic GZIP compression of the archived files.</td> - <td>During November 23rd, 2004, logging output will go to - the file <em>/wombat/foo.2004-11-23</em>. However, at midnight that - file will be compressed to become <em>/wombat/foo.2004-11-23.gz</em>. - For the 24th of November, logging output will be directed to - <em>/wombat/folder/foo.2004-11-24</em> until its rolled over at the - beginning of the next day. + <td> + <p><span class="option">File</span> property not set: During + November 23rd, 2009, logging output will go to the file + <em>/wombat/foo.2009-11-23</em>. However, at midnight that + file will be compressed to become + <em>/wombat/foo.2009-11-23.gz</em>. For the 24th of November, + logging output will be directed to + <em>/wombat/folder/foo.2009-11-24</em> until its rolled over + at the beginning of the next day. + </p> + + <p><span class="option">File</span> property set to + /wombat/foo.txt: During November 23rd, 2009, logging output + will go to the file <em>/wombat/foo.txt</em>. At midnight that + file will be compressed and renamed as + <em>/wombat/foo.2009-11-23.gz</em>. A new + <em>/wombat/foo.txt</em> file will be created where logging + output will go for the rest of November 24rd. At midnight + November 24th, <em>/wombat/foo.txt</em> will be compressed and + renamed as <em>/wombat/foo.2009-11-24.gz</em>. and so on. + </p> </td> </tr> </table> @@ -1086,10 +1135,10 @@ resulting archive files will carry different names. </p> - <p>Thus, <code>TimeBasedRollingPolicy</code> assumes the - responsibility for rollover as well as for the triggering of said - rollover. Indeed, <code>TimeBasedTriggeringPolicy</code> implements - both <code>RollingPolicy</code> and <code>TriggeringPolicy</code> + <p><code>TimeBasedRollingPolicy</code> assumes the responsibility + for rollover as well as for the triggering of said rollover. Indeed, + <code>TimeBasedTriggeringPolicy</code> implements both + <code>RollingPolicy</code> and <code>TriggeringPolicy</code> interfaces. </p> @@ -1108,22 +1157,25 @@ maximum number of archive files to keep, deleting older files. For example, if you specify monthly rollover, and set <span class="option">MaxHistory</span> to 6, then 6 months worth of - archives files will be kept with files older than 6 months deleted. + archives files will be kept with files older than 6 months + deleted. Note as old archived log files are removed, any folders + which were created for the purpose of log file archiving will be + removed as appropriate. </p> - <p>For various reasons, rollovers are not clock-driven but depend on - the arrival of logging events. For example, on 8th of March 2002, - assuming the <span class="option">FileNamePattern</span> is set to - <em>yyyy-MM-dd</em> (daily rollover), the arrival of the first event - after midnight will trigger a rollover. If there are no logging - events during, say 23 minutes and 47 seconds after midnight, then - rollover will actually occur at 00:23'47 AM on March 9th and not at - 0:00 AM. Thus, depending on the arrival rate of events, rollovers - might be triggered with some latency. However, regardless of the - delay, the rollover algorithm is known to be correct, in the sense - that all logging events generated during a certain period will be - output in the correct file delimiting that period. + <p>For various technical reasons, rollovers are not clock-driven but + depend on the arrival of logging events. For example, on 8th of + March 2002, assuming the <span class="option">FileNamePattern</span> + is set to <em>yyyy-MM-dd</em> (daily rollover), the arrival of the + first event after midnight will trigger a rollover. If there are no + logging events during, say 23 minutes and 47 seconds after midnight, + then rollover will actually occur at 00:23'47 AM on March 9th and + not at 0:00 AM. Thus, depending on the arrival rate of events, + rollovers might be triggered with some latency. However, regardless + of the delay, the rollover algorithm is known to be correct, in the + sense that all logging events generated during a certain period will + be output in the correct file delimiting that period. </p> <p>Here is a sample configuration for