Return-Path: X-Original-To: apmail-sling-commits-archive@www.apache.org Delivered-To: apmail-sling-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 3BE83101F3 for ; Tue, 19 Nov 2013 16:58:37 +0000 (UTC) Received: (qmail 79779 invoked by uid 500); 19 Nov 2013 16:58:36 -0000 Delivered-To: apmail-sling-commits-archive@sling.apache.org Received: (qmail 79714 invoked by uid 500); 19 Nov 2013 16:58:35 -0000 Mailing-List: contact commits-help@sling.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@sling.apache.org Delivered-To: mailing list commits@sling.apache.org Received: (qmail 79707 invoked by uid 99); 19 Nov 2013 16:58:34 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 19 Nov 2013 16:58:34 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 19 Nov 2013 16:58:29 +0000 Received: from eris.apache.org (localhost [127.0.0.1]) by eris.apache.org (Postfix) with ESMTP id 5B2D023888E7; Tue, 19 Nov 2013 16:58:08 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1543495 - /sling/site/trunk/content/documentation/development/logging.mdtext Date: Tue, 19 Nov 2013 16:58:08 -0000 To: commits@sling.apache.org From: bdelacretaz@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20131119165808.5B2D023888E7@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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
-This document is for new 4.x release of Sling Commons Log components. Refer to -Logging 3.x 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 +Logging 3.x for older versions.
[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 props = new Hashtable(); @@ -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 -### Configuring OSGi based appenders in Logback Config +### 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 @@ -328,19 +322,18 @@ create an appender with name `logs/error - -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 @@ -353,7 +346,7 @@ of API jar follow the steps below (See [ ... -2. Add `Import-Package` instruction with custom version range. +2. Add an `Import-Package` instruction with a custom version range: :::xml @@ -376,22 +369,20 @@ of API jar follow the steps below (See [ -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.