[logback-dev] [GIT] Logback: the generic, reliable, fast and flexible logging framework. branch master updated. v_1.0.0-58-gdc9180b
Gitbot
git-noreply at pixie.qos.ch
Thu Dec 22 00:11:02 CET 2011
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 dc9180b6daf4950b601e9137fff093d4ba093a70 (commit)
from 7900adbea8f61de47e933d892cbaee1d61e9f111 (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=dc9180b6daf4950b601e9137fff093d4ba093a70
http://github.com/ceki/logback/commit/dc9180b6daf4950b601e9137fff093d4ba093a70
commit dc9180b6daf4950b601e9137fff093d4ba093a70
Author: Ceki Gulcu <ceki at qos.ch>
Date: Thu Dec 22 00:08:58 2011 +0100
add a .prop class as a synonym for .option
diff --git a/logback-site/src/site/pages/css/common.css b/logback-site/src/site/pages/css/common.css
index 1c4e954..fd1ffaf 100644
--- a/logback-site/src/site/pages/css/common.css
+++ b/logback-site/src/site/pages/css/common.css
@@ -238,7 +238,7 @@ table.bodyTable tr td p:first-child {
}
-.option {
+.option, .prop {
border-top: 1px dotted black;
border-bottom: 1px dotted black;
border-left: 1px dotted black;
diff --git a/logback-site/src/site/pages/manual/appenders.html b/logback-site/src/site/pages/manual/appenders.html
index 130aebc..23aa8e7 100644
--- a/logback-site/src/site/pages/manual/appenders.html
+++ b/logback-site/src/site/pages/manual/appenders.html
@@ -259,7 +259,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
</tr>
<tr class="a">
- <td><b><span class="option">encoder</span></b></td>
+ <td><b><span class="prop">encoder</span></b></td>
<td><a
href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a></td>
@@ -275,9 +275,9 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
we have conducted, it appears that turning off immediate flushing or
buffering of character to byte conversions have rather small impact
on performance. As such, as of logback version 0.9.19, the <span
- class="option">ImmediateFlush</span>, <span
- class="option">BufferedIO</span> and <span
- class="option">BufferSize</span> properties have been removed
+ class="prop">ImmediateFlush</span>, <span
+ class="prop">BufferedIO</span> and <span
+ class="prop">BufferSize</span> properties have been removed
without replacement.
</p>
@@ -315,14 +315,14 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
<th>Description</th>
</tr>
<tr class="b">
- <td><b><span class="option">encoder</span></b></td>
+ <td><b><span class="prop">encoder</span></b></td>
<td>
<a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
</td>
<td>See <code>OutputStreamAppender</code> properties.</td>
</tr>
<tr class="a">
- <td><b><span class="option">target</span></b></td>
+ <td><b><span class="prop">target</span></b></td>
<td><code>String</code></td>
<td>
One of the String values <em>System.out</em> or
@@ -375,9 +375,9 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
href="../xref/ch/qos/logback/core/FileAppender.html"><code>FileAppender</code></a>,
a subclass of <code>OutputStreamAppender</code>, appends log events into
a file. The target file is specified by the <span
- class="option">File</span> option. If the file already exists, it
+ class="prop">File</span> option. If the file already exists, it
is either appended to, or truncated depending on the value of the
- <span class="option">Append</span> option.
+ <span class="prop">Append</span> option.
</p>
<table class="bodyTable properties">
@@ -387,17 +387,17 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
<th>Description</th>
</tr>
<tr class="alt">
- <td><b><span class="option">append</span></b></td>
+ <td><b><span class="prop">append</span></b></td>
<td><code>boolean</code></td>
<td>If true, events are appended at the end of an existing
- file. Otherwise, if <span class="option">Append</span> is
+ file. Otherwise, if <span class="prop">Append</span> is
false, any existing file is truncated. The <span
- class="option">Append</span> option is set to true by
+ class="prop">Append</span> option is set to true by
default.
</td>
</tr>
<tr >
- <td><b><span class="option">encoder</span></b></td>
+ <td><b><span class="prop">encoder</span></b></td>
<td>
<a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
</td>
@@ -406,7 +406,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
<tr class="alt">
- <td><b><span class="option">file</span></b></td>
+ <td><b><span class="prop">file</span></b></td>
<td><code>String</code></td>
<td>The name of the file to write to. If the file does not
exist, it is created. On the MS Windows platform users
@@ -416,7 +416,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
a single tab character <em>(\u0009)</em>. Correct values can
be specified as <em>c:/temp/test.log</em> or alternatively as
<em>c:\\temp\\test.log</em>. The <span
- class="option">File</span> option has no default value.
+ class="prop">File</span> option has no default value.
<p>If the parent directory of the file does not exist,
<code>FileAppender</code> will automatically create it,
@@ -438,7 +438,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
value for prudent mode is <code>false</code>.
<p>Prudent mode implies that <span
- class="option">Append</span> property is automatically set to
+ class="prop">Append</span> property is automatically set to
true.
</p>
@@ -461,7 +461,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
per second, the impact on performance should be
negligible. Applications generating 100 or more I/O
operations per second can see an impact on performance and
- should avoid using <span class="option">prudent</span> mode.
+ should avoid using <span class="prop">prudent</span> mode.
</p>
<p>Prudent mode can be used in conjunction with
@@ -629,24 +629,24 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
<th>Description</th>
</tr>
<tr class="b">
- <td><b><span class="option">file</span></b></td>
+ <td><b><span class="prop">file</span></b></td>
<td><code>String</code></td>
<td>See <code>FileAppender</code> properties.</td>
</tr>
<tr class="a">
- <td><b><span class="option">append</span></b></td>
+ <td><b><span class="prop">append</span></b></td>
<td><code>boolean</code></td>
<td>See <code>FileAppender</code> properties.</td>
</tr>
<tr class="b">
- <td><b><span class="option">encoder</span></b></td>
+ <td><b><span class="prop">encoder</span></b></td>
<td>
<a href="../xref/ch/qos/logback/core/encoder/Encoder.html"><code>Encoder</code></a>
</td>
<td>See <code>OutputStreamAppender</code> properties.</td>
</tr>
<tr class="a">
- <td><b><span class="option">rollingPolicy</span></b></td>
+ <td><b><span class="prop">rollingPolicy</span></b></td>
<td><code>RollingPolicy</code></td>
<td>This option is the component that will dictate
<code>RollingFileAppender</code>'s behavior when rollover
@@ -654,7 +654,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
</td>
</tr>
<tr class="b">
- <td><b><span class="option">triggeringPolicy</span></b></td>
+ <td><b><span class="prop">triggeringPolicy</span></b></td>
<td><code>TriggeringPolicy</code></td>
<td>
This option is the component that will tell
@@ -663,7 +663,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
</td>
</tr>
<tr class="a">
- <td valign="top"><span class="option"><a name="prudentWithRolling"
+ <td valign="top"><span class="prop"><a name="prudentWithRolling"
href="#prudentWithRolling"><b>prudent</b></a></span></td>
<td valign="top"><code>boolean</code></td>
@@ -687,7 +687,7 @@ public interface Appender<E> extends LifeCycle, ContextAware, FilterAttachabl
allowed. (We can't have one JVM writing to a file while
another JVM is compressing it.) </li>
- <li>The <span class="option">file</span> property of
+ <li>The <span class="prop">file</span> property of
<code>FileAppender</code> cannot be set and must be left
blank. Indeed, most operating systems do not allow renaming
of a file while another process has it opened.
@@ -748,15 +748,14 @@ public interface RollingPolicy extends LifeCycle {
for example by day or by month.
<code>TimeBasedRollingPolicy</code> assumes the responsibility for
rollover as well as for the triggering of said rollover. Indeed,
- <code>TimeBasedTriggeringPolicy</code> implements both
+ <code>TimeBasedTriggeringPolicy</code> implements <em>both</em>
<code>RollingPolicy</code> and <code>TriggeringPolicy</code>
interfaces.
</p>
- <p><code>TimeBasedRollingPolicy</code>'s configuration has two
- properties, the mandatory <span
- class="option">fileNamePattern</span> property and the optional
- <span class="option">maxHistory</span> property.
+ <p><code>TimeBasedRollingPolicy</code>'s configuration takes one
+ mandatory <span class="prop">fileNamePattern</span> property and
+ several optional properties.
</p>
<table class="bodyTable">
@@ -766,10 +765,10 @@ public interface RollingPolicy extends LifeCycle {
<th>Description</th>
</tr>
<tr class="b">
- <td><b><span class="option">fileNamePattern</span></b></td>
+ <td><b><span class="prop">fileNamePattern</span></b></td>
<td><code>String</code></td>
<td>
- The mandatory <span class="option">fileNamePattern</span>
+ The mandatory <span class="prop">fileNamePattern</span>
property defines the name of the rolled-over (archived) log
files. Its value should consist of the name of the file, plus
a suitably placed <em>%d</em> conversion specifier. The
@@ -777,23 +776,26 @@ public interface RollingPolicy extends LifeCycle {
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 <span
- class="option">File</span> property in
+ <em>yyyy-MM-dd</em> is assumed. <b>The rollover period is
+ inferred from the value of <span
+ class="prop">fileNamePattern</span>.</b>
+
+
+ <p>Note that the <span class="prop">file</span> property in
<code>RollingFileAppender</code> (the parent of
<code>TimeBasedRollingPolicy</code>) can be either set or
- omitted.
-
- <p>By setting the <span class="option">file</span> property
- of the containing <code>FileAppender</code>, 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 examples below should clarify the point.
+ omitted. By setting the <span class="prop">file</span>
+ property of the containing <code>FileAppender</code>, 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="prop">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="prop">file</span> property, then the active file
+ will be computed anew for each period based on the value of
+ <span class="prop">fileNamePattern</span>. The examples
+ below should clarify this point.
</p>
<p>The date-and-time pattern, as found within the accolades
@@ -803,12 +805,17 @@ public interface RollingPolicy extends LifeCycle {
date-and-time pattern will be interpreted as directory
separators.
</p>
+
+ <p>It is possible to specify multiple %d tokens but only one
+ of which can be primary, i.e. used to infer the rollover
+ period. All other tokens <em>must</em> be marked as auxiliary
+ by passing the AUX paramater (see examples below).</p>
</td>
</tr>
<tr class="a">
- <td><span class="option"><b>maxHistory</b></span></td>
+ <td><span class="prop"><b>maxHistory</b></span></td>
<td>int</td>
- <td>The optional <span class="option">maxHistory</span>
+ <td>The optional <span class="prop">maxHistory</span>
property controls the maximum number of archive files to keep,
deleting older files. For example, if you specify monthly
rollover, and set maxHistory to 6, then 6 months worth of
@@ -820,7 +827,7 @@ public interface RollingPolicy extends LifeCycle {
</tr>
<tr class="b">
- <td><span class="option"><b>cleanHistoryOnStart</b></span></td>
+ <td><span class="prop"><b>cleanHistoryOnStart</b></span></td>
<td>boolean</td>
<td>
<p>If set to true, archive removal will be executed on
@@ -832,7 +839,7 @@ public interface RollingPolicy extends LifeCycle {
roll over to be triggered. It follows that for such
short-lived applications archive removal may never get a
chance to execute. By setting <span
- class="option">cleanHistoryOnStart</span> to true, archive
+ class="prop">cleanHistoryOnStart</span> to true, archive
removal is performed at appender start up.</p>
</td>
</tr>
@@ -847,7 +854,7 @@ public interface RollingPolicy extends LifeCycle {
<table class="bodyTable">
<tr class="a">
<th>
- <span class="option">fileNamePattern</span>
+ <span class="prop">fileNamePattern</span>
</th>
<th>Rollover schedule</th>
<th>Example</th>
@@ -863,14 +870,14 @@ public interface RollingPolicy extends LifeCycle {
</td>
<td>
- <p><span class="option">file</span> property not set: During November
+ <p><span class="prop">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
+ <p><span class="prop">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
@@ -890,14 +897,14 @@ public interface RollingPolicy extends LifeCycle {
</td>
<td>Rollover at the beginning of each month.</td>
<td>
- <p><span class="option">file</span> property not set: During
+ <p><span class="prop">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><span class="option">file</span> property set to
+ <p><span class="prop">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
@@ -924,7 +931,7 @@ public interface RollingPolicy extends LifeCycle {
</tr>
<tr class="a">
<td class="small">
- <em>/wombat/foo. /<br/>%d{yyyy-MM-dd_HH}.log</em>
+ <em>/wombat/foo%d{yyyy-MM-dd_HH}.log</em>
</td>
<td>Rollover at the top of each hour.</td>
<td>Similar to previous cases, except that rollover will occur
@@ -933,13 +940,32 @@ public interface RollingPolicy extends LifeCycle {
</tr>
<tr class="b">
<td class="small">
- <em>/wombat/foo. /<br/>%d{yyyy-MM-dd_HH-mm}.log</em>
+ <em>/wombat/foo%d{yyyy-MM-dd_HH-mm}.log</em>
</td>
<td>Rollover at the beginning of every minute.</td>
<td>Similar to previous cases, except that rollover will occur
at the beginning of every minute.
</td>
</tr>
+
+
+ <tr class="a">
+ <td class="small">
+ <em>/foo/%d{yyyy-MM,<b>aux</b>}/%d.log</em>
+ </td>
+ <td>Rollover daily. Archives located under a folder contaning
+ year and month.
+ </td>
+ <td>In this example, the first %d token is marked as
+ <b>aux</b>iliary. The second %d token, with time and date
+ pattern omitted, is then assumed to be primary. Thus, rollover
+ will occur daily (default for %d) and the folder name will
+ depend on the year and month. For example, during the month of
+ November 2006, archived files will all placed under the
+ /foo/2006-11/ folder, e.g <em>/foo/2006-11/2006-11-14.log</em>.
+ </td>
+
+ </tr>
</table>
<p>Any forward or backward slash characters are interpreted as
@@ -952,13 +978,13 @@ public interface RollingPolicy extends LifeCycle {
<p>Just like <code>FixedWindowRollingPolicy</code>,
<code>TimeBasedRollingPolicy</code> supports automatic file
compression. This feature is enabled if the value of the <span
- class="option">fileNamePattern</span> option ends with <em>.gz</em>
+ class="prop">fileNamePattern</span> option ends with <em>.gz</em>
or <em>.zip</em>.
</p>
<table class="bodyTable">
<tr class="a">
- <th><span class="option">fileNamePattern</span></th>
+ <th><span class="prop">fileNamePattern</span></th>
<th>Rollover schedule</th>
<th>Example</th>
</tr>
@@ -967,7 +993,7 @@ public interface RollingPolicy extends LifeCycle {
<td>Daily rollover (at midnight) with automatic GZIP compression of the
archived files.</td>
<td>
- <p><span class="option">file</span> property not set: During
+ <p><span class="prop">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
@@ -977,7 +1003,7 @@ public interface RollingPolicy extends LifeCycle {
at the beginning of the next day.
</p>
- <p><span class="option">file</span> property set to
+ <p><span class="prop">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
@@ -991,7 +1017,7 @@ public interface RollingPolicy extends LifeCycle {
</tr>
</table>
- <p>The <span class="option">fileNamePattern</span> serves a dual
+ <p>The <span class="prop">fileNamePattern</span> serves a dual
purpose. First, by studying the pattern, logback computes the
requested rollover periodicity. Second, it computes each archived
file's name. Note that it is possible for two different patterns to
@@ -1000,25 +1026,25 @@ public interface RollingPolicy extends LifeCycle {
resulting archive files will carry different names.
</p>
- <p>By setting the <span class="option">file</span> property you can
+ <p>By setting the <span class="prop">file</span> property you can
decouple the location of the active log file and the location of
the archived log files. The logging output will be targeted into
- the file specified by the <span class="option">file</span>
+ the file specified by the <span class="prop">file</span>
property. It follows that the name of the 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
+ class="prop">file</span> property, then the active file will be
computed anew for each period based on the value of <span
- class="option">fileNamePattern</span>. By leaving the <span
- class="option">file</span> option unset you can avoid file <a
+ class="prop">fileNamePattern</span>. By leaving the <span
+ class="prop">file</span> option unset you can avoid file <a
href="../codes.html#renamingError">renaming errors</a> which occur
while there exist external file handles referencing log files during
roll over.
</p>
- <p>The <span class="option">maxHistory</span> property controls the
+ <p>The <span class="prop">maxHistory</span> property controls the
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
+ class="prop">maxHistory</span> to 6, then 6 months worth of
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
@@ -1028,7 +1054,7 @@ public interface RollingPolicy extends LifeCycle {
<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>
+ class="prop">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
@@ -1074,7 +1100,7 @@ public interface RollingPolicy extends LifeCycle {
<p>The next configuration sample illustrates the use of
<code>RollingFileAppender</code> associated with
- <code>TimeBasedRollingPolicy</code> in <span class="option">prudent</span>
+ <code>TimeBasedRollingPolicy</code> in <span class="prop">prudent</span>
mode.
</p>
@@ -1115,7 +1141,7 @@ public interface RollingPolicy extends LifeCycle {
to a fixed window algorithm as described below.
</p>
- <p>The <span class="option">fileNamePattern</span> option
+ <p>The <span class="prop">fileNamePattern</span> option
represents the file name pattern for the archived (rolled over) log
files. This option is required and must include an integer token
<em>%i</em> somewhere within the pattern.
@@ -1132,7 +1158,7 @@ public interface RollingPolicy extends LifeCycle {
<th>Description</th>
</tr>
<tr class="b">
- <td><b><span class="option">minIndex</span></b></td>
+ <td><b><span class="prop">minIndex</span></b></td>
<td><code>int</code></td>
<td>
<p>This option represents the lower bound for the window's
@@ -1141,7 +1167,7 @@ public interface RollingPolicy extends LifeCycle {
</td>
</tr>
<tr class="a">
- <td><b><span class="option">maxIndex</span></b></td>
+ <td><b><span class="prop">maxIndex</span></b></td>
<td><code>int</code></td>
<td>
<p>This option represents the upper bound for the window's
@@ -1150,7 +1176,7 @@ public interface RollingPolicy extends LifeCycle {
</td>
</tr>
<tr class="b">
- <td><b><span class="option">fileNamePattern</span></b></td>
+ <td><b><span class="prop">fileNamePattern</span></b></td>
<td><code>String</code></td>
<td>
<p>This option represents the pattern that will be followed
@@ -1166,7 +1192,7 @@ public interface RollingPolicy extends LifeCycle {
</p>
<p>Note that file compression is also specified via this
property. For example, <span
- class="option">fileNamePattern</span> set to
+ class="prop">fileNamePattern</span> set to
<em>MyLogFile%i.log.zip</em> means that archived files must be
compressed using the <em>zip</em> format; <em>gz</em> format
is also supported.
@@ -1183,11 +1209,11 @@ public interface RollingPolicy extends LifeCycle {
</p>
<p>Let us go over a more concrete example of the fixed window
- rollover policy. Suppose that <span class="option">minIndex</span>
- is set to <em>1</em>, <span class="option">maxIndex</span> set to
- <em>3</em>, <span class="option">fileNamePattern</span> property
+ rollover policy. Suppose that <span class="prop">minIndex</span>
+ is set to <em>1</em>, <span class="prop">maxIndex</span> set to
+ <em>3</em>, <span class="prop">fileNamePattern</span> property
set to <em>foo%i.log</em>, and that <span
- class="option">fileNamePattern</span> property is set to
+ class="prop">fileNamePattern</span> property is set to
<em>foo.log</em>.
</p>
@@ -1252,9 +1278,9 @@ public interface RollingPolicy extends LifeCycle {
<p>The configuration file below gives an example of configuring
<code>RollingFileAppender</code> and
<code>FixedWindowRollingPolicy</code>. Note that the <span
- class="option">File</span> option is mandatory even if it contains
+ class="prop">File</span> option is mandatory even if it contains
some of the same information as conveyed with the <span
- class="option">fileNamePattern</span> option.
+ class="prop">fileNamePattern</span> option.
</p>
<p class="example">Example: Sample configuration of a <code>RollingFileAppender</code> using a
@@ -1332,13 +1358,13 @@ public interface RollingPolicy extends LifeCycle {
<p>Note the "%i" conversion token in addition to "%d". Each time
the current log file reaches <span
- class="option">maxFileSize</span> before the current time period
+ class="prop">maxFileSize</span> before the current time period
ends, it will be archived with an increasing index, starting at
0.</p>
<p>Size and time based archiving supports deletion of old archive
files. You need to specify the number of periods to preserve with
- the <span class="option">maxHistory</span> property. When your
+ the <span class="prop">maxHistory</span> property. When your
application is stopped and restarted, logging will continue at the
correct location, i.e. at the largest index number for the current
period.
@@ -1391,11 +1417,11 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</p>
<p><code>SizeBasedTriggeringPolicy</code> accepts only one
- parameter, namely <span class="option">maxFileSize</span>, with a
+ parameter, namely <span class="prop">maxFileSize</span>, with a
default value of 10 MB.
</p>
- <p>The <span class="option">maxFileSize</span> option can be
+ <p>The <span class="prop">maxFileSize</span> option can be
specified in bytes, kilobytes, megabytes or gigabytes by suffixing
a numeric value with <em>KB</em>, <em>MB</em> and respectively
<em>GB</em>. For example, <em>5000000</em>, <em>5000KB</em>,
@@ -1517,8 +1543,8 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</p>
<p>The remote server is identified by the <span
- class="option">remoteHost</span> and <span
- class="option">port</span> properties.
+ class="prop">remoteHost</span> and <span
+ class="prop">port</span> properties.
<code>SocketAppender</code> properties are listed in the following
table.
</p>
@@ -1530,18 +1556,18 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<th>Description</th>
</tr>
<tr class="b">
- <td><b><span class="option">includeCallerData</span></b></td>
+ <td><b><span class="prop">includeCallerData</span></b></td>
<td><code>boolean</code></td>
<td>
<p>
- The <span class="option">includeCallerData</span> option takes a boolean value.
+ The <span class="prop">includeCallerData</span> option takes a boolean value.
If true, the caller data will be available to the remote host.
By default no caller data is sent to the server.
</p>
</td>
</tr>
<tr class="a">
- <td><b><span class="option">port</span></b></td>
+ <td><b><span class="prop">port</span></b></td>
<td><code>int</code></td>
<td>
<p>
@@ -1550,10 +1576,10 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</td>
</tr>
<tr class="b">
- <td><b><span class="option">reconnectionDelay</span></b></td>
+ <td><b><span class="prop">reconnectionDelay</span></b></td>
<td><code>int</code></td>
<td>
- The <span class="option">reconnectionDelay</span> option takes a
+ The <span class="prop">reconnectionDelay</span> option takes a
positive integer representing the number of milliseconds to wait between
each failed connection attempt to the server.
The default value of this option is 30'000 which corresponds to 30 seconds.
@@ -1563,7 +1589,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</td>
</tr>
<tr class="a">
- <td><b><span class="option">remoteHost</span></b></td>
+ <td><b><span class="prop">remoteHost</span></b></td>
<td><code>String</code></td>
<td>
The host name of the server.
@@ -1653,8 +1679,8 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<p>
Note that in the above configuration scripts the values for the
- <span class="option">remoteHost</span>, <span class="option">port</span> and
- <span class="option">includeCallerData</span> properties
+ <span class="prop">remoteHost</span>, <span class="prop">port</span> and
+ <span class="prop">includeCallerData</span> properties
are not given directly but as substituted variable keys. The values for the variables
can be specified as system properties:
</p>
@@ -1693,7 +1719,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<p>The outcome can be easily changed by instructing the
<code>SocketAppender</code> to include caller data by setting the
- <span class="option">includeCallerData</span> option to
+ <span class="prop">includeCallerData</span> option to
true. Using the following command will do the trick:
</p>
@@ -1732,20 +1758,20 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</tr>
<tr>
- <td><b><span class="option">smtpHost</span></b></td>
+ <td><b><span class="prop">smtpHost</span></b></td>
<td><code>String</code></td>
<td>The host name of the SMTP server. This parameter is mandatory.</td>
</tr>
<tr class="alt">
- <td><b><span class="option">smtpPort</span></b></td>
+ <td><b><span class="prop">smtpPort</span></b></td>
<td><code>int</code></td>
<td>The port where the SMTP server is listening. Defaults to
25.</td>
</tr>
<tr>
- <td><a name="smtpTo" href="#smtpTo"><b><span class="option">to</span></b></a></td>
+ <td><a name="smtpTo" href="#smtpTo"><b><span class="prop">to</span></b></a></td>
<td><code>String</code></td>
<td>The email address of the recipient as a
<em>pattern</em>. The pattern is evaluated anew with the
@@ -1758,7 +1784,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</tr>
<tr class="alt">
- <td><b><span class="option">from</span></b></td>
+ <td><b><span class="prop">from</span></b></td>
<td><code>String</code></td>
<td>The originator of the email messages sent by
<code>SMTPAppender</code> in the <a
@@ -1771,7 +1797,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</td>
</tr>
<tr>
- <td><b><span class="option">subject</span></b></td>
+ <td><b><span class="prop">subject</span></b></td>
<td><code>String</code></td>
<td>
<p>The subject of the email. It can be any value accepted as
@@ -1785,7 +1811,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
that triggered the email message.
</p>
- <p>Assuming the <span class="option">subject</span> option
+ <p>Assuming the <span class="prop">subject</span> option
is set to "Log: %logger - %msg" and the triggering event's
logger is named "com.foo.Bar", and contains the message
"Hello world", then the outgoing email will have the subject
@@ -1797,11 +1823,11 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</tr>
<tr class="alt">
- <td><b><span class="option">discriminator</span></b></td>
+ <td><b><span class="prop">discriminator</span></b></td>
<td><code><a href="../xref/ch/qos/logback/core/sift/Discriminator.html">Discriminator</a></code></td>
<td>
<p>With the help of a <span
- class="option">Discriminator</span>,
+ class="prop">Discriminator</span>,
<code>SMTPAppender</code> can scatter incoming events into
different buffers according to the value returned by the
discriminator. The default discriminator always returns the
@@ -1816,7 +1842,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</td>
</tr>
<tr >
- <td><b><span class="option"><a name="smtpAppender_Evaluator"
+ <td><b><span class="prop"><a name="smtpAppender_Evaluator"
href="#smtpAppender_Evaluator">evaluator</a></span></b></td>
<td><code><a
href="../xref/ch/qos/logback/classic/boolex/IEvaluator.html">IEvaluator</a></code></td>
@@ -1859,7 +1885,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</tr>
<tr class="alt">
- <td valign="top"><b><span class="option">cyclicBufferTracker</span></b>
+ <td valign="top"><b><span class="prop">cyclicBufferTracker</span></b>
</td>
<td><a href="../xref/ch/qos/logback/core/spi/CyclicBufferTracker.html"><code>CyclicBufferTracker</code></a>
</td>
@@ -1867,33 +1893,33 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<p>As the name indicates, an instance of the
<code>CyclicBufferTracker</code> class tracks cyclic
buffers. It does so based on the keys returned by the <span
- class="option">discriminator</span> (see above).
+ class="prop">discriminator</span> (see above).
</p>
<p>If you don't specify a <span
- class="option">cyclicBufferTracker</span>, an instance of <a
+ class="prop">cyclicBufferTracker</span>, an instance of <a
href="../xref/ch/qos/logback/core/spi/CyclicBufferTrackerImpl.html">CyclicBufferTrackerImpl</a>
will be automatically created. By default, this instance
will keep events in a cyclic buffer of size 256. You may
change the size with the help of the <span
- class="option">bufferSize</span> option (see below).</p>
+ class="prop">bufferSize</span> option (see below).</p>
</td>
</tr>
<tr>
- <td><b><span class="option">username</span></b></td>
+ <td><b><span class="prop">username</span></b></td>
<td><code>String</code></td> <td>The username value to use
during plain user/password authentication. By default, this
parameter is null. </td>
</tr>
<tr class="alt">
- <td><b><span class="option">password</span></b></td>
+ <td><b><span class="prop">password</span></b></td>
<td><code>String</code></td>
<td>The password value to use for plain user/password
authentication. By default, this parameter is null.
</td>
</tr>
<tr>
- <td><b><span class="option">STARTTLS</span></b> </td>
+ <td><b><span class="prop">STARTTLS</span></b> </td>
<td><code>boolean</code></td>
<td>If this parameter is set to true, then this appender
will issue the STARTTLS command (if the server supports it)
@@ -1903,14 +1929,14 @@ public interface TriggeringPolicy<E> extends LifeCycle {
</td>
</tr>
<tr class="alt">
- <td><b><span class="option">SSL</span></b></td>
+ <td><b><span class="prop">SSL</span></b></td>
<td><code>boolean</code></td> <td>If this parameter is set to
true, then this appender will open an SSL connection to the
server. By default, this parameter is set to false. </td>
</tr>
<tr>
- <td><b><span class="option">charsetEncoding</span></b></td>
+ <td><b><span class="prop">charsetEncoding</span></b></td>
<td><code>String</code></td>
<td>The outgoing email message will be encoded in the
designated <a
@@ -1928,7 +1954,7 @@ public interface TriggeringPolicy<E> extends LifeCycle {
configured, e.g. if the client hostname is not fully
qualified, certain SMTP servers may reject the HELO/EHLO
commands sent by the client. To overcome this issue, you may
- set the value of the <span class="option">localhost</span>
+ set the value of the <span class="prop">localhost</span>
property to the fully qualified name of the client host. See
also the "mail.smtp.localhost" property in the documentation
for the <a
@@ -1994,8 +2020,8 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<p>Before trying out <code>chapters.appenders.mail.Email</code> application
with the above configuration file, you must set the <span
- class="option">smtpHost</span>, <span class="option">to</span> and
- <span class="option">from</span> properties to values appropriate for
+ class="prop">smtpHost</span>, <span class="prop">to</span> and
+ <span class="prop">from</span> properties to values appropriate for
your environment. Once you have set the correct values in the
configuration file, execute the following command:
</p>
@@ -2011,8 +2037,8 @@ public interface TriggeringPolicy<E> extends LifeCycle {
<p><img src="images/chapters/appenders/smtpAppender1.jpg" alt="resulting email"/></p>
<p>In the next example configuration file <em>mail2.xml</em>, the
- values for the <span class="option">smtpHost</span>, <span
- class="option">to</span> and <span class="option">from</span>
+ values for the <span class="prop">smtpHost</span>, <span
+ class="prop">to</span> and <span class="prop">from</span>
properties are determined by variable substitution. Here is the
relevant part of <em>mail2.xml</em>.
</p>
@@ -2161,7 +2187,7 @@ public class CounterBasedEvaluator extends ContextAwareBase implements EventEval
common functionality.
</p>
- <p>Setting the <span class="option">Evaluator</span> option of
+ <p>Setting the <span class="prop">Evaluator</span> option of
<code>SMTPAppender</code> instructs it to use a custom evaluator.
The next configuration file attaches a <code>SMTPAppender</code>
to the root logger. This appender uses a
@@ -2445,16 +2471,16 @@ logger.error(<b>notifyAdmin</b>,
<p>Internally, each distinct value returned by the discriminator
will cause the creation of a new cyclic buffer. However, at most
- <span class="option">maxNumberOfBuffers</span> (by default 64)
+ <span class="prop">maxNumberOfBuffers</span> (by default 64)
will be maintained. Whenever the number of buffers rises above
- <span class="option">maxNumberOfBuffers</span>, the least recently
+ <span class="prop">maxNumberOfBuffers</span>, the least recently
updated buffer is automatically discarded. As a second safety
measure, any buffer which has not been updated in the last 30
minutes will be automatically discarded as well.</p>
<p>On systems serving a large number of transactions per minute,
allowing only a small number for <span
- class="option">maxNumberOfBuffers</span> (by default 64) will
+ class="prop">maxNumberOfBuffers</span> (by default 64) will
often cause the number of events in the outgoing email to be
unnecessarily small. Indeed, in the presence of a large number of
transactions, there will be more than one buffer associated with
@@ -2462,7 +2488,7 @@ logger.error(<b>notifyAdmin</b>,
succession for the same discriminator value (or transaction). Note
that in even such very busy systems, the maximum number of cyclic
buffers is capped by <span
- class="option">maxNumberOfBuffers</span>.
+ class="prop">maxNumberOfBuffers</span>.
</p>
<p>To avoid such yo-yo effects, <code>SMTPAppender</code> will
@@ -2470,7 +2496,7 @@ logger.error(<b>notifyAdmin</b>,
soon as it sees an event marked as "FINALIZE_SESSION". This will
cause the appropriate buffer to be discarded at the end of each
transaction. You can then safely increase the value of <span
- class="option">maxNumberOfBuffers</span> to a larger value such as
+ class="prop">maxNumberOfBuffers</span> to a larger value such as
512 or 1024 without risking running out of memory.
</p>
@@ -2795,7 +2821,7 @@ logger.error(<b>notifyAdmin</b>,
<p>
The correct driver must be declared. Here, the <code>com.mysql.jdbc.Driver</code>
- class is used. The <span class="option">url</span> must begin with <em>jdbc:myslq://</em>.
+ class is used. The <span class="prop">url</span> must begin with <em>jdbc:myslq://</em>.
</p>
<p>
@@ -3060,7 +3086,7 @@ logger.error(<b>notifyAdmin</b>,
<tr class="b">
<td>
<b>
- <span class="option">syslogHost</span>
+ <span class="prop">syslogHost</span>
</b>
</td>
<td>
@@ -3073,7 +3099,7 @@ logger.error(<b>notifyAdmin</b>,
<tr class="a">
<td>
<b>
- <span class="option">port</span>
+ <span class="prop">port</span>
</b>
</td>
<td>
@@ -3087,7 +3113,7 @@ logger.error(<b>notifyAdmin</b>,
<tr class="b">
<td>
<b>
- <span class="option">facility</span>
+ <span class="prop">facility</span>
</b>
</td>
<td>
@@ -3095,11 +3121,11 @@ logger.error(<b>notifyAdmin</b>,
</td>
<td>
<p>
- The <span class="option">facility</span> is meant to identify
+ The <span class="prop">facility</span> is meant to identify
the source of a message.
</p>
<p>
- The <span class="option">facility</span> option must be set to one
+ The <span class="prop">facility</span> option must be set to one
of the strings <em>KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP,
CRON, AUTHPRIV, FTP, NTP, AUDIT, ALERT, CLOCK, LOCAL0, LOCAL1, LOCAL2,
LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7</em>. Case is not important.
@@ -3109,19 +3135,19 @@ logger.error(<b>notifyAdmin</b>,
<tr class="a">
<td>
<b>
- <span class="option">suffixPattern</span>
+ <span class="prop">suffixPattern</span>
</b>
</td>
<td>
<code>String</code>
</td>
<td>
- <p>The <span class="option">suffixPattern</span> option
+ <p>The <span class="prop">suffixPattern</span> option
specifies the format of the non-standardized part of the
message sent to the syslog server. By default, its value is
<em>[%thread] %logger %msg</em>. Any value that a
<code>PatternLayout</code> could use is a correct <span
- class="option">suffixPattern</span> value.
+ class="prop">suffixPattern</span> value.
</p>
</td>
</tr>
@@ -3137,7 +3163,7 @@ logger.error(<b>notifyAdmin</b>,
<p>
Since the format of a syslog request follows rather strict rules, there is no layout
to be used with <code>SyslogAppender</code>. However, using the
- <span class="option">suffixPattern</span> option lets the user display whatever
+ <span class="prop">suffixPattern</span> option lets the user display whatever
information she wishes.
</p>
@@ -3238,9 +3264,9 @@ logger.debug("Alice says hello"); </p>
discriminator type is <a
href="../xref/ch/qos/logback/classic/sift/MDCBasedDiscriminator.html">MDCBasedDiscriminator</a>. It
will use the MDC value associated with the <span
- class="option">Key</span> property as a discriminator. If that
+ class="prop">Key</span> property as a discriminator. If that
value is null, then the value associated with the <span
- class="option">defaultValue</span> property will be used.
+ class="prop">defaultValue</span> property will be used.
</p>
<p>The <code>SiftingAppender</code> is unique in its capacity to
@@ -3403,7 +3429,7 @@ public class CountingConsoleAppender extends AppenderBase<ILoggingEvent> {
<p>
Access' <a href="../xref/ch/qos/logback/access/net/SMTPAppender.html">
<code>SMTPAppender</code></a> works in the same way as its Classic counterpart.
- However, the <span class="option">evaluator</span> option is rather different.
+ However, the <span class="prop">evaluator</span> option is rather different.
By default, a <code>URLEvaluator</code> object
is used by <code>SMTPAppender</code>. This evaluator contains a list of URLs that are
checked against the current request's URL. When one of the pages given to the
@@ -3566,7 +3592,7 @@ public class CountingConsoleAppender extends AppenderBase<ILoggingEvent> {
<tr class="b">
<td>
<b>
- <span class="option">insertHeaders</span>
+ <span class="prop">insertHeaders</span>
</b>
</td>
<td>
@@ -3610,13 +3636,13 @@ public class CountingConsoleAppender extends AppenderBase<ILoggingEvent> {
uses a designated field in AccessEvent as the basis for selecting a
nested appender. If the value of the designated field is null,
then the value specified in the <span
- class="option">defaultValue</span> property is used.
+ class="prop">defaultValue</span> property is used.
</p>
<p>The designated AccessEvent field can be one of COOKIE,
REQUEST_ATTRIBUTE, SESSION_ATTRIBUTE, REMOTE_ADDRESS, LOCAL_PORT,
REQUEST_URI. Note that the first three fields require that the
- <span class="option">AdditionalKey</span> property also be
+ <span class="prop">AdditionalKey</span> property also be
specified.</p>
<p>Below is an example configuration file.</p>
-----------------------------------------------------------------------
Summary of changes:
logback-site/src/site/pages/css/common.css | 2 +-
logback-site/src/site/pages/manual/appenders.html | 308 +++++++++++----------
2 files changed, 168 insertions(+), 142 deletions(-)
hooks/post-receive
--
Logback: the generic, reliable, fast and flexible logging framework.
More information about the logback-dev
mailing list