Author: ihabunek
Date: Wed Oct 19 05:13:48 2011
New Revision: 1185971
URL: http://svn.apache.org/viewvc?rev=1185971&view=rev
Log:
More work on docs.
Added:
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/loggers.xml
Removed:
logging/log4php/branches/experimental/config-adapters/src/site/apt/docs/configuration-old.apt
logging/log4php/branches/experimental/config-adapters/src/site/apt/docs/filters-old.apt
logging/log4php/branches/experimental/config-adapters/src/site/apt/docs/introduction-old.apt
logging/log4php/branches/experimental/config-adapters/src/site/apt/docs/loggers.apt
Modified:
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/appenders.xml
Modified:
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/appenders.xml
URL:
http://svn.apache.org/viewvc/logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/appenders.xml?rev=1185971&r1=1185970&r2=1185971&view=diff
==============================================================================
---
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/appenders.xml
(original)
+++
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/appenders.xml
Wed Oct 19 05:13:48 2011
@@ -83,7 +83,7 @@
</tr>
<tr>
<td><a
href="appenders/php.html">LoggerAppenderPhp</a></td>
- <td>Creates a PHP
user-level message using the PHP <code>trigger_error</code> function.</td>
+ <td>Creates a PHP
user-level message using the PHP <code>trigger_error()</code> function.</td>
</tr>
<tr>
<td><a
href="appenders/socket.html">LoggerAppenderSocket</a></td>
@@ -163,6 +163,28 @@
<em>primus</em> and will therefore only log to
the console.</p>
</subsection>
+
+
+ <subsection name="Appender threshold">
+
+ <p>An appender can be assigned a threshold
level. All logging requests with level lower than this threshold
+ will be ignored.</p>
+
+ <p>For example, if you set <code>WARN</code> as
a threshold, then <code>INFO</code>, <code>DEBUG</code>
+ and <code>TRACE</code> level events recieved by
the appender will not be logged, but <code>WARN</code>,
+ <code>ERROR</code> and <code>FATAL</code>
will.</p>
+
+ <p>An example of setting an appender
threshold:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="default" class="LoggerAppenderEcho" threshold="WARN" />
+ <root>
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+ </subsection>
</section>
</body>
</document>
Added:
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/loggers.xml
URL:
http://svn.apache.org/viewvc/logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/loggers.xml?rev=1185971&view=auto
==============================================================================
---
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/loggers.xml
(added)
+++
logging/log4php/branches/experimental/config-adapters/src/site/xdoc/docs/loggers.xml
Wed Oct 19 05:13:48 2011
@@ -0,0 +1,289 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document xmlns="http://maven.apache.org/XDOC/2.0";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd";>
+
+ <properties>
+ <title>Loggers</title>
+ </properties>
+
+ <body>
+ <section name="Loggers">
+
+ <p>A logger is a component which will take your logging
request and log it. Each class in a project can
+ have an individual logger, or they can all use a common
logger. Loggers are named entities; it is
+ common to name them after the class which will use it
for logging.</p>
+
+ <p>Creating a logger is done by calling the static
<code>getLogger()</code> method on the Logger object
+ and providing the name of the logger. For example, to
create a logger named <code>foo</code>:</p>
+
+ <pre class="prettyprint">$logger =
Logger::getLogger('foo');</pre>
+
+ <p>Logging requests are made by invoking one of the
printing methods of a Logger instance. These logging
+ methods are: trace, debug, info, warn, error and fatal.
The printing method determines the level of a
+ logging request. For example, calling the method
<code>info()</code> creates a logging request of level
+ <code>INFO</code>. For example:</p>
+
+ <pre class="prettyprint">$logger->info("This is the
message to be logged.");</pre>
+
+ <p>Loggers by themselves do not define where these
messages will be logged. For that you need to assign
+ one or more <a href="./appender.html">appenders</a> to
the logger.</p>
+
+ <subsection name="Logger threshold"
id="Logger_threshold">
+ <p>A logger can be assigned a threshold level.
All logging requests with level lower than this threshold
+ will be ignored.</p>
+
+ <p>For example, setting logger threshold to
<code>INFO</code> means that logging requests with levels
+ <code>TRACE</code> and <code>DEBUG</code> will
not be logged by this logger.</p>
+
+ <p>An example of setting the root logger
threshold to <code>DEBUG</code>:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>By default loggers do not have a threshold
set, which means they will log all events, regardless of the
+ level.</p>
+ </subsection>
+
+ <subsection name="Configuring loggers"
id="Configuring_loggers">
+ <p>Loggers can be individually configured in
the configuration file. </p>
+
+ <p>The simplest example is to configure the
root logger, since all other loggers will inherit its
+ settings, as explained in the <a
href="#Logger_hierarchy">next section</a>.</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+ <p>This configuration adds the
<code>default</code> appender to the root logger, and sets it's
+ <a href="#Logger_threshold">threshold level</a>
to DEBUG.</p>
+
+ <p>It is also possible to configure individual
named loggers. For example, let's configure the
+ <code>foo</code> logger, used in the example
above, and set it's threshold to WARN:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="default" class="LoggerAppenderConsole" />
+ <logger name="foo">
+ <level value="warn" />
+ <appender_ref ref="default" />
+ </logger>
+</configuration>
+]]></pre>
+ </subsection>
+
+ <subsection name="Logger hierarchy"
id="Logger_hierarchy">
+ <p>Loggers follow a parent-child relationship
pattern which is implemented by using a naming pattern.
+ A logger is said to be an <em>ancestor</em> of
another logger if its name followed by a dot is a
+ prefix of the <em>descendant</em> logger name.
A logger is said to be a <em>parent</em> of a
+ <em>child</em> logger if there are no ancestors
between itself and the descendant logger.</p>
+
+ <p>For example, the logger named
<code>foo</code> is a parent of the logger named <code>foo.bar</code>.
+ Similarly, <code>org</code> is a parent of
<code>org.apache</code> and an ancestor of
+ <code>org.apache.logging</code>. This naming
scheme should be familiar to most developers.</p>
+
+ <p>The root logger resides at the top of the
logger hierarchy. It is exceptional in two ways:</p>
+ <ul>
+ <li>it always exists,</li>
+ <li>it cannot be retrieved by name.</li>
+ </ul>
+
+ <p>Invoking the class static
<code>Logger::getRootLogger()</code> method retrieves the root logger.
+ All other loggers are instantiated and
retrieved with the <code>Logger::getLogger($name)</code>
+ method. This method takes the name of the
desired logger as a parameter. If the logger does not exist
+ at the time of the call, it will be created.</p>
+ </subsection>
+
+ <subsection name="Logger inheritance"
id="Logger_inheritance">
+ <p>The threshold level and appenders are
inherited from the parent to the child loggers.</p>
+
+ <p>For example examine the following
configuration:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="default" class="LoggerAppenderConsole" />
+ <root>
+ <level value="debug" />
+ <appender_ref ref="default" />
+ </root>
+</configuration>
+]]></pre>
+
+ <p>The threshold level of the root logger is
set to debug. Also, the root logger is linked to a console
+ appender. Any named logger that is created will
inherit these root settings.</p>
+
+<pre class="prettyprint"><![CDATA[
+$main = Logger::getLogger('main');
+$main->trace('This will not be logged.');
+$main->info('This will be logged.');
+]]></pre>
+ <p>A logger named <code>main</code> is created.
Since there is no logger-specific configuration, it
+ will inherit all of it's settings from the root
logger: a console appender, and threshold set to DEBUG.
+ Therefore, this code will produce the following
output:</p>
+
+ <pre>INFO - This will be logged.</pre>
+ </subsection>
+
+ <subsection name="Appender additivity"
id="Appender_additivity">
+ <p>Appender additivity is a property of loggers
to inherit their parent's appenders. By default all
+ loggers have appender additivity enabled.</p>
+
+ <p>Let's take the following example:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ </logger>
+</configuration>
+]]></pre>
+ <p>Since additivity is enabled by default, the
logger <code>foo</code> will have two linked appenders:
+ A1 which it will inherit from the root logger,
and A2 which is defined for it specifically.</p>
+
+ <p>Therefore, by executing the following
code:</p>
+
+<pre class="prettyprint"><![CDATA[
+$main = Logger::getLogger('foo');
+$main->info('This will be logged twice.');
+]]></pre>
+ <p>The message will be logged twice - once by
A1 and once by A2, producing:</p>
+
+<pre>
+INFO - This will be logged twice.
+INFO - This will be logged twice.
+</pre>
+
+ <h4>Disabling appender additivity</h4>
+
+ <p>Logger's appender additivity can also be
disabled if needed.</p>
+
+ <p>If the <code>foo</code> logger in the
previous example was configured like this:</p>
+
+<pre class="prettyprint"><![CDATA[
+<logger name="foo" additivity="false">
+ <appender_ref ref="A2" />
+</logger>
+]]></pre>
+ <p>Then the logger would not have inherited the
A1 appender from the root logger, and the message
+ would have been logged only once.</p>
+
+ <h4>A more complex example</h4>
+
+ <p>In this example we will look at multiple
loggers making a hierarchy.</p>
+
+ <p>Not to make the example too complex, all
appenders will log to the console. Of course, this doesn't
+ always have to be the case.</p>
+
+ <p>Let's take the following configuration
file:</p>
+
+<pre class="prettyprint"><![CDATA[
+<configuration xmlns="http://logging.apache.org/log4php/";>
+ <appender name="A1" class="LoggerAppenderConsole" />
+ <appender name="A2" class="LoggerAppenderConsole" />
+ <appender name="A3" class="LoggerAppenderConsole" />
+ <appender name="A4" class="LoggerAppenderConsole" />
+
+ <root>
+ <appender_ref ref="A1" />
+ </root>
+ <logger name="foo">
+ <appender_ref ref="A2" />
+ <appender_ref ref="A3" />
+ </logger>
+ <logger name="foo.bar" />
+ <logger name="foo.bar.baz" additivity="false">
+ <appender_ref ref="A4" />
+ </logger>
+</configuration>
+]]></pre>
+ <p>The table below shows how the configuration
is interpreted, and which appenders are inherited:</p>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Logger name</th>
+ <th>Linked
appenders</th>
+ <th>Additivity flag</th>
+ <th>Output targets</th>
+ <th>Comment</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>root</td>
+ <td>A1</td>
+ <td>N/A</td>
+ <td>A1</td>
+ <td>One appender, named
A1, is added to root logger. Any logging requests to root logger
+ will be forwarded only
to that one appender.</td>
+ </tr>
+ <tr>
+ <td>foo</td>
+ <td>A2, A3</td>
+ <td>true</td>
+ <td>A1, A2, A3</td>
+ <td>A logger named
<code>foo</code> is created and two appenders, named A2 and A3, are
+ added to it.
Additionally, because of logger additivity, <code>foo</code> inherits the
+ appender A1 from the
root logger which is it's parent in the logger hierarchy. Therefore
+ logging requests to
this logger will be forwarded to appenders A1, A2 and A3.</td>
+ </tr>
+ <tr>
+ <td>foo.bar</td>
+ <td>none</td>
+ <td>true</td>
+ <td>A1, A2, A3</td>
+ <td>A logger named
<code>foo.bar</code> is created. Because it's name starts with
+ <code>foo</code>, it
will be created as a child of the <code>foo</code> logger.
+ No appenders are added
to <code>foo.bar</code> but it will inherit it's ancestor's
+ appenders: appenders A2
and A3 from <code>foo</code> and A1 from <code>root</code>.
+ Logging requests to
this logger will be forwarded to appenders A1, A2 and A3.</td>
+ </tr>
+ <tr>
+ <td>foo.bar.baz</td>
+ <td>A4</td>
+ <td>false</td>
+ <td>A4</td>
+ <td>Finally, logger
<code>foo.bar.baz</code> is created, and because of it's name it is
+ created as child to
<code>foo.bar</code>. One appender, A4 is added to it. However, since
+ it's additivity flag is
set to <em>false</em>, it will not inherit any appenders from it's
+ ancestors. Logging
requests to this logger will be forwarded only to appender A4.</td>
+ </tr>
+ </tbody>
+
+ </table>
+ </subsection>
+ </section>
+ </body>
+</document>
