incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bdelacre...@apache.org
Subject svn commit: r1543495 - /sling/site/trunk/content/documentation/development/logging.mdtext
Date Tue, 19 Nov 2013 16:58:08 GMT
Author: bdelacretaz
Date: Tue Nov 19 16:58:07 2013
New Revision: 1543495

URL: http://svn.apache.org/r1543495
Log:
clarify some statements and fix a few typos

Modified:
    sling/site/trunk/content/documentation/development/logging.mdtext

Modified: sling/site/trunk/content/documentation/development/logging.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/logging.mdtext?rev=1543495&r1=1543494&r2=1543495&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/logging.mdtext (original)
+++ sling/site/trunk/content/documentation/development/logging.mdtext Tue Nov 19 16:58:07
2013
@@ -1,9 +1,8 @@
 Title: Logging
 
 <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>
 
 [TOC]
@@ -11,8 +10,8 @@ to older version.
 ## Introduction
 
 Logging in Sling is supported by the `org.apache.sling.commons.log` 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
+and started by the Sling Launcher. This bundle along with other bundles manages the Sling
Logging and provides the
+following features:
 
 * Implements the OSGi Log Service Specification and registers the `LogService` and `LogReader`
services
 * Exports three commonly used logging APIs:
@@ -21,11 +20,11 @@ features
   * [log4j](http://logging.apache.org/log4j/index.html)
   * [java.util.logging](http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html)
 * Configures logging through Logback which is integrated with the OSGi environment
-* Logging can be configured both via editing Logback xml or via OSGi Configurations
+* Allows logging to be configured both via editing Logback xml or via OSGi Configurations
 
 ## Initial Configuration
 
-The `org.apache.sling.commons.log` bundle gets the initial configuration from the following
`BundleContext` properties:
+The `org.apache.sling.commons.log` bundle gets its initial configuration from the following
`BundleContext` properties:
 
 
 | Property | Default | Description |
@@ -42,7 +41,7 @@ The `org.apache.sling.commons.log` bundl
 
 User Configuration after initial configuration is provided by the Configuration Admin Service.
To this avail two
 `org.osgi.services.cm.ManagedServiceFactory` services are registered under the PIDs `org.apache.sling.commons.log.LogManager.factory.writer`
-and `org.apache.sling.commons.log.LogManager.factory.config` which may receive configuration.
+and `org.apache.sling.commons.log.LogManager.factory.config` to receive configurations.
 
 
 ### Logger Configuration
@@ -89,7 +88,7 @@ and is used by specifying a `SimpleDateF
 and is used by setting a maximum file size as the log file size.
 
 As of version 2.0.6 of the Sling Commons Log bundle, the default value for log file scheduling
is `'.'yyyy-MM-dd`
-causing daily log rotation. Previously log rotation defaulted to a 10MB file size limit.
+causing daily log rotation. In previous version, log rotation defaults to a 10MB file size
limit.
 
 ##### Scheduled Rotation
 
@@ -137,17 +136,16 @@ Logback integration provides following f
 * LogBack configuration can be provided via Logback config xml
 * Supports Appenders registered as OSGi Services
 * Supports Filters and TurboFilters registered as OSGi Services
-* Support providing Logback config as fragments through OSGi Service Registry
-* Support for referring to Appenders registered as OSGi services from with Logback
-  config
-* Exposing Logback runtime state through Felix WebConsole Plugin
+* Support providing Logback configuration as fragments through OSGi Service Registry
+* Support for referring to Appenders registered as OSGi services from with Logback config
+* Exposes Logback runtime state through the Felix WebConsole Plugin
 
-Following sections would provide more details around these features
+The following sections provide more details.
 
-### TurboFilters as OSGi Service
+### TurboFilters as OSGi Services
 
-[Logback TurboFilter][3] operate globally and invoked for every Logback call. To register
a `TurboFilter` as OSGi service
-the bundle just need to register a service  against `ch.qos.logback.classic.turbo.TurboFilter`
class
+[Logback TurboFilters][3] operate globally and are invoked for every Logback call. To register
an OSGi `TurboFilter`,
+just to register an service that implements the `ch.qos.logback.classic.turbo.TurboFilter`
interface.
 
     :::java
     import import ch.qos.logback.classic.turbo.MatchingFilter;
@@ -166,9 +164,9 @@ the bundle just need to register a servi
         }
     }
 
-As these filters are invoked for every call they must not take much time to execute.
+As these filters are invoked for every call they must execute quickly.
 
-### Filter as OSGi service
+### Filters as OSGi services
 
 [Logback Filters][1] 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
@@ -194,13 +192,11 @@ be passed to the appender. When register
         }
     }
 
-### Appenders as OSGi service
-
-[Logback Appenders][2] handle the logging events produced by Logback. To register an `Appender`
as OSGi service
-the bundle just need to register a service  against `ch.qos.logback.core.Appender` class.
 When registering an
-appender the bundle needs to configure a service property `loggers` which refers to list
of logger names to which
-the Appender must be attached
+### Appenders as OSGi services
 
+[Logback Appenders][2] handle the logging events produced by Logback. To register an OSGi
`Appender`,
+just register a service that implements the `ch.qos.logback.core.Appender` interface.  Such
a service must
+have a `loggers` service property, which refers to list of logger names to which the Appender
must be attached.
 
     :::java
     Dictionary<String,Object> props = new Hashtable<String, Object>();
@@ -216,12 +212,13 @@ the Appender must be attached
 ### Logback Config Fragment Support
 
 Logback supports including parts of a configuration file from another file (See [File Inclusion][4]).
This module
-extends that support by allowing other bundles to provide config fragments. There are two
ways to achieve that
+extends that support by allowing other bundles to provide config fragments. There are two
ways to achieve that, 
+described below.
 
-#### Exposing fragment as String objects
+#### Logback config fragments as String objects
 
 If you have the config as string then you can register that String instance as a service
with property `logbackConfig`
-set to true. Sling Logback Extension would monitor such objects and pass them to logback
+set to true. The Sling Logback Extension monitors such objects and passes them to logback.
 
 
     :::java
@@ -245,12 +242,12 @@ set to true. Sling Logback Extension wou
     registration = context.registerService(String.class.getName(),config,props);
 
 
-If the config needs to be updated just re-register the service and change would be picked
up
-
-#### Exposing fragment as ConfigProvider instance
+If the config needs to be updated just re-register the service so that changes are picked
up.
 
-Another way to provide config fragment is by providing an implementation of `org.apache.sling.commons.log.logback.ConfigProvider`
+#### Logback config fragments as ConfigProvider instances
 
+Another way to provide config fragments is with services that implement the 
+`org.apache.sling.commons.log.logback.ConfigProvider` interface.
 
     :::java
     @Component
@@ -261,8 +258,8 @@ Another way to provide config fragment i
         }
     }
 
-If the config changes then sending an event to `org/apache/sling/commons/log/RESET` would
reset the Logback runtime
-
+If the config changes then sending an OSGi event with the `org/apache/sling/commons/log/RESET`
topic 
+resets the Logback runtime.
 
     :::java
     eventAdmin.sendEvent(new Event("org/apache/sling/commons/log/RESET",new Properties()));
@@ -271,13 +268,11 @@ If the config changes then sending an ev
 
 Logback can be configured with an external file. The file name can be specified through
 
-1. OSGi config - Look for config with name `Apache Sling Logging Configuration` and specify
the path for
-   config file property
-2. OSGi Framework Properties - Logback supports also looks for file name with property name
-   `org.apache.sling.commons.log.configurationFile`
-
-If you are providing an external config file then to support OSGi integration you would need
to add following
-action entry
+1. OSGi config - Look for a config with name `Apache Sling Logging Configuration` and specify
the config file path.
+2. OSGi Framework Properties - Logback support also looks for a file named according to the
OSGi framwork `org.apache.sling.commons.log.configurationFile` property.
+   
+If you are providing an external config file then to support OSGi integration you need to
add following
+action entry:
 
     :::xml
     <newRule pattern="*/configuration/osgi"
@@ -290,24 +285,24 @@ The `osgi` element enables the OSGi inte
 
 ### Java Util Logging (JUL) Integration
 
-The bundle also support [SLF4JBridgeHandler][9]. To enable JUL integration following two
steps
-needs to be done. This features allows routing logging messages from JUL to the Logbback
appenders
+The bundle also support [SLF4JBridgeHandler][9]. The two steps listed below enable the JUL
integration.
+This allows for routing logging messages from JUL to the Logbback appenders.
 
-1. Set framework property `org.apache.sling.commons.log.julenabled` to true
-2. Set the [LevelChangePropagator][8] in LogbackConfig
+1. Set the `org.apache.sling.commons.log.julenabled` framework property to true.
+2. Set the [LevelChangePropagator][8] in LogbackConfig:
 
         :::xml
         <configuration>
           <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
         </configuration>
 
-### <a name="config-override"></a>Configuring OSGi based appenders in Logback
Config
+### <a name="config-override"></a>Configuring OSGi appenders in the Logback Config
 
-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
+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.
 
-For example for following OSGi config
+For example, for the following OSGi config
 
     org.apache.sling.commons.log.file="logs/error.log"
     org.apache.sling.commons.log.level="info"
@@ -315,9 +310,8 @@ For example for following OSGi config
     org.apache.sling.commons.log.file.number=I"7"
     org.apache.sling.commons.log.pattern="{0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3}
{5}"
 
-
-The Logback appender would be named as `logs/error.log`. To extend/override the config in
Logback config
-create an appender with name `logs/error.log`
+The Logback appender would be named `logs/error.log`. To extend/override the config in a
Logback config
+create an appender with the name `logs/error.log`:
 
     :::xml
     <appender name="/logs/error.log" class="ch.qos.logback.core.FileAppender">
@@ -328,19 +322,18 @@ create an appender with name `logs/error
       </encoder>
     </appender>
 
-
-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
+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.
 
 ## Using Slf4j API 1.7
 
 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. `log.info("This is a test {} , {}, {}, {}",1,2,3,4)`. Without
var args
 you need to construct an object array `log.info("This is a test {} , {}, {}, {}",new Object[]
{1,2,3,4})`. 
-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 [SLING-3243][SLING-3243]) for more details
+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 [SLING-3243][SLING-3243]) for more details.
 
