You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by bd...@apache.org on 2013/11/19 17:58:08 UTC
svn commit: r1543495 -
/sling/site/trunk/content/documentation/development/logging.mdtext
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" />