Google Git
Sign in
apache / logging-site / a4f88a44f9ece0268ea2d36ba57a00f2b881cabc / . / content / log4php / 2.3.0 / docs / layouts / pattern.html
blob: 92639d36fb02d5eda01590aeb4aa5f318b187921 [file] [log] [blame]
<!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 Oct 13, 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>Apache log4php -
LoggerLayoutPattern - 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="20121013" />
<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="http://logging.apache.org/log4php">Apache log4php &trade;</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="external">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">
<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="expanded">
<a href="../../docs/layouts.html" title="Layouts">Layouts</a>
<ul>
<li class="none">
<a href="../../docs/layouts/html.html" title="LoggerLayoutHtml">LoggerLayoutHtml</a>
</li>
<li class="none active">
<a href="../../docs/layouts/pattern.html" title="LoggerLayoutPattern">LoggerLayoutPattern</a>
</li>
<li class="none">
<a href="../../docs/layouts/serialized.html" title="LoggerLayoutSerialized">LoggerLayoutSerialized</a>
</li>
<li class="none">
<a href="../../docs/layouts/simple.html" title="LoggerLayoutSimple">LoggerLayoutSimple</a>
</li>
<li class="none">
<a href="../../docs/layouts/ttcc.html" title="LoggerLayoutTTCC">LoggerLayoutTTCC</a>
</li>
<li class="none">
<a href="../../docs/layouts/xml.html" title="LoggerLayoutXml">LoggerLayoutXml</a>
</li>
</ul>
</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="external" target="_blank" title="Wiki">Wiki</a>
</li>
<li class="none">
<a href="http://blogs.apache.org/logging/" class="external" 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="external" target="_blank" title="Home">Home</a>
</li>
<li class="none">
<a href="http://www.apache.org/foundation/sponsorship.html" class="external" target="_blank" title="Sponsorship">Sponsorship</a>
</li>
<li class="none">
<a href="http://www.apache.org/licenses/" class="external" target="_blank" title="License">License</a>
</li>
<li class="none">
<a href="http://www.apache.org/foundation/thanks.html" class="external" target="_blank" title="Thanks">Thanks</a>
</li>
<li class="none">
<a href="http://www.apachecon.com" class="external" target="_blank" title="Conferences">Conferences</a>
</li>
<li class="none">
<a href="http://www.apache.org/security/" class="external" 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>LoggerLayoutPattern<a name="LoggerLayoutPattern"></a></h2>
<p>LoggerLayoutPattern is a flexible layout configurable via a conversion pattern.</p>
<div class="section"><h3>Parameters<a name="Parameters"></a></h3>
<p>The following parameters are available:</p>
<table border="0" class="bodyTable">
<thead>
<tr class="a">
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td>conversionPattern</td>
<td>string</td>
<td>No</td>
<td>%message%newline</td>
<td>String which controls the output. See full specification below.</td>
</tr>
</tbody>
</table>
<div class="section"><h4>Conversion patterns<a name="Conversion_patterns"></a></h4>
<p><b>Conversion pattern</b> is a string which controls the formatting of logging
events. It controls how logging events will be transformed into strings by the layout.</p>
<p>The conversion pattern is closely related to the conversion pattern of the PHP
<a class="external" href="http://www.php.net/manual/en/function.sprintf.php">sprintf</a> function.
It is composed of literal text and format control expressions called <i>conversion specifiers</i>.
</p>
<p>A conversion specifier begins with a percent sign (%) and is followed by a <i>conversion word</i>.
Some conversion words require one or more <i>options</i> to be given. These are specified in braces after the
conversion word. An example of a conversion specifier is <tt>%message</tt> which will be converted into
the message from the logging event which is being logged.</p>
<p>The recognized conversion specifiers are:</p>
<table border="0" class="table table-bordered">
<thead>
<tr class="a">
<th>Conversion specifier</th>
<th>Converts to</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td>
<p><b>%c</b>{length}</p>
<p><b>%lo</b>{length}</p>
<p><b>%logger</b>{length}</p>
</td>
<td>
<p>Name of the Logger which generated the logging request.</p>
<p>Optionally, a desired output length can be specified. If given, the converter will attempt
to abbreviate the logger name without losing too much information in the process. If
zero length is specified, only the rightmost name fragment will be output.</p>
<p>Specifying the desired length 0 means that only the class name will be returned without
the corresponding namespace.</p>
<p>Several examples of the shortening algorithm in action:</p>
<table border="0" class="table table-bordered table-not-wide">
<thead>
<tr class="a">
<th>Conversion specifier</th>
<th>Logger name</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td>%logger</td>
<td>org\apache\logging\log4php\Foo</td>
<td>org\apache\logging\log4php\Foo</td>
</tr>
<tr class="a">
<td>%logger{0}</td>
<td>org\apache\logging\log4php\Foo</td>
<td>Foo</td>
</tr>
<tr class="b">
<td>%logger{10}</td>
<td>org\apache\logging\log4php\Foo</td>
<td>o\a\l\l\Foo</td>
</tr>
<tr class="a">
<td>%logger{20}</td>
<td>org\apache\logging\log4php\Foo</td>
<td>o\a\l\log4php\Foo</td>
</tr>
<tr class="b">
<td>%logger{25}</td>
<td>org\apache\logging\log4php\Foo</td>
<td>o\a\logging\log4php\Foo</td>
</tr>
<tr class="a">
<td>%logger{30}</td>
<td>org\apache\logging\log4php\Foo</td>
<td>org\apache\logging\log4php\Foo</td>
</tr>
</tbody>
</table>
<p>Note that rightmost segment will never be shortened. It is possible that the
resulting string will be longer than the specified desired length.</p>
<p>For backward compatibility, a dot can be used as a namespace separator, as well as
the backslash.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%C</b>{length}</p>
<p><b>%class</b>{length}</p>
</td>
<td>
<p>The fully qualified class name of the caller issuing the logging request.</p>
<p>Just like <b>%logger</b>, a desired length can be defined as an option.</p>
</td>
</tr>
<tr class="b">
<td>
<p><b>%cookie</b>{key}</p>
</td>
<td>
<p>A value from the $_COOKIE superglobal array corresponding to the given key.</p>
<p>If no key is given, will return all values in key=value format.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%d</b>{pattern}</p>
<p><b>%date</b>{pattern}</p>
</td>
<td>
<p>The date/time of the logging event. Accepts a pattern string as an option. The
pattern syntax is the same as used by the PHP's <tt><a class="external" href="http://php.net/manual/en/function.date.php">date()</a></tt> function.</p>
<p>If no pattern is given, the date format will default to the ISO8601 datetime format,
which is the same as giving the pattern: <tt>c</tt>.</p>
<table border="0" class="bodyTable">
<thead>
<tr class="b">
<th>Conversion specifier</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr class="a">
<td>%d</td>
<td>2011-12-27T12:01:32+01:00</td>
</tr>
<tr class="b">
<td>%date</td>
<td>2011-12-27T12:01:32+01:00</td>
</tr>
<tr class="a">
<td>%date{ISO8601}</td>
<td>2011-12-27T12:01:32+01:00</td>
</tr>
<tr class="b">
<td>%date{Y-m-d H:i:s,u}</td>
<td>2011-12-27 12:01:32,610</td>
</tr>
<tr class="a">
<td>%date{l jS \of F Y h:i:s A}</td>
<td>Tuesday 27th of December 2011 12:01:32 PM</td>
</tr>
</tbody>
</table>
</td>
</tr>
<tr class="a">
<td>
<p><b>%e</b>{key}</p>
<p><b>%env</b>{key}</p>
</td>
<td>
<p>A value from the $_ENV superglobal array corresponding to the given key.</p>
<p>If no key is given, will return all values in key=value format.</p>
</td>
</tr>
<tr class="b">
<td>
<p><b>%ex</b></p>
<p><b>%exception</b></p>
<p><b>%throwable</b></p>
</td>
<td>
<p>The exception associated with the logging event, along with it's stack trace. If
there is no exception, evalutates to an empty string.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%F</b></p>
<p><b>%file</b></p>
</td>
<td>Name of the file from which the logging request was issued.</td>
</tr>
<tr class="b">
<td>
<p><b>%l</b></p>
<p><b>%location</b></p>
</td>
<td>
<p>Location information of the caller which generated the logging event.</p>
<p>Identical to <tt>%C.%M(%F:%L)</tt></p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%L</b></p>
<p><b>%line</b></p>
</td>
<td>The line number at which the logging request was issued.</td>
</tr>
<tr class="b">
<td>
<p><b>%m</b></p>
<p><b>%msg</b></p>
<p><b>%message</b></p>
</td>
<td>The message associated with the logging event.</td>
</tr>
<tr class="a">
<td>
<p><b>%M</b></p>
<p><b>%method</b></p>
</td>
<td>The method or function name from which the logging request was issued.</td>
</tr>
<tr class="b">
<td>
<p><b>%n</b></p>
<p><b>%newline</b></p>
</td>
<td>
<p>A platform dependent line-break character(s).</p>
<p>Note that a line break will not be printed unless explicitely specified.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%p</b></p>
<p><b>%le</b></p>
<p><b>%level</b></p>
</td>
<td>The level of the logging event.</td>
</tr>
<tr class="b">
<td>
<p><b>%r</b></p>
<p><b>%relative</b></p>
</td>
<td>The number of milliseconds elapsed since the start of the application until the creation of the logging event.</td>
</tr>
<tr class="a">
<td>
<p><b>%req</b>{key}</p>
<p><b>%request</b>{key}</p>
</td>
<td>
<p>A value from the $_REQUEST superglobal array corresponding to the given key.</p>
<p>If no key is given, will return all values in key=value format.</p>
</td>
</tr>
<tr class="b">
<td>
<p><b>%s</b>{key}</p>
<p><b>%server</b>{key}</p>
</td>
<td>
<p>A value from the $_SERVER superglobal array corresponding to the given key.</p>
<p>If no key is given, will return all values in key=value format.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%ses</b>{key}</p>
<p><b>%session</b>{key}</p>
</td>
<td>
<p>A value from the $_SESSION superglobal array corresponding to the given key.</p>
<p>If no key is given, will return all values in key=value format.</p>
</td>
</tr>
<tr class="b">
<td>
<p><b>%sid</b></p>
<p><b>%sessionid</b></p>
</td>
<td>
<p>The active session ID, or an empty string if not in session.</p>
<p>Equivalent to calling <tt>session_id()</tt>.</p>
</td>
</tr>
<tr class="a">
<td>
<p><b>%t</b></p>
<p><b>%pid</b></p>
<p><b>%process</b></p>
</td>
<td>The ID of the process that generated the logging event.</td>
</tr>
<tr class="b">
<td>
<p><b>%x</b></p>
<p><b>%ndc</b></p>
</td>
<td>The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.</td>
</tr>
<tr class="a">
<td>
<p><b>%X</b>{key}</p>
<p><b>%mdc</b>{key}</p>
</td>
<td>
<p>A value from the Mapped Diagnostic Context (MDC) corresponding to the given key.</p>
</td>
</tr>
</tbody>
</table>
</div></div>
<div class="section"><h3>Format modifiers<a name="Format_modifiers"></a></h3>
<p>By default the relevant information is output as-is. However, with the aid of format modifiers
it is possible to change the minimum and maximum width and the justifications of each data field.
</p>
<p>Both format modifiers are optional, and are placed between the percent sign (%) and the conversion
word. These are, in order:</p>
<ol style="list-style-type: decimal">
<li>A <b>minimum width specifier</b>, a number which determines the minimum width of the resulting
string. If the resulting string is shorter that the given number, it will be padded with spaces to
the desired length. By default, the string is right-justified (padded from left), but adding a
&quot;-&quot; sign before the specifier will make it left-justified.</li>
<li>A <b>maximum widht specifier</b>, a dot (&quot;.&quot;) followed by a number which determines the maximum
allowed width of the resulting string. If the resulting string is shorter than the given number, it
will be truncated to the maximum width. By default the string is truncated from the right, but
adding a &quot;-&quot; sign before the specifier will cause it to truncate from the left.</li>
</ol>
<p>The following table demonstrates various uses of format modifiers:</p>
<table border="0" class="bodyTable">
<thead>
<tr class="a">
<th>Format modifier</th>
<th>Padding</th>
<th>Trimming</th>
<th>Minimum width</th>
<th>Maximum width</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td align="center"><b>%logger</b></td>
<td align="center">none</td>
<td align="center">none</td>
<td align="center">none</td>
<td align="center">none</td>
<td>Output the logger name as-is.</td>
</tr>
<tr class="a">
<td align="center"><b>%20logger</b></td>
<td align="center">right</td>
<td align="center">none</td>
<td align="center">20</td>
<td align="center">none</td>
<td>Left pad with spaces if the logger name is less than 20 characters long.</td>
</tr>
<tr class="b">
<td align="center"><b>%-20logger</b></td>
<td align="center">left</td>
<td align="center">none</td>
<td align="center">20</td>
<td align="center">none</td>
<td>Right pad with spaces if the logger name is less than 20 characters long.</td>
</tr>
<tr class="a">
<td align="center"><b>%.30logger</b></td>
<td align="center">none</td>
<td align="center">right</td>
<td align="center">none</td>
<td align="center">30</td>
<td>Trim from the end if the logger name is longer than 30 characters.</td>
</tr>
<tr class="b">
<td align="center"><b>%.-30logger</b></td>
<td align="center">none</td>
<td align="center">left</td>
<td align="center">none</td>
<td align="center">30</td>
<td>Trim from the beginning if the logger name is longer than 30 characters.</td>
</tr>
<tr class="a">
<td align="center"><b>%20.30logger</b></td>
<td align="center">right</td>
<td align="center">right</td>
<td align="center">20</td>
<td align="center">30</td>
<td>Left pad with spaces if the logger name is shorter than 20 characters. However, if
the logger name is longer than 30 characters, then trim from the end.</td>
</tr>
<tr class="b">
<td align="center"><b>%-20.30logger</b></td>
<td align="center">left</td>
<td align="center">right</td>
<td align="center">20</td>
<td align="center">30</td>
<td>Right pad with spaces if the logger name is shorter than 20 characters. However, if the
logger name is longer than 30 characters, then trim from the end.</td>
</tr>
</tbody>
</table>
<p>The following table lists a couple of examples for using format modifiers. Note that the square
brackets are added to the conversion pattern to delimit the output.</p>
<table border="0" class="table table-bordered table-striped table-not-wide">
<thead>
<tr class="a">
<th>Conversion pattern</th>
<th>Logger name</th>
<th>Result</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td>[%10logger]</td>
<td>Foo</td>
<td><tt>[&#160;&#160;&#160;&#160;&#160;&#160;&#160;Foo]</tt></td>
<td>Added padding, right aligned.</td>
</tr>
<tr class="a">
<td>[%-10logger]</td>
<td>Foo</td>
<td><tt>[Foo&#160;&#160;&#160;&#160;&#160;&#160;&#160;]</tt></td>
<td>Added padding, left aligned.</td>
</tr>
<tr class="b">
<td>[%.10logger]</td>
<td>org.apache.log4php.Foo</td>
<td><tt>[org.apache]</tt></td>
<td>Trimmed from right.</td>
</tr>
<tr class="a">
<td>[%.-10logger]</td>
<td>org.apache.log4php.Foo</td>
<td><tt>[og4php.Foo]</tt></td>
<td>Trimmed from left.</td>
</tr>
</tbody>
</table>
</div>
<div class="section"><h3>Examples<a name="Examples"></a></h3>
<p>The following configuration configures a <tt>LoggerAppenderEcho</tt> which uses the pattern
layout. All examples will use the same code and configuration, only the conversion pattern will
change from example to example.</p>
<div class="auto-tabs">
<ul>
<li>XML</li>
<li>PHP</li>
</ul>
<div class="tab-content">
<div class="tab-pane">
<div><pre class="prettyprint linenums">
&lt;configuration xmlns=&quot;http://logging.apache.org/log4php/&quot;&gt;
&lt;appender name=&quot;default&quot; class=&quot;LoggerAppenderEcho&quot;&gt;
&lt;layout class=&quot;LoggerLayoutPattern&quot;&gt;
&lt;param name=&quot;conversionPattern&quot; value=&quot;%date %logger %-5level %msg%n&quot; /&gt;
&lt;/layout&gt;
&lt;/appender&gt;
&lt;root&gt;
&lt;appender_ref ref=&quot;default&quot; /&gt;
&lt;/root&gt;
&lt;/configuration&gt;
</pre></div>
</div>
<div class="tab-pane">
<div><pre class="prettyprint linenums">
array(
'appenders' =&gt; array(
'default' =&gt; array(
'class' =&gt; 'LoggerAppenderEcho',
'layout' =&gt; array(
'class' =&gt; 'LoggerLayoutPattern',
'params' =&gt; array(
'conversionPattern' =&gt; '%date %logger %-5level %msg%n'
)
)
)
),
'rootLogger' =&gt; array(
'appenders' =&gt; array('default')
),
)
</pre></div>
</div>
</div>
</div>
<p>Example code:</p>
<div><pre class="prettyprint linenums">
Logger::configure(&quot;config.xml&quot;);
$logger = Logger::getLogger('myLogger');
$logger-&gt;info(&quot;Lorem ipsum dolor sit amet, consectetur adipiscing elit.&quot;);
$logger-&gt;debug(&quot;Donec a diam lectus.&quot;);
$logger-&gt;warn(&quot;Sed sit amet ipsum mauris.&quot;);
</pre></div>
<div class="section"><h4>A simple example<a name="A_simple_example"></a></h4>
<p>Conversion pattern: <tt>%date %logger %-5level %msg%n</tt></p>
<p>Running the example code produces the following output:</p>
<div><pre>
2012-02-27T19:42:17+01:00 myLogger INFO Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2012-02-27T19:42:17+01:00 myLogger DEBUG Donec a diam lectus.
2012-02-27T19:42:17+01:00 myLogger WARN Sed sit amet ipsum mauris.
</pre></div>
<p>In this example, <tt>%date</tt> is converted to the event datetime in default format
(corresponding to the ISO-8601 specification), and <tt>%-5level</tt> produces the event
level right padded to 5 characters. Since longest level name is 5 characters long, this
ensures that the message always starts at the same character position which improves log
readability.</p>
<p>Notice that the newline between logging events (%n) has to be explicitely defined. Otherwise all
logging events will be logged in the same line.</p>
</div><div class="section"><h4>Formatting the date<a name="Formatting_the_date"></a></h4>
<p>The <tt>%date</tt> conversion word can take the desired date format as an option. For example,
if you're European, the d.m.Y date format might be more familiar. Also, adding milliseconds.</p>
<p>Conversion pattern: <tt>%date{d.m.Y H:i:s,u} %logger %-5level %msg%n</tt></p>
<p>Running the example code produces the following output:</p>
<div><pre>
27.02.2012 20:14:41,624 myLogger INFO Lorem ipsum dolor sit amet, consectetur adipiscing elit.
27.02.2012 20:14:41,625 myLogger DEBUG Donec a diam lectus.
27.02.2012 20:14:41,626 myLogger WARN Sed sit amet ipsum mauris.
</pre></div>
</div><div class="section"><h4>Logging HTTP requests<a name="Logging_HTTP_requests"></a></h4>
<p>If log4php is used to log HTTP requests, a pattern like this might be useful:</p>
<p><tt>%date [%pid] From:%server{REMOTE_ADDR}:%server{REMOTE_PORT} Request:[%request] Message: %msg%n</tt></p>
<p>Request <tt>/test.php?foo=bar</tt> it will produce the output similar to:</p>
<div><pre>
2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Donec a diam lectus.
2012-01-02T14:19:33+01:00 [22924] From:194.152.205.71:11257 Request:[foo=bar] Message: Sed sit amet ipsum mauris.
</pre></div>
<p><tt>%server{REMOTE_ADDR}</tt> is equivalent to PHP code <tt>$_SERVER['REMOTE_ADDR']</tt>.</p>
</div><div class="section"><h4>Logging exceptions<a name="Logging_exceptions"></a></h4>
<p>If you wish to log any exception passed to the logging methods, you should add the <tt>%ex</tt>
specifier to the end of your conversion pattern, after <tt>%newline</tt>. This way, if an exception
is loggerd it will be addded to your log below your message.</p>
<p>For example: <tt>%date %logger %message%newline%ex</tt></p>
<p>In the following code, suppose that the work() method can throw an exception. This wolud be a good
way to deal with it:</p>
<div><pre class="prettyprint linenums">
$log = Logger::getLogger('foo');
$log-&gt;info(&quot;Let's try this&quot;);
try
{
$foo = new Foo();
$foo-&gt;work(123);
}
catch(Exception $ex)
{
// Exception is passed as the second parameter
$log-&gt;error(&quot;That didn't work&quot;, $ex);
}
$log-&gt;info(&quot;Done.&quot;);
</pre></div>
<p>If work() throws an exception, your log might look something like this:</p>
<div><pre>
2012-10-08T10:11:18+02:00 foo Let's try this
2012-10-08T10:11:18+02:00 foo That didn't work
exception 'Exception' with message 'Doesn't work' in D:\work\exceptions.php:38
Stack trace:
#0 D:\work\exceptions.php(29): Bar-&gt;work(123)
#1 D:\work\exceptions.php(48): Foo-&gt;work(123)
#2 {main}
2012-10-08T10:11:18+02:00 foo Done.
</pre></div>
<p>The exception, along with the full stack trace ends up in your log. This also works with nested
exceptions, the full stack trace is added.</p>
</div></div>
</div>
</td>
</tr>
</table>
</div>
<div class="footer">
<p>Copyright &#169; 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>
<p>Site powered by <a class="external" href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a>. Icons from
<a class="external" href="http://glyphicons.com/">Glyphicons Free</a>.</p>
</div>
</body>
</html>