incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From chet...@apache.org
Subject svn commit: r1542739 - /sling/site/trunk/content/documentation/development/logging-new.mdtext
Date Sun, 17 Nov 2013 14:43:57 GMT
Author: chetanm
Date: Sun Nov 17 14:43:57 2013
New Revision: 1542739

URL: http://svn.apache.org/r1542739
Log:
SLING-3070 - Update Log help document with Logback related details 

Adding OSGi based configuration steps from previous documentation

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

Modified: sling/site/trunk/content/documentation/development/logging-new.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/development/logging-new.mdtext?rev=1542739&r1=1542738&r2=1542739&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/development/logging-new.mdtext (original)
+++ sling/site/trunk/content/documentation/development/logging-new.mdtext Sun Nov 17 14:43:57
2013
@@ -21,6 +21,7 @@ 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
 
 ## Logback Integration
 
@@ -41,6 +42,7 @@ Following sections would provide more de
 [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
 
+    :::java
     import import ch.qos.logback.classic.turbo.MatchingFilter;
 
     SimpleTurboFilter stf = new SimpleTurboFilter();
@@ -66,6 +68,7 @@ be passed to the appender. When register
 `appenders` which refers to list of appender names to which the Filter must be attached
 
 
+    :::java
     import ch.qos.logback.core.filter.Filter;
 
     SimpleFilter stf = new SimpleFilter();
@@ -92,6 +95,7 @@ appender the bundle needs to configure a
 the Appender must be attached
 
 
+    :::java
     Dictionary<String,Object> props = new Hashtable<String, Object>();
 
     String[] loggers = {
@@ -148,7 +152,7 @@ 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 listener
+If the config changes then sending an event to `org/apache/sling/commons/log/RESET` would
reset the Logback runtime
 
 
     eventAdmin.sendEvent(new Event("org/apache/sling/commons/log/RESET",new Properties()));
@@ -165,7 +169,7 @@ Logback can be configured with an extern
 If you are providing an external config file then to support OSGi integration you would need
to add following
 action entry
 
-
+    :::xml
     <newRule pattern="*/configuration/osgi"
              actionClass="org.apache.sling.commons.log.logback.OsgiAction"/>
     <newRule pattern="*/configuration/appender-ref-osgi"
@@ -182,12 +186,13 @@ needs to be done. This features allows r
 1. Set framework property `org.apache.sling.commons.log.julenabled` to true
 2. Set the [LevelChangePropagator][8] in LogbackConfig
 
-        <configuration>
-            <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
-            ...
-        </configuration>
+    :::xml
+    <configuration>
+      <contextListener class="ch.qos.logback.classic.jul.LevelChangePropagator"/>
+      ...
+    </configuration>
 
-### Configuring OSGi based appenders in Logback Config
+### <a name="config-override"></a>Configuring OSGi based appenders in 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
@@ -205,7 +210,7 @@ For example for following OSGi config
 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`
 
-
+    :::xml
     <appender name="/logs/error.log" class="ch.qos.logback.core.FileAppender">
       <file>${sling.home}/logs/error.log</file>
       <encoder>
@@ -233,6 +238,100 @@ The `org.apache.sling.commons.log` bundl
 | `org.apache.sling.commons.log.julenabled` | n/a | Enables the `java.util.logging` support.
|
 | `org.apache.sling.commons.log.configurationFile` | n/a | Path for the Logback config file
which would be used to configure logging. If the path is not absolute then it would be resolved
against Sling Home |
 
+## User Configuration - OSGi Based
+
+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.
+
+
+### Logger Configuration
+
+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 `org.apache.sling.commons.log.LogManager.factory.config`
+may be created and configured with the Configuration Admin Service.
+
+The following properties may be set:
+
+| Property | Type | Default | Description |
+|--|--|--|--|
+| `org.apache.sling.commons.log.level` | `String` | `INFO` | Sets the logging level of the
loggers. This may be any of the defined logging levels `DEBUG`, `INFO`, `WARN`, `ERROR` and
`FATAL`. |
+| `org.apache.sling.commons.log.file` | `String` | undefined | Sets the log file to which
log messages are written. If this property is empty or missing, log messages are written to
`System.out`. 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. |
+| `org.apache.sling.commons.log.pattern` | `String` | \{0,date,dd.MM.yyyy HH:mm:ss.SSS\}
\*\{4\}\* \[\{2\}\]({{ refs.-2.path }}) \{3\} \{5\} | The `java.util.MessageFormat` pattern
to use for formatting log messages with the root logger. This is a `java.util.MessageFormat`
pattern supporting up to six arguments: \{0\} The timestamp of type `java.util.Date`, \{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. |
+| `org.apache.sling.commons.log.names` | `String\[\]` | -- | A list of logger names to which
this configuration applies. |
+
+
+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.
+
+
+### Log Writer Configuration
+
+Log Writer Configuration is used to setup file output and log file rotation characteristics
for log writers used by the Loggers.
+
+The following properties may be set:
+
+| Property | Default | Description |
+|--|--|--|
+| `org.apache.sling.commons.log.file` | undefined | Sets the log file to which log messages
are written. If this property is empty or missing, log messages are written to `System.out`.
|
+| `org.apache.sling.commons.log.file.number` | 5 | The number of rotated files to keep. |
+| `org.apache.sling.commons.log.file.size` | '.'yyyy-MM-dd | Defines how the log file is
rotated (by schedule or by size) and when to rotate. See the section *Log File Rotation* below
for full details on log file rotation. |
+
+See the section *Log File Rotation* below for full details on the `org.apache.sling.commons.log.file.size`
and
+`org.apache.sling.commons.log.file.number` properties.
+
+
+
+#### Log File Rotation
+
+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 *Scheduled Rotation*
+and is used by specifying a `SimpleDateFormat` pattern as the log file "size". The second
method is called *Size Rotation*
+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.
+
+##### Scheduled Rotation
+
+The rolling schedule is specified by setting the `org.apache.sling.commons.log.file.size`
property to a
+`java.text.SimpleDateFormat` pattern. Literal text (such as a leading dot) to be included
must be *enclosed* 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 `TimeBasedRollingPolicy` for the appender. Refer to [TimeBasedRollingPolicy][10]
for
+more details around the pattern format
+
+For example, if the log file is configured as `/foo/bar.log` and the pattern set to `'.'yyyy-MM-dd`,
on
+2001-02-16 at midnight, the logging file `/foo/bar.log` will be renamed to `/foo/bar.log.2001-02-16`
and logging for
+2001-02-17 will continue in a new `/foo/bar.log` file until it rolls over the next day.
+
+It is possible to specify monthly, weekly, half-daily, daily, hourly, or minutely rollover
schedules.
+
+| DatePattern | Rollover schedule | Example |
+|--|--|--|
+| `'.'yyyy-MM` | Rollover at the beginning of each month | At midnight of May 31st, 2002
`/foo/bar.log` will be copied to `/foo/bar.log.2002-05`. Logging for the month of June will
be output to `/foo/bar.log` until it is also rolled over the next month. |
+| `'.'yyyy-ww` | Rollover at the first day of each week. The first day of the week depends
on the locale. | Assuming the first day of the week is Sunday, on Saturday midnight, June
9th 2002, the file `/foo/bar.log` will be copied to `/foo/bar.log.2002-23`. Logging for the
24th week of 2002 will be output to `/foo/bar.log` until it is rolled over the next week.
|
+| `'.'yyyy-MM-dd` | Rollover at midnight each day.| At midnight, on March 8th, 2002, `/foo/bar.log`
will be copied to `/foo/bar.log.2002-03-08`. Logging for the 9th day of March will be output
to `/foo/bar.log` until it is rolled over the next day.|
+| `'.'yyyy-MM-dd-a` | Rollover at midnight and midday of each day.| at noon, on March 9th,
2002, `/foo/bar.log` will be copied to  `/foo/bar.log.2002-03-09-AM`. Logging for the afternoon
of the 9th will be output to `/foo/bar.log` until it is rolled over at midnight.|
+| `'.'yyyy-MM-dd-HH` | Rollover at the top of every hour.| At approximately 11:00.000 o'clock
on March 9th, 2002, `/foo/bar.log` will be copied to `/foo/bar.log.2002-03-09-10`. Logging
for the 11th hour of the 9th of March will be output to `/foo/bar.log` until it is rolled
over at the beginning of the next hour.|
+| `'.'yyyy-MM-dd-HH-mm` | Rollover at the beginning of every minute.| At approximately 11:23,000,
on March 9th, 2001, `/foo/bar.log` will be copied to `/foo/bar.log.2001-03-09-10-22`. Logging
for the minute of 11:23 (9th of March) will be output to `/foo/bar.log` until it is rolled
over the next minute.|
+
+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.
+
+Note that Scheduled Rotation ignores the `org.apache.sling.commons.log.file.number` property
since the old log files are
+not numbered but "dated".
+
+
+##### Size Rotation
+
+Log file rotation by size is specified by setting the `org.apache.sling.commons.log.file.size`
property to a plain number
+or a number plus a size multiplier. The size multiplier may be any of `K`, `KB`, `M`, `MB`,
`G`, or `GB` where the case
+is ignored and the meaning is probably obvious.
+
+When using Size Rotation, the `org.apache.sling.commons.log.file.number` 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 `org.apache.sling.commons.log.file.number`
+to `5` (which happens to be the default).
 
 ## WebConsole Plugin enhancements
 
@@ -251,4 +350,5 @@ The web Console Plugin supports followin
 [3]: http://logback.qos.ch/manual/filters.html#TurboFilter
 [4]: http://logback.qos.ch/manual/configuration.html#fileInclusion
 [8]: http://logback.qos.ch/manual/configuration.html#LevelChangePropagator
-[9]: http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html
\ No newline at end of file
+[9]: http://www.slf4j.org/api/org/slf4j/bridge/SLF4JBridgeHandler.html
+[10]: http://logback.qos.ch/manual/appenders.html#TimeBasedRollingPolicy
\ No newline at end of file



Mime
View raw message