| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia at Feb 18, 2012 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title> |
| Loggers - Apache log4php</title> |
| <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css" /> |
| <link rel="stylesheet" href="../css/site.css" type="text/css" /> |
| <script type="text/javascript" src="../js/jquery.min.js"></script> |
| <script type="text/javascript" src="../js/bootstrap.min.js"></script> |
| <script type="text/javascript" src="../js/prettify.min.js"></script> |
| <script type="text/javascript" src="../js/site.js"></script> |
| <meta name="Date-Revision-yyyymmdd" content="20120218" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-26177991-1']); |
| _gaq.push (['_gat._anonymizeIp']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| </script> |
| </head> |
| <body class="composite"> |
| |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="brand" href="#">Apache log4php ™</a> |
| <ul class="nav"> |
| <li> |
| <a href="../index.html" title="About">About</a> |
| </li> |
| <li> |
| <a href="../download.html" title="Download">Download</a> |
| </li> |
| <li> |
| <a href="../install.html" title="Install">Install</a> |
| </li> |
| <li> |
| <a href="../quickstart.html" title="Quick start">Quick start</a> |
| </li> |
| </ul> |
| |
| <!-- Twitter link --> |
| <ul class="nav pull-right"> |
| <li><a href="http://twitter.com/log4php/" class="externalLink">Follow <strong>@log4php</strong></a></li> |
| </ul> |
| |
| <!-- Google CSE Search Box --> |
| <form class="navbar-search pull-right" id="cref" action="http://www.google.com/cse"> |
| <input type="hidden" name="cref" value="http://logging.apache.org/log4php/cse.xml" /> |
| <input class="search-query pull-left" type="text" name="q" size="40" placeholder="Search" /> |
| </form> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container-fluid"> |
| <table class="layout-table"> |
| <tr> |
| <td class="sidebar"> |
| <div class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-home"></i>Apache log4php™</li> |
| <li class="none"> |
| <a href="../index.html" title="About">About</a> |
| </li> |
| <li class="none"> |
| <a href="../download.html" title="Download">Download</a> |
| </li> |
| <li class="none"> |
| <a href="../install.html" title="Install">Install</a> |
| </li> |
| <li class="none"> |
| <a href="../changelog.html" title="Changelog">Changelog</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-book"></i>Documentation</li> |
| <li class="none"> |
| <a href="../quickstart.html" title="Quick start">Quick start</a> |
| </li> |
| <li class="none"> |
| <a href="../docs/introduction.html" title="Introduction">Introduction</a> |
| </li> |
| <li class="none"> |
| <a href="../docs/configuration.html" title="Configuration">Configuration</a> |
| </li> |
| <li class="none active"> |
| <a href="../docs/loggers.html" title="Loggers">Loggers</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../docs/appenders.html" title="Appenders">Appenders</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../docs/layouts.html" title="Layouts">Layouts</a> |
| </li> |
| <li class="none"> |
| <a href="../docs/filters.html" title="Filters">Filters</a> |
| </li> |
| <li class="none"> |
| <a href="../docs/renderers.html" title="Renderers">Renderers</a> |
| </li> |
| <li class="none"> |
| <a href="../apidocs/index.html" title="API documentation">API documentation</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-user"></i>Community</li> |
| <li class="none"> |
| <a href="../volunteering.html" title="Volunteering">Volunteering</a> |
| </li> |
| <li class="none"> |
| <a href="../contributingpatches.html" title="Contributing Patches">Contributing Patches</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://wiki.apache.org/logging-log4php" class="externalLink" target="_blank" title="Wiki">Wiki</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://blogs.apache.org/logging/" class="externalLink" target="_blank" title="Blog">Blog</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-info-sign"></i>Project Information</li> |
| <li class="none"> |
| <a href="../integration.html" title="Continuous Integration">Continuous Integration</a> |
| </li> |
| <li class="none"> |
| <a href="../source-repository.html" title="Source Repository">Source Repository</a> |
| </li> |
| <li class="none"> |
| <a href="../dependencies.html" title="Dependencies">Dependencies</a> |
| </li> |
| <li class="none"> |
| <a href="../license.html" title="Project License">Project License</a> |
| </li> |
| <li class="none"> |
| <a href="../team-list.html" title="Project Team">Project Team</a> |
| </li> |
| <li class="none"> |
| <a href="../issue-tracking.html" title="Issue Tracking">Issue Tracking</a> |
| </li> |
| <li class="none"> |
| <a href="../mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-cog"></i>Project Reports</li> |
| <li class="none"> |
| <a href="../changes-report.html" title="Changes Report">Changes Report</a> |
| </li> |
| <li class="none"> |
| <a href="../surefire-report.html" title="Surefire Report">Surefire Report</a> |
| </li> |
| <li class="none"> |
| <a href="../rat-report.html" title="RAT Report">RAT Report</a> |
| </li> |
| <li class="none"> |
| <a href="../coverage-report/index.html" title="Code Coverage">Code Coverage</a> |
| </li> |
| </ul> |
| <ul class="nav nav-list"> |
| <li class="nav-header"><i class="icon-heart"></i>Apache</li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apache.org" class="externalLink" target="_blank" title="Home">Home</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" target="_blank" title="Sponsorship">Sponsorship</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apache.org/licenses/" class="externalLink" target="_blank" title="License">License</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apache.org/foundation/thanks.html" class="externalLink" target="_blank" title="Thanks">Thanks</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apachecon.com" class="externalLink" target="_blank" title="Conferences">Conferences</a> |
| </li> |
| <li class="none"> |
| |
| |
| <a href="http://www.apache.org/security/" class="externalLink" target="_blank" title="Security">Security</a> |
| </li> |
| </ul> |
| </div> |
| <div id="poweredBy"> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| </div> |
| </td> |
| <td class="content"> |
| <!-- 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. --> |
| |
| |
| <div class="section"><h2>Loggers<a name="Loggers"></a></h2> |
| |
| <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 <tt>getLogger()</tt> method on the Logger object |
| and providing the name of the logger. For example, to create a logger named <tt>foo</tt>:</p> |
| |
| <div class="prettyprint"><pre>$logger = Logger::getLogger('foo');</pre></div> |
| |
| <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 <tt>info()</tt> creates a logging request of level |
| <tt>INFO</tt>. For example:</p> |
| |
| <div class="prettyprint"><pre>$logger->info("This is the message to be logged.");</pre></div> |
| |
| <p>Loggers by themselves do not define where these messages will be logged. For that you need to assign |
| one or more <a href="./appenders.html">appenders</a> to the logger.</p> |
| |
| <a name="Logger_threshold"></a><div class="section"><h3 id="Logger_threshold">Logger threshold</h3> |
| <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 <tt>INFO</tt> means that logging requests with levels |
| <tt>TRACE</tt> and <tt>DEBUG</tt> will not be logged by this logger.</p> |
| |
| <p>An example of setting the root logger threshold to <tt>INFO</tt>:</p> |
| |
| <div class="prettyprint linenums"><pre> |
| <configuration xmlns="http://logging.apache.org/log4php/"> |
| <appender name="default" class="LoggerAppenderConsole" /> |
| <root> |
| <level value="info" /> |
| <appender_ref ref="default" /> |
| </root> |
| </configuration> |
| </pre></div> |
| |
| <p>If not explicitly configured, loggers will have their threshold level set to <tt>DEBUG</tt> by |
| default.</p> |
| </div> |
| |
| <a name="Configuring_loggers"></a><div class="section"><h3 id="Configuring_loggers">Configuring loggers</h3> |
| <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> |
| |
| <div class="prettyprint linenums"><pre> |
| <configuration xmlns="http://logging.apache.org/log4php/"> |
| <appender name="default" class="LoggerAppenderConsole" /> |
| <root> |
| <level value="info" /> |
| <appender_ref ref="default" /> |
| </root> |
| </configuration> |
| </pre></div> |
| <p>This configuration adds the <tt>default</tt> appender to the root logger, and sets it's |
| <a href="#Logger_threshold">threshold level</a> to <tt>INFO</tt>.</p> |
| |
| <p>It is also possible to configure individual named loggers. For example, let's configure the |
| <tt>foo</tt> logger, used in the example above, and set it's threshold to WARN:</p> |
| |
| <div class="prettyprint linenums"><pre> |
| <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></div> |
| </div> |
| |
| <a name="Logger_hierarchy"></a><div class="section"><h3 id="Logger_hierarchy">Logger hierarchy</h3> |
| <p>Loggers follow a parent-child relationship pattern which is implemented by using a naming pattern. |
| A logger is said to be an <i>ancestor</i> of another logger if its name followed by a dot is a |
| prefix of the <i>descendant</i> logger name. A logger is said to be a <i>parent</i> of a |
| <i>child</i> logger if there are no ancestors between itself and the descendant logger.</p> |
| |
| <p>For example, the logger named <tt>foo</tt> is a parent of the logger named <tt>foo.bar</tt>. |
| Similarly, <tt>org</tt> is a parent of <tt>org.apache</tt> and an ancestor of |
| <tt>org.apache.logging</tt>. 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 <tt>Logger::getRootLogger()</tt> method retrieves the root logger. |
| All other loggers are instantiated and retrieved with the <tt>Logger::getLogger($name)</tt> |
| 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> |
| </div> |
| |
| <a name="Logger_inheritance"></a><div class="section"><h3 id="Logger_inheritance">Logger inheritance</h3> |
| <p>The threshold level and appenders are inherited from the parent to the child loggers.</p> |
| |
| <p>For example examine the following configuration:</p> |
| |
| <div class="prettyprint linenums"><pre> |
| <configuration xmlns="http://logging.apache.org/log4php/"> |
| <appender name="default" class="LoggerAppenderConsole" /> |
| <root> |
| <level value="debug" /> |
| <appender_ref ref="default" /> |
| </root> |
| </configuration> |
| </pre></div> |
| |
| <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> |
| |
| <div class="prettyprint linenums"><pre> |
| $main = Logger::getLogger('main'); |
| $main->trace('This will not be logged.'); |
| $main->info('This will be logged.'); |
| </pre></div> |
| <p>A logger named <tt>main</tt> 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> |
| |
| <div><pre>INFO - This will be logged.</pre></div> |
| </div> |
| |
| <a name="Appender_additivity"></a><div class="section"><h3 id="Appender_additivity">Appender additivity</h3> |
| <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> |
| |
| <div class="prettyprint linenums"><pre> |
| <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></div> |
| <p>Since additivity is enabled by default, the logger <tt>foo</tt> 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> |
| |
| <div class="prettyprint linenums"><pre> |
| $main = Logger::getLogger('foo'); |
| $main->info('This will be logged twice.'); |
| </pre></div> |
| <p>The message will be logged twice - once by A1 and once by A2, producing:</p> |
| |
| <div><pre> |
| INFO - This will be logged twice. |
| INFO - This will be logged twice. |
| </pre></div> |
| |
| <div class="section"><h4>Disabling appender additivity<a name="Disabling_appender_additivity"></a></h4> |
| |
| <p>Logger's appender additivity can also be disabled if needed.</p> |
| |
| <p>If the <tt>foo</tt> logger in the previous example was configured like this:</p> |
| |
| <div class="prettyprint linenums"><pre> |
| <logger name="foo" additivity="false"> |
| <appender_ref ref="A2" /> |
| </logger> |
| </pre></div> |
| <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> |
| |
| </div><div class="section"><h4>A more complex example<a name="A_more_complex_example"></a></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> |
| |
| <div class="prettyprint linenums"><pre> |
| <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></div> |
| <p>The table below shows how the configuration is interpreted, and which appenders are inherited:</p> |
| |
| <table border="0" class="bodyTable"> |
| <thead> |
| <tr class="a"> |
| <th>Logger name</th> |
| <th>Linked appenders</th> |
| <th>Additivity flag</th> |
| <th>Output targets</th> |
| <th>Comment</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="b"> |
| <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 class="a"> |
| <td>foo</td> |
| <td>A2, A3</td> |
| <td>true</td> |
| <td>A1, A2, A3</td> |
| <td>A logger named <tt>foo</tt> is created and two appenders, named A2 and A3, are |
| added to it. Additionally, because of logger additivity, <tt>foo</tt> 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 class="b"> |
| <td>foo.bar</td> |
| <td>none</td> |
| <td>true</td> |
| <td>A1, A2, A3</td> |
| <td>A logger named <tt>foo.bar</tt> is created. Because it's name starts with |
| <tt>foo</tt>, it will be created as a child of the <tt>foo</tt> logger. |
| No appenders are added to <tt>foo.bar</tt> but it will inherit it's ancestor's |
| appenders: appenders A2 and A3 from <tt>foo</tt> and A1 from <tt>root</tt>. |
| Logging requests to this logger will be forwarded to appenders A1, A2 and A3.</td> |
| </tr> |
| <tr class="a"> |
| <td>foo.bar.baz</td> |
| <td>A4</td> |
| <td>false</td> |
| <td>A4</td> |
| <td>Finally, logger <tt>foo.bar.baz</tt> is created, and because of it's name it is |
| created as child to <tt>foo.bar</tt>. One appender, A4 is added to it. However, since |
| it's additivity flag is set to <i>false</i>, 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> |
| </div></div> |
| </div> |
| |
| |
| </td> |
| </tr> |
| </table> |
| </div> |
| |
| <div class="footer"> |
| <p>Copyright © 2012 |
| <a href="http://www.apache.org">Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License, Version 2.0</a>. |
| Please read the <a href="../privacy.html">Privacy policy</a></p> |
| <p>Apache log4php, Apache, log4php, the Apache feather logo, the Apache Logging Services project logo and the Built by |
| Maven logo are trademarks of The Apache Software Foundation.</p> |
| </div> |
| </body> |
| </html> |
