src/site/xdoc/docs/appenders.xml - logging-log4php - Git at Google

 <?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/mail-event.html">LoggerAppenderMailEvent</a></td>
 							<td>Sends the log via email. Each log entry is sent in individual emails.</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>
	<?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/mail-event.html">LoggerAppenderMailEvent</a></td>
	<td>Sends the log via email. Each log entry is sent in individual emails.</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>