Author: buildbot
Date: Tue Nov 19 16:58:13 2013
New Revision: 887248
Log:
Staging update by buildbot for sling
Modified:
websites/staging/sling/trunk/content/ (props changed)
websites/staging/sling/trunk/content/documentation/development/logging.html
Propchange: websites/staging/sling/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Nov 19 16:58:13 2013
@@ -1 +1 @@
-1543480
+1543495
Modified:
websites/staging/sling/trunk/content/documentation/development/logging.html
==============================================================================
--- websites/staging/sling/trunk/content/documentation/development/logging.html
(original)
+++ websites/staging/sling/trunk/content/documentation/development/logging.html
Tue Nov 19 16:58:13 2013
@@ -86,9 +86,8 @@
<h1>Logging</h1>
<div class="note">
-This document is for new 4.x release of Sling Commons Log components. Refer to
-<a href="http://sling.apache.org/documentation/legacy/logging.html";>Logging
3.x</a> for documentation related
-to older version.
+This document is for the new (November 2013) 4.x release of the Sling Commons
Log components. Refer to
+<a href="http://sling.apache.org/documentation/legacy/logging.html";>Logging
3.x</a> for older versions.
</div>
<div class="toc">
@@ -108,17 +107,17 @@ to older version.
</ul>
</li>
<li><a href="#logback-integration">Logback Integration</a><ul>
-<li><a href="#turbofilters-as-osgi-service">TurboFilters as OSGi
Service</a></li>
-<li><a href="#filter-as-osgi-service">Filter as OSGi service</a></li>
-<li><a href="#appenders-as-osgi-service">Appenders as OSGi service</a></li>
+<li><a href="#turbofilters-as-osgi-services">TurboFilters as OSGi
Services</a></li>
+<li><a href="#filters-as-osgi-services">Filters as OSGi services</a></li>
+<li><a href="#appenders-as-osgi-services">Appenders as OSGi services</a></li>
<li><a href="#logback-config-fragment-support">Logback Config Fragment
Support</a><ul>
-<li><a href="#exposing-fragment-as-string-objects">Exposing fragment as String
objects</a></li>
-<li><a href="#exposing-fragment-as-configprovider-instance">Exposing fragment
as ConfigProvider instance</a></li>
+<li><a href="#logback-config-fragments-as-string-objects">Logback config
fragments as String objects</a></li>
+<li><a href="#logback-config-fragments-as-configprovider-instances">Logback
config fragments as ConfigProvider instances</a></li>
</ul>
</li>
<li><a href="#external-config-file">External Config File</a></li>
<li><a href="#java-util-logging-jul-integration">Java Util Logging (JUL)
Integration</a></li>
-<li><a
href="#wzxhzdk13wzxhzdk14configuring-osgi-based-appenders-in-logback-config"><a
name="config-override"></a>Configuring OSGi based appenders in Logback
Config</a></li>
+<li><a
href="#wzxhzdk13wzxhzdk14configuring-osgi-appenders-in-the-logback-config"><a
name="config-override"></a>Configuring OSGi appenders in the Logback
Config</a></li>
</ul>
</li>
<li><a href="#using-slf4j-api-17">Using Slf4j API 1.7</a></li>
@@ -127,8 +126,8 @@ to older version.
</div>
<h2 id="introduction">Introduction</h2>
<p>Logging in Sling is supported by the
<code>org.apache.sling.commons.log</code> bundle, which is one of the first
bundles installed
-and started by the Sling Launcher. This bundle along with other bundles manage
the Sling Logging and provide following
-features</p>
+and started by the Sling Launcher. This bundle along with other bundles
manages the Sling Logging and provides the
+following features:</p>
<ul>
<li>Implements the OSGi Log Service Specification and registers the
<code>LogService</code> and <code>LogReader</code> services</li>
<li>Exports three commonly used logging APIs:</li>
@@ -137,10 +136,10 @@ 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>
+<li>Allows logging to be configured both via editing Logback xml or via OSGi
Configurations</li>
</ul>
<h2 id="initial-configuration">Initial Configuration</h2>
-<p>The <code>org.apache.sling.commons.log</code> bundle gets the initial
configuration from the following <code>BundleContext</code> properties:</p>
+<p>The <code>org.apache.sling.commons.log</code> bundle gets its initial
configuration from the following <code>BundleContext</code> properties:</p>
<table>
<thead>
<tr>
@@ -190,7 +189,7 @@ features</p>
<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>
+and <code>org.apache.sling.commons.log.LogManager.factory.config</code> to
receive configurations.</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>
@@ -272,7 +271,7 @@ two ways: At specific times or when the
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>
+causing daily log rotation. In previous version, log rotation defaults 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
@@ -341,15 +340,14 @@ to <code>5</code> (which happens to be t
<li>LogBack configuration can be provided via Logback config xml</li>
<li>Supports Appenders registered as OSGi Services</li>
<li>Supports Filters and TurboFilters registered as OSGi Services</li>
-<li>Support providing Logback config as fragments through OSGi Service
Registry</li>
-<li>Support for referring to Appenders registered as OSGi services from with
Logback
- config</li>
-<li>Exposing Logback runtime state through Felix WebConsole Plugin</li>
+<li>Support providing Logback configuration as fragments through OSGi Service
Registry</li>
+<li>Support for referring to Appenders registered as OSGi services from with
Logback config</li>
+<li>Exposes Logback runtime state through the Felix WebConsole Plugin</li>
</ul>
-<p>Following sections would provide more details around these 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>
+<p>The following sections provide more details.</p>
+<h3 id="turbofilters-as-osgi-services">TurboFilters as OSGi Services</h3>
+<p><a href="http://logback.qos.ch/manual/filters.html#TurboFilter";>Logback
TurboFilters</a> operate globally and are invoked for every Logback call. To
register an OSGi <code>TurboFilter</code>,
+just to register an service that implements the
<code>ch.qos.logback.classic.turbo.TurboFilter</code> interface.</p>
<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="o">=</span> <span class="k">new</span> <span
class="n">SimpleTurboFilter</span><span class="o">();</span>
@@ -368,8 +366,8 @@ the bundle just need to register a servi
</pre></div>
-<p>As these filters are invoked for every call they must not take much time to
execute.</p>
-<h3 id="filter-as-osgi-service">Filter as OSGi service</h3>
+<p>As these filters are invoked for every call they must execute quickly.</p>
+<h3 id="filters-as-osgi-services">Filters as OSGi services</h3>
<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>
@@ -393,11 +391,10 @@ be passed to the appender. When register
</pre></div>
-<h3 id="appenders-as-osgi-service">Appenders as OSGi service</h3>
-<p><a href="http://logback.qos.ch/manual/appenders.html";>Logback Appenders</a>
handle the logging events produced by Logback. To register an
<code>Appender</code> as OSGi service
-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>
+<h3 id="appenders-as-osgi-services">Appenders as OSGi services</h3>
+<p><a href="http://logback.qos.ch/manual/appenders.html";>Logback Appenders</a>
handle the logging events produced by Logback. To register an OSGi
<code>Appender</code>,
+just register a service that implements the
<code>ch.qos.logback.core.Appender</code> interface. Such a service must
+have a <code>loggers</code> service property, 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="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="o">[]</span> <span
class="n">loggers</span> <span class="o">=</span> <span class="o">{</span>
@@ -412,10 +409,11 @@ the Appender must be attached</p>
<h3 id="logback-config-fragment-support">Logback Config Fragment Support</h3>
<p>Logback supports including parts of a configuration file from another file
(See <a
href="http://logback.qos.ch/manual/configuration.html#fileInclusion";>File
Inclusion</a>). This module
-extends that support by allowing other bundles to provide config fragments.
There are two ways to achieve that</p>
-<h4 id="exposing-fragment-as-string-objects">Exposing fragment as String
objects</h4>
+extends that support by allowing other bundles to provide config fragments.
There are two ways to achieve that,
+described below.</p>
+<h4 id="logback-config-fragments-as-string-objects">Logback config fragments
as String objects</h4>
<p>If you have the config as string then you can register that String instance
as a service with property <code>logbackConfig</code>
-set to true. Sling Logback Extension would monitor such objects and pass them
to logback</p>
+set to true. The Sling Logback Extension monitors such objects and passes them
to logback.</p>
<div class="codehilite"><pre><span class="n">Properties</span> <span
class="n">props</span> <span class="o">=</span> <span class="k">new</span>
<span class="n">Properties</span><span class="o">();</span>
<span class="n">props</span><span class="o">.</span><span
class="na">setProperty</span><span class="o">(</span><span
class="s">"logbackConfig"</span><span class="o">,</span><span
class="s">"true"</span><span class="o">);</span>
@@ -437,9 +435,10 @@ set to true. Sling Logback Extension wou
</pre></div>
-<p>If the config needs to be updated just re-register the service and change
would be picked up</p>
-<h4 id="exposing-fragment-as-configprovider-instance">Exposing fragment as
ConfigProvider instance</h4>
-<p>Another way to provide config fragment is by providing an implementation of
<code>org.apache.sling.commons.log.logback.ConfigProvider</code></p>
+<p>If the config needs to be updated just re-register the service so that
changes are picked up.</p>
+<h4 id="logback-config-fragments-as-configprovider-instances">Logback config
fragments as ConfigProvider instances</h4>
+<p>Another way to provide config fragments is with services that implement the
+<code>org.apache.sling.commons.log.logback.ConfigProvider</code> interface.</p>
<div class="codehilite"><pre><span class="nd">@Component</span>
<span class="nd">@Service</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">ConfigProviderExample</span> <span class="kd">implements</span>
<span class="n">ConfigProvider</span> <span class="o">{</span>
@@ -450,7 +449,8 @@ set to true. Sling Logback Extension wou
</pre></div>
-<p>If the config changes then sending an event to
<code>org/apache/sling/commons/log/RESET</code> would reset the Logback
runtime</p>
+<p>If the config changes then sending an OSGi event with the
<code>org/apache/sling/commons/log/RESET</code> topic
+resets the Logback runtime.</p>
<div class="codehilite"><pre><span class="n">eventAdmin</span><span
class="o">.</span><span class="na">sendEvent</span><span
class="o">(</span><span class="k">new</span> <span class="n">Event</span><span
class="o">(</span><span
class="s">"org/apache/sling/commons/log/RESET"</span><span
class="o">,</span><span class="k">new</span> <span
class="n">Properties</span><span class="o">()));</span>
</pre></div>
@@ -458,13 +458,11 @@ set to true. Sling Logback Extension wou
<h3 id="external-config-file">External Config File</h3>
<p>Logback can be configured with an external file. The file name can be
specified through</p>
<ol>
-<li>OSGi config - Look for config with name <code>Apache Sling Logging
Configuration</code> and specify the path for
- config file property</li>
-<li>OSGi Framework Properties - Logback supports also looks for file name with
property name
- <code>org.apache.sling.commons.log.configurationFile</code></li>
+<li>OSGi config - Look for a config with name <code>Apache Sling Logging
Configuration</code> and specify the config file path.</li>
+<li>OSGi Framework Properties - Logback support also looks for a file named
according to the OSGi framwork
<code>org.apache.sling.commons.log.configurationFile</code> property.</li>
</ol>
-<p>If you are providing an external config file then to support OSGi
integration you would need to add following
-action entry</p>
+<p>If you are providing an external config file then to support OSGi
integration you need to add following
+action entry:</p>
<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>
@@ -475,12 +473,12 @@ action entry</p>
<p>The <code>osgi</code> element enables the OSGi integration support</p>
<h3 id="java-util-logging-jul-integration">Java Util Logging (JUL)
Integration</h3>
-<p>The bundle also support <a
href="http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html";>SLF4JBridgeHandler</a>.
To enable JUL integration following two steps
-needs to be done. This features allows routing logging messages from JUL to
the Logbback appenders</p>
+<p>The bundle also support <a
href="http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html";>SLF4JBridgeHandler</a>.
The two steps listed below enable the JUL integration.
+This allows for routing logging messages from JUL to the Logbback
appenders.</p>
<ol>
-<li>Set framework property
<code>org.apache.sling.commons.log.julenabled</code> to true</li>
+<li>Set the <code>org.apache.sling.commons.log.julenabled</code> framework
property to true.</li>
<li>
-<p>Set the <a
href="http://logback.qos.ch/manual/configuration.html#LevelChangePropagator";>LevelChangePropagator</a>
in LogbackConfig</p>
+<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>
@@ -489,11 +487,11 @@ needs to be done. This features allows r
</li>
</ol>
-<h3
id="wzxhzdk13wzxhzdk14configuring-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>
-<p>For example for following OSGi config</p>
+<h3 id="wzxhzdk13wzxhzdk14configuring-osgi-appenders-in-the-logback-config"><a
name="config-override"></a>Configuring OSGi appenders in the Logback Config</h3>
+<p>So far Sling used to configure the appenders based on OSGi config. This
provides a very limited
+set of 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>
+<p>For example, for the following OSGi config</p>
<div class="codehilite"><pre><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">file</span><span
class="p">=</span>"<span class="n">logs</span><span
class="o">/</span><span class="n">error</span><span class="p">.</span><span
class="nb">log</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">level</span><span
class="p">=</span>"<span class="n">info</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">file</span><span
class="p">.</span><span class="nb">size</span><span
class="p">=</span>"<span class="s">'.'</span><span
class="n">yyyy</span><span class="o">-</span><span class="n">MM</span><span
class="o">-</span><span class="n">dd</span>"
@@ -502,8 +500,8 @@ from within the Logback config file. OSG
</pre></div>
-<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>
+<p>The Logback appender would be named <code>logs/error.log</code>. To
extend/override the config in a Logback config
+create an appender with the name <code>logs/error.log</code>:</p>
<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>
@@ -514,17 +512,17 @@ create an appender with name <code>logs/
</pre></div>
-<p>In this case then Log module would create appender based on Logback config
instead of OSGi config. This can
-be used to move the application from OSGi based config to Logback based config
easily</p>
+<p>In this case the logging module creates an appender based on the Logback
config instead of the OSGi config.
+This can be used to move the application from OSGi based configs to Logback
based configs.</p>
<h2 id="using-slf4j-api-17">Using Slf4j API 1.7</h2>
<p>With Slf4j API 1.7 onwards its possible to use logger methods with varargs
i.e. log n arguments without
constructing an object array e.g. <code>log.info("This is a test {} , {}, {},
{}",1,2,3,4)</code>. Without var args
you need to construct an object array <code>log.info("This is a test {} , {},
{}, {}",new Object[] {1,2,3,4})</code>.
-To make use of this API and still be able to use your bundle on Sling system
which package older version
-of API jar follow the steps below (See <a
href="https://issues.apache.org/jira/browse/SLING-3243";>SLING-3243</a>) for
more details</p>
+To make use of this API and still be able to use your bundle on Sling systems
which package older version
+of the API jar, follow the below steps. (See <a
href="https://issues.apache.org/jira/browse/SLING-3243";>SLING-3243</a>) for
more details.</p>
<ol>
<li>
-<p>Update the api version in pom dependency</p>
+<p>Update the api version in the pom:</p>
<div class="codehilite"><pre><span class="nt"><dependencies></span>
<span class="nt"><dependency></span>
<span class="nt"><groupId></span>org.slf4j<span
class="nt"></groupId></span>
@@ -539,7 +537,7 @@ of API jar follow the steps below (See <
</li>
<li>
-<p>Add <code>Import-Package</code> instruction with custom version range. </p>
+<p>Add an <code>Import-Package</code> instruction with a custom version range:
</p>
<div class="codehilite"><pre><span class="nt"><build></span>
<span class="nt"><plugins></span>
<span class="nt"><plugin></span>
@@ -564,24 +562,21 @@ of API jar follow the steps below (See <
</li>
</ol>
-<p>Above setup ensures following things</p>
-<ol>
-<li>Slf4j API bundle 1.7.x is binary compatible with 1.6.x.</li>
-<li>It allows bundle to make use of var args feature while making logging
calls</li>
-<li>Bundle can still be deployed on older system which package 1.6.4 version
of slf4j api</li>
-</ol>
+<p>The Slf4j API bundle 1.7.x is binary compatible with 1.6.x.</p>
+<p>This setup allows your bundles to make use of the var args feature while
making logging calls, but the bundles
+can still be deployed on older systems which provide only the 1.6.4 version of
the slf4j api.</p>
<h2 id="webconsole-plugin">WebConsole Plugin</h2>
-<p>The Web Console Plugin supports following features</p>
+<p>The Web Console Plugin supports the following features:</p>
<ul>
-<li>Displays list of loggers which have level or appender configured</li>
-<li>List of File appenders with location of current active files</li>
-<li>Content of LogBack config file</li>
-<li>Content of various Logback config fragment</li>
-<li>Logback Status logs</li>
+<li>Display the list of loggers which have levels or appenders configured.</li>
+<li>List the file appenders with the location of current active log files.</li>
+<li>Show the contents of LogBack config files.</li>
+<li>Show the contents of various Logback config fragments.</li>
+<li>Show Logback Status logs.</li>
</ul>
<p><img src="sling-log-support.png" /></p>
<div class="timestamp" style="margin-top: 30px; font-size: 80%;
text-align: right;">
- Rev. 1542924 by chetanm on Mon, 18 Nov 2013 07:01:51 +0000
+ Rev. 1543495 by bdelacretaz on Tue, 19 Nov 2013 16:58:07 +0000
</div>
<div class="trademarkFooter">
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache
Sling project
