Author: buildbot
Date: Sun Nov 17 14:45:12 2013
New Revision: 886965
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/development/logging-new.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Sun Nov 17 14:45:12 2013
@@ -1 +1 @@
-1542250
+1542739
Modified:
websites/staging/sling/trunk/content/documentation/development/logging-new.html
==============================================================================
---
websites/staging/sling/trunk/content/documentation/development/logging-new.html
(original)
+++
websites/staging/sling/trunk/content/documentation/development/logging-new.html
Sun Nov 17 14:45:12 2013
@@ -105,6 +105,7 @@ features</p>
<li><a href="http://logging.apache.org/log4j/index.html";>log4j</a></li>
<li><a
href="http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html";>java.util.logging</a></li>
<li>Configures logging through Logback which is integrated with the OSGi
environment</li>
+<li>Logging can be configured both via editing Logback xml or via OSGi
Configurations</li>
</ul>
<h2 id="logback-integration">Logback Integration</h2>
<p>Logback integration provides following features</p>
@@ -121,21 +122,21 @@ features</p>
<h3 id="turbofilters-as-osgi-service">TurboFilters as OSGi Service</h3>
<p><a href="http://logback.qos.ch/manual/filters.html#TurboFilter";>Logback
TurboFilter</a> operate globally and invoked for every Logback call. To
register a <code>TurboFilter</code> as OSGi service
the bundle just need to register a service against
<code>ch.qos.logback.classic.turbo.TurboFilter</code> class</p>
-<div class="codehilite"><pre><span class="n">import</span> <span
class="n">import</span> <span class="n">ch</span><span class="p">.</span><span
class="n">qos</span><span class="p">.</span><span class="n">logback</span><span
class="p">.</span><span class="n">classic</span><span class="p">.</span><span
class="n">turbo</span><span class="p">.</span><span
class="n">MatchingFilter</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">import</span> <span class="n">ch</span><span class="o">.</span><span
class="na">qos</span><span class="o">.</span><span
class="na">logback</span><span class="o">.</span><span
class="na">classic</span><span class="o">.</span><span
class="na">turbo</span><span class="o">.</span><span
class="na">MatchingFilter</span><span class="o">;</span>
-<span class="n">SimpleTurboFilter</span> <span class="n">stf</span> <span
class="p">=</span> <span class="n">new</span> <span
class="n">SimpleTurboFilter</span><span class="p">();</span>
-<span class="n">ServiceRegistration</span> <span class="n">sr</span> <span
class="p">=</span> <span class="n">bundleContext</span><span
class="p">.</span><span class="n">registerService</span><span
class="p">(</span><span class="n">TurboFilter</span><span
class="p">.</span><span class="n">class</span><span class="p">.</span><span
class="n">getName</span><span class="p">(),</span> <span
class="n">stf</span><span class="p">,</span> <span class="n">null</span><span
class="p">);</span>
+<span class="n">SimpleTurboFilter</span> <span class="n">stf</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">SimpleTurboFilter</span><span class="o">();</span>
+<span class="n">ServiceRegistration</span> <span class="n">sr</span> <span
class="o">=</span> <span class="n">bundleContext</span><span
class="o">.</span><span class="na">registerService</span><span
class="o">(</span><span class="n">TurboFilter</span><span
class="o">.</span><span class="na">class</span><span class="o">.</span><span
class="na">getName</span><span class="o">(),</span> <span
class="n">stf</span><span class="o">,</span> <span class="kc">null</span><span
class="o">);</span>
-<span class="n">private</span> <span class="n">static</span> <span
class="n">class</span> <span class="n">SimpleTurboFilter</span> <span
class="n">extends</span> <span class="n">MatchingFilter</span> <span
class="p">{</span>
- <span class="p">@</span><span class="n">Override</span>
- <span class="n">public</span> <span class="n">FilterReply</span> <span
class="n">decide</span><span class="p">(</span><span class="n">Marker</span>
<span class="n">marker</span><span class="p">,</span> <span
class="n">Logger</span> <span class="n">logger</span><span class="p">,</span>
<span class="n">Level</span> <span class="n">level</span><span
class="p">,</span> <span class="n">String</span> <span
class="n">format</span><span class="p">,</span>
- <span class="n">Object</span><span class="p">[]</span> <span
class="n">params</span><span class="p">,</span> <span
class="n">Throwable</span> <span class="n">t</span><span class="p">)</span>
<span class="p">{</span>
- <span class="k">if</span><span class="p">(</span><span
class="n">logger</span><span class="p">.</span><span
class="n">getName</span><span class="p">().</span><span
class="n">equals</span><span class="p">(</span>"<span
class="n">turbofilter</span><span class="p">.</span><span
class="n">foo</span><span class="p">.</span><span
class="n">bar</span>"<span class="p">)){</span>
- <span class="k">return</span> <span
class="n">FilterReply</span><span class="p">.</span><span
class="n">DENY</span><span class="p">;</span>
- <span class="p">}</span>
- <span class="k">return</span> <span class="n">FilterReply</span><span
class="p">.</span><span class="n">NEUTRAL</span><span class="p">;</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<span class="kd">private</span> <span class="kd">static</span> <span
class="kd">class</span> <span class="nc">SimpleTurboFilter</span> <span
class="kd">extends</span> <span class="n">MatchingFilter</span> <span
class="o">{</span>
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">FilterReply</span> <span
class="nf">decide</span><span class="o">(</span><span class="n">Marker</span>
<span class="n">marker</span><span class="o">,</span> <span
class="n">Logger</span> <span class="n">logger</span><span class="o">,</span>
<span class="n">Level</span> <span class="n">level</span><span
class="o">,</span> <span class="n">String</span> <span
class="n">format</span><span class="o">,</span>
+ <span class="n">Object</span><span class="o">[]</span> <span
class="n">params</span><span class="o">,</span> <span
class="n">Throwable</span> <span class="n">t</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="k">if</span><span class="o">(</span><span
class="n">logger</span><span class="o">.</span><span
class="na">getName</span><span class="o">().</span><span
class="na">equals</span><span class="o">(</span><span
class="s">"turbofilter.foo.bar"</span><span class="o">)){</span>
+ <span class="k">return</span> <span
class="n">FilterReply</span><span class="o">.</span><span
class="na">DENY</span><span class="o">;</span>
+ <span class="o">}</span>
+ <span class="k">return</span> <span class="n">FilterReply</span><span
class="o">.</span><span class="na">NEUTRAL</span><span class="o">;</span>
+ <span class="o">}</span>
+<span class="o">}</span>
</pre></div>
@@ -144,23 +145,23 @@ the bundle just need to register a servi
<p><a href="http://logback.qos.ch/manual/filters.html";>Logback Filters</a> are
attached to appenders and are used to determine if any LoggingEvent needs to
be passed to the appender. When registering a filter the bundle needs to
configure a service property
<code>appenders</code> which refers to list of appender names to which the
Filter must be attached</p>
-<div class="codehilite"><pre><span class="n">import</span> <span
class="n">ch</span><span class="p">.</span><span class="n">qos</span><span
class="p">.</span><span class="n">logback</span><span class="p">.</span><span
class="n">core</span><span class="p">.</span><span class="n">filter</span><span
class="p">.</span><span class="n">Filter</span><span class="p">;</span>
+<div class="codehilite"><pre><span class="kn">import</span> <span
class="nn">ch.qos.logback.core.filter.Filter</span><span class="o">;</span>
-<span class="n">SimpleFilter</span> <span class="n">stf</span> <span
class="p">=</span> <span class="n">new</span> <span
class="n">SimpleFilter</span><span class="p">();</span>
-<span class="n">Dictionary</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">Object</span><span class="o">></span> <span class="n">props</span>
<span class="p">=</span> <span class="n">new</span> <span
class="n">Hashtable</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">Object</span><span class="o">></span><span class="p">();</span>
-<span class="n">props</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span>"<span
class="n">appenders</span>"<span class="p">,</span> "<span
class="n">TestAppender</span>"<span class="p">);</span>
-<span class="n">ServiceRegistration</span> <span class="n">sr</span> <span
class="p">=</span> <span class="n">bundleContext</span><span
class="p">.</span><span class="n">registerService</span><span
class="p">(</span><span class="n">Filter</span><span class="p">.</span><span
class="n">class</span><span class="p">.</span><span
class="n">getName</span><span class="p">(),</span> <span
class="n">stf</span><span class="p">,</span> <span class="n">props</span><span
class="p">);</span>
-
-<span class="n">private</span> <span class="n">static</span> <span
class="n">class</span> <span class="n">SimpleFilter</span> <span
class="n">extends</span> <span class="n">Filter</span><span
class="o"><</span><span class="n">ILoggingEvent</span><span
class="o">></span> <span class="p">{</span>
-
- <span class="p">@</span><span class="n">Override</span>
- <span class="n">public</span> <span class="n">FilterReply</span> <span
class="n">decide</span><span class="p">(</span><span
class="n">ILoggingEvent</span> <span class="n">event</span><span
class="p">)</span> <span class="p">{</span>
- <span class="k">if</span><span class="p">(</span><span
class="n">event</span><span class="p">.</span><span
class="n">getLoggerName</span><span class="p">().</span><span
class="n">equals</span><span class="p">(</span>"<span
class="n">filter</span><span class="p">.</span><span class="n">foo</span><span
class="p">.</span><span class="n">bar</span>"<span class="p">)){</span>
- <span class="k">return</span> <span
class="n">FilterReply</span><span class="p">.</span><span
class="n">DENY</span><span class="p">;</span>
- <span class="p">}</span>
- <span class="k">return</span> <span class="n">FilterReply</span><span
class="p">.</span><span class="n">NEUTRAL</span><span class="p">;</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<span class="n">SimpleFilter</span> <span class="n">stf</span> <span
class="o">=</span> <span class="k">new</span> <span
class="n">SimpleFilter</span><span class="o">();</span>
+<span class="n">Dictionary</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span
class="n">Object</span><span class="o">></span> <span class="n">props</span>
<span class="o">=</span> <span class="k">new</span> <span
class="n">Hashtable</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span
class="n">Object</span><span class="o">>();</span>
+<span class="n">props</span><span class="o">.</span><span
class="na">put</span><span class="o">(</span><span
class="s">"appenders"</span><span class="o">,</span> <span
class="s">"TestAppender"</span><span class="o">);</span>
+<span class="n">ServiceRegistration</span> <span class="n">sr</span> <span
class="o">=</span> <span class="n">bundleContext</span><span
class="o">.</span><span class="na">registerService</span><span
class="o">(</span><span class="n">Filter</span><span class="o">.</span><span
class="na">class</span><span class="o">.</span><span
class="na">getName</span><span class="o">(),</span> <span
class="n">stf</span><span class="o">,</span> <span class="n">props</span><span
class="o">);</span>
+
+<span class="kd">private</span> <span class="kd">static</span> <span
class="kd">class</span> <span class="nc">SimpleFilter</span> <span
class="kd">extends</span> <span class="n">Filter</span><span
class="o"><</span><span class="n">ILoggingEvent</span><span
class="o">></span> <span class="o">{</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">public</span> <span class="n">FilterReply</span> <span
class="nf">decide</span><span class="o">(</span><span
class="n">ILoggingEvent</span> <span class="n">event</span><span
class="o">)</span> <span class="o">{</span>
+ <span class="k">if</span><span class="o">(</span><span
class="n">event</span><span class="o">.</span><span
class="na">getLoggerName</span><span class="o">().</span><span
class="na">equals</span><span class="o">(</span><span
class="s">"filter.foo.bar"</span><span class="o">)){</span>
+ <span class="k">return</span> <span
class="n">FilterReply</span><span class="o">.</span><span
class="na">DENY</span><span class="o">;</span>
+ <span class="o">}</span>
+ <span class="k">return</span> <span class="n">FilterReply</span><span
class="o">.</span><span class="na">NEUTRAL</span><span class="o">;</span>
+ <span class="o">}</span>
+<span class="o">}</span>
</pre></div>
@@ -169,15 +170,15 @@ be passed to the appender. When register
the bundle just need to register a service against
<code>ch.qos.logback.core.Appender</code> class. When registering an
appender the bundle needs to configure a service property <code>loggers</code>
which refers to list of logger names to which
the Appender must be attached</p>
-<div class="codehilite"><pre><span class="n">Dictionary</span><span
class="o"><</span><span class="n">String</span><span class="p">,</span><span
class="n">Object</span><span class="o">></span> <span class="n">props</span>
<span class="p">=</span> <span class="n">new</span> <span
class="n">Hashtable</span><span class="o"><</span><span
class="n">String</span><span class="p">,</span> <span
class="n">Object</span><span class="o">></span><span class="p">();</span>
+<div class="codehilite"><pre><span class="n">Dictionary</span><span
class="o"><</span><span class="n">String</span><span class="o">,</span><span
class="n">Object</span><span class="o">></span> <span class="n">props</span>
<span class="o">=</span> <span class="k">new</span> <span
class="n">Hashtable</span><span class="o"><</span><span
class="n">String</span><span class="o">,</span> <span
class="n">Object</span><span class="o">>();</span>
-<span class="n">String</span><span class="p">[]</span> <span
class="n">loggers</span> <span class="p">=</span> <span class="p">{</span>
- "<span class="n">foo</span><span class="p">.</span><span
class="n">bar</span><span class="p">:</span><span
class="n">DEBUG</span>"<span class="p">,</span>
- "<span class="n">foo</span><span class="p">.</span><span
class="n">bar</span><span class="p">.</span><span class="n">zoo</span><span
class="p">:</span><span class="n">INFO</span>"<span class="p">,</span>
-<span class="p">};</span>
+<span class="n">String</span><span class="o">[]</span> <span
class="n">loggers</span> <span class="o">=</span> <span class="o">{</span>
+ <span class="s">"foo.bar:DEBUG"</span><span
class="o">,</span>
+ <span class="s">"foo.bar.zoo:INFO"</span><span
class="o">,</span>
+<span class="o">};</span>
-<span class="n">props</span><span class="p">.</span><span
class="n">put</span><span class="p">(</span>"<span
class="n">loggers</span>"<span class="p">,</span><span
class="n">loggers</span><span class="p">);</span>
-<span class="n">sr</span> <span class="p">=</span> <span
class="n">bundleContext</span><span class="p">.</span><span
class="n">registerService</span><span class="p">(</span><span
class="n">Appender</span><span class="p">.</span><span
class="n">class</span><span class="p">.</span><span
class="n">getName</span><span class="p">(),</span><span
class="n">this</span><span class="p">,</span><span class="n">props</span><span
class="p">);</span>
+<span class="n">props</span><span class="o">.</span><span
class="na">put</span><span class="o">(</span><span
class="s">"loggers"</span><span class="o">,</span><span
class="n">loggers</span><span class="o">);</span>
+<span class="n">sr</span> <span class="o">=</span> <span
class="n">bundleContext</span><span class="o">.</span><span
class="na">registerService</span><span class="o">(</span><span
class="n">Appender</span><span class="o">.</span><span
class="na">class</span><span class="o">.</span><span
class="na">getName</span><span class="o">(),</span><span
class="k">this</span><span class="o">,</span><span class="n">props</span><span
class="o">);</span>
</pre></div>
@@ -221,7 +222,7 @@ registration = context.registerService(S
</pre></div>
-<p>If the config changes then sending an event to
<code>org/apache/sling/commons/log/RESET</code> would reset the listener</p>
+<p>If the config changes then sending an event to
<code>org/apache/sling/commons/log/RESET</code> would reset the Logback
runtime</p>
<div class="codehilite"><pre><span class="n">eventAdmin</span><span
class="p">.</span><span class="n">sendEvent</span><span class="p">(</span><span
class="n">new</span> <span class="n">Event</span><span
class="p">(</span>"<span class="n">org</span><span class="o">/</span><span
class="n">apache</span><span class="o">/</span><span
class="n">sling</span><span class="o">/</span><span
class="n">commons</span><span class="o">/</span><span
class="nb">log</span><span class="o">/</span><span
class="n">RESET</span>"<span class="p">,</span><span class="n">new</span>
<span class="n">Properties</span><span class="p">()));</span>
</pre></div>
@@ -236,11 +237,11 @@ registration = context.registerService(S
</ol>
<p>If you are providing an external config file then to support OSGi
integration you would need to add following
action entry</p>
-<div class="codehilite"><pre><span class="o"><</span><span
class="n">newRule</span> <span class="n">pattern</span><span
class="p">=</span>"<span class="o">*/</span><span
class="n">configuration</span><span class="o">/</span><span
class="n">osgi</span>"
- <span class="n">actionClass</span><span class="p">=</span>"<span
class="n">org</span><span class="p">.</span><span class="n">apache</span><span
class="p">.</span><span class="n">sling</span><span class="p">.</span><span
class="n">commons</span><span class="p">.</span><span
class="nb">log</span><span class="p">.</span><span
class="n">logback</span><span class="p">.</span><span
class="n">OsgiAction</span>"<span class="o">/></span>
-<span class="o"><</span><span class="n">newRule</span> <span
class="n">pattern</span><span class="p">=</span>"<span
class="o">*/</span><span class="n">configuration</span><span
class="o">/</span><span class="n">appender</span><span class="o">-</span><span
class="n">ref</span><span class="o">-</span><span class="n">osgi</span>"
- <span class="n">actionClass</span><span class="p">=</span>"<span
class="n">org</span><span class="p">.</span><span class="n">apache</span><span
class="p">.</span><span class="n">sling</span><span class="p">.</span><span
class="n">commons</span><span class="p">.</span><span
class="nb">log</span><span class="p">.</span><span
class="n">logback</span><span class="p">.</span><span
class="n">OsgiAppenderRefAction</span>"<span class="o">/></span>
-<span class="o"><</span><span class="n">osgi</span><span
class="o">/></span>
+<div class="codehilite"><pre><span class="nt"><newRule</span> <span
class="na">pattern=</span><span
class="s">"*/configuration/osgi"</span>
+ <span class="na">actionClass=</span><span
class="s">"org.apache.sling.commons.log.logback.OsgiAction"</span><span
class="nt">/></span>
+<span class="nt"><newRule</span> <span class="na">pattern=</span><span
class="s">"*/configuration/appender-ref-osgi"</span>
+ <span class="na">actionClass=</span><span
class="s">"org.apache.sling.commons.log.logback.OsgiAppenderRefAction"</span><span
class="nt">/></span>
+<span class="nt"><osgi/></span>
</pre></div>
@@ -252,16 +253,14 @@ needs to be done. This features allows r
<li>Set framework property
<code>org.apache.sling.commons.log.julenabled</code> to true</li>
<li>
<p>Set the <a
href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator";>LevelChangePropagator</a>
in LogbackConfig</p>
-<div class="codehilite"><pre><span class="nt"><configuration></span>
- <span class="nt"><contextListener</span> <span
class="na">class=</span><span
class="s">"ch.qos.logback.classic.jul.LevelChangePropagator"</span><span
class="nt">/></span>
- ...
-<span class="nt"></configuration></span>
-</pre></div>
-
-
+<p>:::xml
+<configuration>
+ <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
+ ...
+</configuration></p>
</li>
</ol>
-<h3 id="configuring-osgi-based-appenders-in-logback-config">Configuring OSGi
based appenders in Logback Config</h3>
+<h3
id="wzxhzdk11wzxhzdk12configuring-osgi-based-appenders-in-logback-config"><a
name="config-override"></a>Configuring OSGi based appenders in Logback
Config</h3>
<p>So far Sling used to configure the appenders based on OSGi config. That
mode only provide a very limited
set to configuration options. To make use of other Logback features you can
override the OSGi config
from within the Logback config file. OSGi config based appenders are named
based on the file name</p>
@@ -276,13 +275,13 @@ from within the Logback config file. OSG
<p>The Logback appender would be named as <code>logs/error.log</code>. To
extend/override the config in Logback config
create an appender with name <code>logs/error.log</code></p>
-<div class="codehilite"><pre><span class="o"><</span><span
class="s-Atom">appender</span> <span class="s-Atom">name=</span><span
class="s2">"/logs/error.log"</span> <span
class="s-Atom">class=</span><span
class="s2">"ch.qos.logback.core.FileAppender"</span><span
class="o">></span>
- <span class="o"><</span><span class="s-Atom">file></span><span
class="err">$</span><span class="p">{</span><span
class="s-Atom">sling</span><span class="p">.</span><span
class="s-Atom">home</span><span class="p">}</span><span class="o">/</span><span
class="s-Atom">logs</span><span class="o">/</span><span
class="s-Atom">error</span><span class="p">.</span><span
class="s-Atom">log</file</span><span class="o">></span>
- <span class="o"><</span><span class="s-Atom">encoder</span><span
class="o">></span>
- <span class="o"><</span><span class="s-Atom">pattern></span><span
class="c1">%d %-5level %X{sling.userId:-NA} [%thread] %logger{30} %marker- %msg
%n</pattern></span>
- <span class="o"><</span><span class="s-Atom">immediateFlush</span><span
class="o">></span><span class="s-Atom">true</immediateFlush</span><span
class="o">></span>
- <span class="s-Atom"></encoder</span><span class="o">></span>
-<span class="s-Atom"></appender</span><span class="o">></span>
+<div class="codehilite"><pre><span class="nt"><appender</span> <span
class="na">name=</span><span class="s">"/logs/error.log"</span> <span
class="na">class=</span><span
class="s">"ch.qos.logback.core.FileAppender"</span><span
class="nt">></span>
+ <span class="nt"><file></span>${sling.home}/logs/error.log<span
class="nt"></file></span>
+ <span class="nt"><encoder></span>
+ <span class="nt"><pattern></span>%d %-5level %X{sling.userId:-NA}
[%thread] %logger{30} %marker- %msg %n<span class="nt"></pattern></span>
+ <span class="nt"><immediateFlush></span>true<span
class="nt"></immediateFlush></span>
+ <span class="nt"></encoder></span>
+<span class="nt"></appender></span>
</pre></div>
@@ -336,6 +335,154 @@ be used to move the application from OSG
</tr>
</tbody>
</table>
+<h2 id="user-configuration-osgi-based">User Configuration - OSGi Based</h2>
+<p>User Configuration after initial configuration is provided by the
Configuration Admin Service. To this avail two
+<code>org.osgi.services.cm.ManagedServiceFactory</code> services are
registered under the PIDs
<code>org.apache.sling.commons.log.LogManager.factory.writer</code>
+and <code>org.apache.sling.commons.log.LogManager.factory.config</code> which
may receive configuration.</p>
+<h3 id="logger-configuration">Logger Configuration</h3>
+<p>Loggers (or Categories) can be configured to log to specific files at
specific levels using configurable patterns.
+To this avail factory configuration instances with factory PID
<code>org.apache.sling.commons.log.LogManager.factory.config</code>
+may be created and configured with the Configuration Admin Service.</p>
+<p>The following properties may be set:</p>
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Type</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.apache.sling.commons.log.level</code></td>
+<td><code>String</code></td>
+<td><code>INFO</code></td>
+<td>Sets the logging level of the loggers. This may be any of the defined
logging levels <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>,
<code>ERROR</code> and <code>FATAL</code>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file</code></td>
+<td><code>String</code></td>
+<td>undefined</td>
+<td>Sets the log file to which log messages are written. If this property is
empty or missing, log messages are written to <code>System.out</code>. This
property should refer to the file name of a configured Log Writer (see below).
If no Log Writer is configured with the same file name an implicit Log Writer
configuration with default configuration is created.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.pattern</code></td>
+<td><code>String</code></td>
+<td>{0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}]() {3} {5}</td>
+<td>The <code>java.util.MessageFormat</code> pattern to use for formatting log
messages with the root logger. This is a <code>java.util.MessageFormat</code>
pattern supporting up to six arguments: {0} The timestamp of type
<code>java.util.Date</code>, {1} the log marker, {2} the name of the current
thread, {3} the name of the logger, {4} the debug level and {5} the actual
debug message. If the log call includes a Throwable, the stacktrace is just
appended to the message regardless of the pattern.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.names</code></td>
+<td><code>String\[\]</code></td>
+<td>--</td>
+<td>A list of logger names to which this configuration applies.</td>
+</tr>
+</tbody>
+</table>
+<p>Note that multiple Logger Configurations may refer to the same Log Writer
Configuration. If no Log Writer Configuration
+exists whose file name matches the file name set on the Logger Configuration
an implicit Log Writer Configuration
+with default setup (daily log rotation) is internally created.</p>
+<h3 id="log-writer-configuration">Log Writer Configuration</h3>
+<p>Log Writer Configuration is used to setup file output and log file rotation
characteristics for log writers used by the Loggers.</p>
+<p>The following properties may be set:</p>
+<table>
+<thead>
+<tr>
+<th>Property</th>
+<th>Default</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>org.apache.sling.commons.log.file</code></td>
+<td>undefined</td>
+<td>Sets the log file to which log messages are written. If this property is
empty or missing, log messages are written to <code>System.out</code>.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file.number</code></td>
+<td>5</td>
+<td>The number of rotated files to keep.</td>
+</tr>
+<tr>
+<td><code>org.apache.sling.commons.log.file.size</code></td>
+<td>'.'yyyy-MM-dd</td>
+<td>Defines how the log file is rotated (by schedule or by size) and when to
rotate. See the section <em>Log File Rotation</em> below for full details on
log file rotation.</td>
+</tr>
+</tbody>
+</table>
+<p>See the section <em>Log File Rotation</em> below for full details on the
<code>org.apache.sling.commons.log.file.size</code> and
+<code>org.apache.sling.commons.log.file.number</code> properties.</p>
+<h4 id="log-file-rotation">Log File Rotation</h4>
+<p>Log files can grow rather quickly and fill up available disk space. To cope
with this growth log files may be rotated in
+two ways: At specific times or when the log file reaches a configurable size.
The first method is called <em>Scheduled Rotation</em>
+and is used by specifying a <code>SimpleDateFormat</code> pattern as the log
file "size". The second method is called <em>Size Rotation</em>
+and is used by setting a maximum file size as the log file size.</p>
+<p>As of version 2.0.6 of the Sling Commons Log bundle, the default value for
log file scheduling is <code>'.'yyyy-MM-dd</code>
+causing daily log rotation. Previously log rotation defaulted to a 10MB file
size limit.</p>
+<h5 id="scheduled-rotation">Scheduled Rotation</h5>
+<p>The rolling schedule is specified by setting the
<code>org.apache.sling.commons.log.file.size</code> property to a
+<code>java.text.SimpleDateFormat</code> pattern. Literal text (such as a
leading dot) to be included must be <em>enclosed</em> within a
+pair of single quotes. A formatted version of the date pattern is used as the
suffix for the rolled file name. Internally
+the Log bundle configures a <code>TimeBasedRollingPolicy</code> for the
appender. Refer to <a
href="http://logback.qos.ch/manual/appenders.html#TimeBasedRollingPolicy";>TimeBasedRollingPolicy</a>
for
+more details around the pattern format</p>
+<p>For example, if the log file is configured as <code>/foo/bar.log</code> and
the pattern set to <code>'.'yyyy-MM-dd</code>, on
+2001-02-16 at midnight, the logging file <code>/foo/bar.log</code> will be
renamed to <code>/foo/bar.log.2001-02-16</code> and logging for
+2001-02-17 will continue in a new <code>/foo/bar.log</code> file until it
rolls over the next day.</p>
+<p>It is possible to specify monthly, weekly, half-daily, daily, hourly, or
minutely rollover schedules.</p>
+<table>
+<thead>
+<tr>
+<th>DatePattern</th>
+<th>Rollover schedule</th>
+<th>Example</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>'.'yyyy-MM</code></td>
+<td>Rollover at the beginning of each month</td>
+<td>At midnight of May 31st, 2002 <code>/foo/bar.log</code> will be copied to
<code>/foo/bar.log.2002-05</code>. Logging for the month of June will be output
to <code>/foo/bar.log</code> until it is also rolled over the next month.</td>
+</tr>
+<tr>
+<td><code>'.'yyyy-ww</code></td>
+<td>Rollover at the first day of each week. The first day of the week depends
on the locale.</td>
+<td>Assuming the first day of the week is Sunday, on Saturday midnight, June
9th 2002, the file <code>/foo/bar.log</code> will be copied to
<code>/foo/bar.log.2002-23</code>. Logging for the 24th week of 2002 will be
output to <code>/foo/bar.log</code> until it is rolled over the next week.</td>
+</tr>
+<tr>
+<td><code>'.'yyyy-MM-dd</code></td>
+<td>Rollover at midnight each day.</td>
+<td>At midnight, on March 8th, 2002, <code>/foo/bar.log</code> will be copied
to <code>/foo/bar.log.2002-03-08</code>. Logging for the 9th day of March will
be output to <code>/foo/bar.log</code> until it is rolled over the next
day.</td>
+</tr>
+<tr>
+<td><code>'.'yyyy-MM-dd-a</code></td>
+<td>Rollover at midnight and midday of each day.</td>
+<td>at noon, on March 9th, 2002, <code>/foo/bar.log</code> will be copied to
<code>/foo/bar.log.2002-03-09-AM</code>. Logging for the afternoon of the 9th
will be output to <code>/foo/bar.log</code> until it is rolled over at
midnight.</td>
+</tr>
+<tr>
+<td><code>'.'yyyy-MM-dd-HH</code></td>
+<td>Rollover at the top of every hour.</td>
+<td>At approximately 11:00.000 o'clock on March 9th, 2002,
<code>/foo/bar.log</code> will be copied to
<code>/foo/bar.log.2002-03-09-10</code>. Logging for the 11th hour of the 9th
of March will be output to <code>/foo/bar.log</code> until it is rolled over at
the beginning of the next hour.</td>
+</tr>
+<tr>
+<td><code>'.'yyyy-MM-dd-HH-mm</code></td>
+<td>Rollover at the beginning of every minute.</td>
+<td>At approximately 11:23,000, on March 9th, 2001, <code>/foo/bar.log</code>
will be copied to <code>/foo/bar.log.2001-03-09-10-22</code>. Logging for the
minute of 11:23 (9th of March) will be output to <code>/foo/bar.log</code>
until it is rolled over the next minute.</td>
+</tr>
+</tbody>
+</table>
+<p>Do not use the colon ":" character in anywhere in the pattern option. The
text before the colon is interpreted as the
+protocol specification of a URL which is probably not what you want.</p>
+<p>Note that Scheduled Rotation ignores the
<code>org.apache.sling.commons.log.file.number</code> property since the old
log files are
+not numbered but "dated".</p>
+<h5 id="size-rotation">Size Rotation</h5>
+<p>Log file rotation by size is specified by setting the
<code>org.apache.sling.commons.log.file.size</code> property to a plain number
+or a number plus a size multiplier. The size multiplier may be any of
<code>K</code>, <code>KB</code>, <code>M</code>, <code>MB</code>,
<code>G</code>, or <code>GB</code> where the case
+is ignored and the meaning is probably obvious.</p>
+<p>When using Size Rotation, the
<code>org.apache.sling.commons.log.file.number</code> defines the number of old
log file generations
+to keep. For example to keep 5 old log files indexed by 0 through 4, set the
<code>org.apache.sling.commons.log.file.number</code>
+to <code>5</code> (which happens to be the default).</p>
<h2 id="webconsole-plugin-enhancements">WebConsole Plugin enhancements</h2>
<p>The web Console Plugin supports following features</p>
<ul>
@@ -347,7 +494,7 @@ be used to move the application from OSG
</ul>
<p><img src="sling-log-support.png" /></p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1542230 by chetanm on Fri, 15 Nov 2013 11:09:02 +0000
+ Rev. 1542739 by chetanm on Sun, 17 Nov 2013 14:43:57 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
