<?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>Appenders</title> | |
</properties> | |
<body> | |
<section name="Appenders"> | |
<p>Logging requests can be sent to multiple destinations, such as files, databases, syslog and others. | |
Such destinations are called appenders. Appenders are attached to <a href="loggers.html">loggers</a> | |
and each logger can have multiple attached appenders.</p> | |
<subsection name="Appender reference" id="Appender_reference"> | |
<p>The following appender classes are available:</p> | |
<table> | |
<thead> | |
<tr> | |
<th>Name</th> | |
<th>Destination</th> | |
</tr> | |
</thead> | |
<tbody> | |
<tr> | |
<td><a href="appenders/console.html">LoggerAppenderConsole</a></td> | |
<td>Console, directly to the stdout or stderr stream.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/echo.html">LoggerAppenderEcho</a></td> | |
<td>Console, using the PHP <code>echo</code> command.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/file.html">LoggerAppenderFile</a></td> | |
<td>A file.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/daily-file.html">LoggerAppenderDailyFile</a></td> | |
<td>A file (new file each day).</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/rolling-file.html">LoggerAppenderRollingFile</a></td> | |
<td>A file (new file when a specified size has been reached). </td> | |
</tr> | |
<tr> | |
<td><a href="appenders/mail.html">LoggerAppenderMail</a></td> | |
<td>Sends the log via email. The entire log is sent in one email.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/mongodb.html">LoggerAppenderMongoDB</a></td> | |
<td>MongoDB.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/null.html">LoggerAppenderNull</a></td> | |
<td>Ignores all log events.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/pdo.html">LoggerAppenderPDO</a></td> | |
<td>Database.</td> | |
</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> | |
</tr> | |
<tr> | |
<td><a href="appenders/socket.html">LoggerAppenderSocket</a></td> | |
<td>A network socket.</td> | |
</tr> | |
<tr> | |
<td><a href="appenders/syslog.html">LoggerAppenderSyslog</a></td> | |
<td>Syslog.</td> | |
</tr> | |
</tbody> | |
</table> | |
</subsection> | |
<subsection name="Configuring appenders" id="Configuring_appenders"> | |
<p>The following configuration shows how to configure an appender which logs to a file:</p> | |
<pre class="prettyprint linenums"><![CDATA[ | |
<configuration xmlns="http://logging.apache.org/log4php/"> | |
<appender name="default" class="LoggerAppenderFile"> | |
<layout class="LoggerLayoutSimple" /> | |
<param name="file" value="/var/log/my.log" /> | |
<param name="append" value="true" /> | |
</appender> | |
<root> | |
<appender_ref ref="default" /> | |
</root> | |
</configuration> | |
]]></pre> | |
<p>From the configuration you can see that an appender has the following properties:</p> | |
<ul> | |
<li>A <strong>name</strong> which uniquely identifies it, in this case <em>default</em>.</li> | |
<li>A <strong>class</strong> which specifies which appender class will be used to handle the | |
requests. Since we wish to log to a file, <code>LoggerAppenderFile</code> is used in this case.</li> | |
<li>A <strong>layout</strong> which transforms the logging events to string which can be logged. | |
A layout is required by most appenders, but some do not require it, such as the database appender. | |
If a layout is not defined, the appenders will use a default layout.</li> | |
<li>Zero or more <strong>parameters</strong> which configure the appender | |
behaviour. In this example, the <em>file</em> parameter governs the path to the file which will be | |
used for logging, and <em>append</em> defines that log messages should be appended to the file, | |
instead of truncating it.</li> | |
</ul> | |
</subsection> | |
<subsection name="Linking appenders to loggers"> | |
<p>A logger can be linked to one or more appenders. Also, multiple loggers can share the same | |
appender.</p> | |
<p>Consider the following configuration:</p> | |
<pre class="prettyprint linenums"><![CDATA[ | |
<log4php:configuration xmlns:log4php="http://logging.apache.org/log4php/"> | |
<appender name="primus" class="LoggerAppenderConsole" /> | |
<appender name="secundus" class="LoggerAppenderFile"> | |
<param name="file" value="/var/log/my.log" /> | |
</appender> | |
<logger name="main"> | |
<appender_ref ref="primus" /> | |
<appender_ref ref="secundus" /> | |
</logger> | |
<logger name="alternative"> | |
<appender_ref ref="primus" /> | |
</logger> | |
</log4php:configuration> | |
]]></pre> | |
<p>This configures two appenders, called <em>primus</em> and <em>secundus</em>, and two loggers named | |
<em>main</em> and <em>alternative</em>. The logger <em>main</em> is linked to <em>primus</em> and | |
<em>secundus</em> and will therefore forward logging events to both of them. In other words, | |
it will log both to console and to a file. Logger <em>alternative</em> is only linked to appender | |
<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 linenums"><![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> |