-1. Update the api version in pom dependency
+1. Update the api version in the pom:
 
         :::xml
         <dependencies>
@@ -353,7 +346,7 @@ of API jar follow the steps below (See [
            ...
         </dependency>
 
-2. Add `Import-Package` instruction with custom version range. 
+2. Add an `Import-Package` instruction with a custom version range: 
 
         :::xml
         <build>
@@ -376,22 +369,20 @@ of API jar follow the steps below (See [
            </plugins>
         </build>
 
-Above setup ensures following things
-
-1. Slf4j API bundle 1.7.x is binary compatible with 1.6.x.
-2. It allows bundle to make use of var args feature while making logging calls
-3. Bundle can still be deployed on older system which package 1.6.4 version of slf4j api
+The Slf4j API bundle 1.7.x is binary compatible with 1.6.x.
 
+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.
 
 ## WebConsole Plugin
 
-The Web Console Plugin supports following features
+The Web Console Plugin supports the following features:
 
-* Displays list of loggers which have level or appender configured
-* List of File appenders with location of current active files
-* Content of LogBack config file
-* Content of various Logback config fragment
-* Logback Status logs
+* Display the list of loggers which have levels or appenders configured.
+* List the file appenders with the location of current active log files.
+* Show the contents of LogBack config files.
+* Show the contents of various Logback config fragments.
+* Show Logback Status logs.
 
 <img src="sling-log-support.png" />
 



Mime
View raw message