incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Logging
Date Thu, 23 Jul 2009 13:32:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Logging">Logging</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~fmeschbe">Felix
Meschberger</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <h1><a name="Logging-Logging"></a>Logging</h1>

<h2><a name="Logging-Introduction"></a>Introduction</h2>

<p>Logging in Sling is supported by the <tt>org.apache.sling.commons.log</tt>
bundle, which is one of the first bundles installed and started by the Sling Launcher. The
<tt>org.apache.sling.commons.log</tt> bundle has the following tasks:</p>

<ul>
	<li>Implements the OSGi Log Service Specification and registers the <tt>LogService</tt>
and <tt>LogReader</tt> services</li>
	<li>Exports three commonly used logging APIs:
	<ul>
		<li><a href="http://www.slf4j.org" rel="nofollow">Simple Logging Facade for
Java (SLF4J)</a></li>
		<li><a href="http://jakarta.apache.org/commons/logging" rel="nofollow">Apache
Commons Logging</a></li>
		<li><a href="http://logging.apache.org/log4j/index.html" rel="nofollow">log4j</a></li>
	</ul>
	</li>
	<li>Configures logging through our own implementation of the SLF4J backend API</li>
</ul>



<h2><a name="Logging-InitialConfiguration"></a>Initial Configuration</h2>

<p>The <tt>org.apache.sling.commons.log</tt> bundle gets the initial configuration
from the following <tt>BundleContext</tt> properties:</p>


<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.level</tt> </td>
<td class='confluenceTd'> <tt>INFO</tt> </td>
<td class='confluenceTd'> Sets the initial logging level of the root logger. This may
be any of the defined logging levels <tt>DEBUG</tt>, <tt>INFO</tt>,
<tt>WARN</tt>, <tt>ERROR</tt> and <tt>FATAL</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file</tt> </td>
<td class='confluenceTd'> undefined </td>
<td class='confluenceTd'> Sets the log file to which log messages are written. If this
property is empty or missing, log messages are written to <tt>System.out</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file.number</tt>
</td>
<td class='confluenceTd'> 5 </td>
<td class='confluenceTd'> The number of rotated files to keep. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file.size</tt>
</td>
<td class='confluenceTd'> '.'yyyy-MM-dd </td>
<td class='confluenceTd'> Defines how the log file is rotated (by schedule or by size)
and when to rotate. See the section <em>Log File Rotation</em> below for full
details on log file rotation. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.pattern</tt>
</td>
<td class='confluenceTd'> {0,date,dd.MM.yyyy HH:mm:ss.SSS} &#42;{4}&#42; [{2}]
{3} {5} </td>
<td class='confluenceTd'> The <tt>MessageFormat</tt> pattern to use for
formatting log messages with the root logger. </td>
</tr>
</tbody></table>


<h2><a name="Logging-UserConfiguration"></a>User Configuration</h2>

<p>User Configuration after initial configuration is provided by the Configuration Admin
Service. To this avail two <tt>org.osgi.services.cm.ManagedServiceFactory</tt>
services are registered under the PIDs <tt>org.apache.sling.commons.log.LogManager.factory.writer</tt>
and <tt>org.apache.sling.commons.log.LogManager.factory.config</tt> which may
receive configuration.</p>


<h3><a name="Logging-LoggerConfiguration"></a>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
<tt>org.apache.sling.commons.log.LogManager.factory.config</tt> may be created
and configured with the Configuration Admin Service.</p>

<p>The following properties may be set:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Type </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.level</tt> </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> <tt>INFO</tt> </td>
<td class='confluenceTd'> Sets the logging level of the loggers. This may be any of
the defined logging levels <tt>DEBUG</tt>, <tt>INFO</tt>, <tt>WARN</tt>,
<tt>ERROR</tt> and <tt>FATAL</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file</tt> </td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> undefined </td>
<td class='confluenceTd'> Sets the log file to which log messages are written. If this
property is empty or missing, log messages are written to <tt>System.out</tt>.
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. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.pattern</tt>
</td>
<td class='confluenceTd'> String </td>
<td class='confluenceTd'> {0,date,dd.MM.yyyy HH:mm:ss.SSS} &#42;{4}&#42; [{2}]
{3} {5} </td>
<td class='confluenceTd'> The <tt>java.util.MessageFormat</tt> pattern to
use for formatting log messages with the root logger. This is a <tt>java.util.MessageFormat</tt>
pattern supporting up to six arguments: \<br/>
 <div class="error"><span class="error">Unknown macro: {0}</span> </div>
