[logback-dev] svn commit: r2425 - in logback/trunk: logback-core/src/main/java/ch/qos/logback/core/joran/action logback-site/src/site/pages/manual
noreply.ceki at qos.ch
noreply.ceki at qos.ch
Sun Aug 9 00:55:29 CEST 2009
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
More information about the logback-dev
mailing list