The timestamp of type <tt>java.util.Date</tt>, <div class="error"><span
class="error">Unknown macro: {1}</span> </div> the log marker, <div class="error"><span
class="error">Unknown macro: {2}</span> </div> the name \<br/>
 of the current thread, <div class="error"><span class="error">Unknown macro:
{3}</span> </div> the name of the logger, <div class="error"><span class="error">Unknown
macro: {4}</span> </div> the debug level and \<br/>
 <div class="error"><span class="error">Unknown macro: {5}</span> </div>
the actual debug message. If the log call includes a Throwable, the \<br/>
 stacktrace is just appended to the message regardless of the pattern. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.names</tt> </td>
<td class='confluenceTd'> String[] </td>
<td class='confluenceTd'> A list of logger names to which this configuration applies.
</td>
</tr>
</tbody></table>


<p>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. </p>


<h3><a name="Logging-LogWriterConfiguration"></a>Log Writer Configuration</h3>

<p>Log Writer Configuration is used to setup file output and log file rotation characteristics
for log writers used by the Loggers.</p>

<p>The following properties may be set:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file</tt> </td>
<td class='confluenceTd'> undefined </td>
<td class='confluenceTd'> Sets the log file to which log messages are written. If this
property is empty or missing, log messages are written to <tt>System.out</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file.number</tt>
</td>
<td class='confluenceTd'> 5 </td>
<td class='confluenceTd'> The number of rotated files to keep. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>org.apache.sling.commons.log.file.size</tt>
</td>
<td class='confluenceTd'> '.'yyyy-MM-dd </td>
<td class='confluenceTd'> Defines how the log file is rotated (by schedule or by size)
and when to rotate. See the section <em>Log File Rotation</em> below for full
details on log file rotation. </td>
</tr>
</tbody></table>

<p>See the section <em>Log File Rotation</em> below for full details on
the <tt>org.apache.sling.commons.log.file.size</tt> and <tt>org.apache.sling.commons.log.file.number</tt>
properties.</p>



<h2><a name="Logging-LogFileRotation"></a>Log File Rotation</h2>

<p>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 <em>Scheduled Rotation</em> and
is used by specifying a <tt>SimpleDateFormat</tt> 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 <tt>'.'yyyy-MM-dd</tt> causing daily log rotation. Previously log
rotation defaulted to a 10MB file size limit.</p>



<h3><a name="Logging-ScheduledRotation"></a>Scheduled Rotation</h3>

<p>The rolling schedule is specified by setting the <tt>org.apache.sling.commons.log.file.size</tt>
property to a <tt>java.text.SimpleDateFormat</tt> pattern. Literal text (such
as a leading dot) to be included must be <em>enclosed</em> within a pair of single
quotes. A formatted version of the date pattern is used as the suffix for the rolled file
name.</p>

<p>For example, if the log file is configured as <tt>/foo/bar.log</tt> and
the pattern set to <tt>'.'yyyy-MM-dd</tt>, on 2001-02-16 at midnight, the logging
file <tt>/foo/bar.log</tt> will be copied to <tt>/foo/bar.log.2001-02-16</tt>
and logging for 2001-02-17 will continue in <tt>/foo/bar.log</tt> until it rolls
over the next day.</p>

<p>Is is possible to specify monthly, weekly, half-daily, daily, hourly, or minutely
rollover schedules.</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> DatePattern </th>
<th class='confluenceTh'> Rollover schedule </th>
<th class='confluenceTh'> Example </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-MM</tt> </td>
<td class='confluenceTd'> Rollover at the beginning of each month </td>
<td class='confluenceTd'> At midnight of May 31st, 2002 <tt>/foo/bar.log</tt>
will be copied to <tt>/foo/bar.log.2002-05</tt>. Logging for the month of June
will be output to <tt>/foo/bar.log</tt> until it is also rolled over the next
month. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-ww</tt> </td>
<td class='confluenceTd'> Rollover at the first day of each week. The first day of the
week depends on the locale. </td>
<td class='confluenceTd'> Assuming the first day of the week is Sunday, on Saturday
midnight, June 9th 2002, the file <tt>/foo/bar.log</tt> will be copied to <tt>/foo/bar.log.2002-23</tt>.
Logging for the 24th week of 2002 will be output to <tt>/foo/bar.log</tt> until
it is rolled over the next week. </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-MM-dd</tt> </td>
<td class='confluenceTd'> Rollover at midnight each day.</td>
<td class='confluenceTd'> At midnight, on March 8th, 2002, <tt>/foo/bar.log</tt>
will be copied to <tt>/foo/bar.log.2002-03-08</tt>. Logging for the 9th day of
March will be output to <tt>/foo/bar.log</tt> until it is rolled over the next
day.</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-MM-dd-a</tt> </td>
<td class='confluenceTd'> Rollover at midnight and midday of each day.</td>
<td class='confluenceTd'> at noon, on March 9th, 2002, <tt>/foo/bar.log</tt>
will be copied to  <tt>/foo/bar.log.2002-03-09-AM</tt>. Logging for the afternoon
of the 9th will be output to <tt>/foo/bar.log</tt> until it is rolled over at
midnight.</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-MM-dd-HH</tt> </td>
<td class='confluenceTd'> Rollover at the top of every hour.</td>
<td class='confluenceTd'> At approximately 11:00.000 o'clock on March 9th, 2002, <tt>/foo/bar.log</tt>
will be copied to <tt>/foo/bar.log.2002-03-09-10</tt>. Logging for the 11th hour
of the 9th of March will be output to <tt>/foo/bar.log</tt> until it is rolled
over at the beginning of the next hour.</td>
</tr>
<tr>
<td class='confluenceTd'> <tt>'.'yyyy-MM-dd-HH-mm</tt> </td>
<td class='confluenceTd'> Rollover at the beginning of every minute.</td>
<td class='confluenceTd'> At approximately 11:23,000, on March 9th, 2001, <tt>/foo/bar.log</tt>
will be copied to <tt>/foo/bar.log.2001-03-09-10-22</tt>. Logging for the minute
of 11:23 (9th of March) will be output to <tt>/foo/bar.log</tt> until it is rolled
over the next minute.</td>
</tr>
</tbody></table>

<p>Do not use the colon ":" character in anywhere in the pattern option. The text before
the colon is interpeted as the protocol specificaion of a URL which is probably not what you
want.</p>

<p>Note that Scheduled Rotation ignores the <tt>org.apache.sling.commons.log.file.number</tt>
property since the old log files are not numbered but "dated".</p>


<h3><a name="Logging-SizeRotation"></a>Size Rotation</h3>

<p>Log file rotation by size is specified by setting the <tt>org.apache.sling.commons.log.file.size</tt>
property to a plain number or a number plus a size multiplier. The size multiplier may be
any of <tt>K</tt>, <tt>KB</tt>, <tt>M</tt>, <tt>MB</tt>,
<tt>G</tt>, or <tt>GB</tt> where the case is ignored and the meaning
is probably obvious.</p>

<p>When using Size Rotation, the <tt>org.apache.sling.commons.log.file.number</tt>
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 <tt>org.apache.sling.commons.log.file.number</tt>
to <tt>5</tt> (which happens to be the default).</p>
     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Logging">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=76166&revisedVersion=5&originalVersion=4">View
Change</a>
              |
       <a href="http://cwiki.apache.org/confluence/display/SLINGxSITE/Logging?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message