Google Git
Sign in
apache / logging-site / a4f88a44f9ece0268ea2d36ba57a00f2b881cabc / . / content / log4php / 2.2.1 / docs / layouts / pattern.html
blob: 1246ac87a79ad5e2b53baea8d6cdb96942b40608 [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 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>
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="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 &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="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">
<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="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>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>%m%n</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>This is the string which controls formatting and consists of a mix of literal content and
conversion specifiers.</p>
<p>The conversion pattern is closely related to the conversion pattern of the
<a class="externalLink" href="http://www.cplusplus.com/reference/clibrary/cstdio/printf" target="_blank">printf</a>
function in C. It is composed of literal text and format control expressions called conversion
specifiers. You are free to insert any literal text within the conversion pattern.</p>
<p>Each conversion specifier starts with a percent sign (%) and is followed by optional <i>
format modifiers</i> and a <i>conversion character</i>. The recognized conversion specifiers
are:</p>
<table border="0" class="bodyTable">
<thead>
<tr class="a">
<th>Conversion character</th>
<th>Converts to</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td>
<p><tt>%c</tt></p>
<p><tt>%c{&lt;precision&gt;}</tt></p>
</td>
<td>
<p>Name of the Logger object which recieved the logging request.</p>
<p>Optionally, it can be can followed by <i>precision specifier</i>, which is a
decimal constant in brackets. If a precision specifier is given, then only the
corresponding number of right most components of the logger name will be printed.</p>
<p>For example, if the logger is named <tt>foo.bar.Baz</tt>, then <tt>%c</tt>
will be translated to the full logger name, <tt>%c{2}</tt> will be translated to
<tt>bar.Baz</tt>, and <tt>%c{1}</tt> will be translated to <tt>Baz</tt>.
</p>
</td>
</tr>
<tr class="a">
<td>
<p><tt>%C</tt></p>
<p><tt>%C{&lt;precision&gt;}</tt></p>
</td>
<td>
<p>The fully qualified class name of the caller issuing the logging request. Currently,
this will always return &quot;Logger&quot;.</p>
</td>
</tr>
<tr class="b">
<td>
<p><tt>%d</tt></p>
<p><tt>%d{&lt;format&gt;}</tt></p>
</td>
<td>
<p>The date of the logging event.</p>
<p>Optionally, may be followed by a <i>date format specifier</i> enclosed between
braces. The format specifier follows the PHP
<a class="externalLink" href="http://php.net/manual/en/function.date.php">date</a> function. If no date
format specifier is given then ISO8601 format is assumed (Y-m-d H:i:s,u). </p>
<p>For example: <tt>%d{Y-m-d H:i:s}</tt></p>
</td>
</tr>
<tr class="a">
<td><tt>%F</tt></td>
<td>Name of the file from which the logging request was issued.</td>
</tr>
<tr class="b">
<td><tt>%l</tt></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><tt>%L</tt></td>
<td>The line number at which the logging request was issued.</td>
</tr>
<tr class="b">
<td><tt>%m</tt></td>
<td>The message associated with the logging event.</td>
</tr>
<tr class="a">
<td><tt>%n</tt></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="b">
<td><tt>%M</tt></td>
<td>The method or function name from which the logging request was issued.</td>
</tr>
<tr class="a">
<td><tt>%p</tt></td>
<td>The level of the logging event.</td>
</tr>
<tr class="b">
<td><tt>%r</tt></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><tt>%t</tt></td>
<td>The ID of the process that generated the logging event.</td>
</tr>
<tr class="b">
<td><tt>%x</tt></td>
<td>The NDC (Nested Diagnostic Context) associated with the thread that generated the logging event.</td>
</tr>
<tr class="a">
<td><tt>%X{&lt;key&gt;}</tt></td>
<td>
<p>The MDC (Mapped Diagnostic Context) associated with the thread that generated the
logging event.</p>
<p>The X conversion character must be followed by the MDC key in braces. The value in
the MDC corresponding to the key will be output.</p>
</td>
</tr>
<tr class="b">
<td><tt>%%</tt></td>
<td>A single percent sign.</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>All format modifiers are optional, and are placed between the percent sign and the conversion
character.</p>
<p>The first format modifier is the <i>left justification flag</i> which is just the minus (-)
character.</p>
<p>Then comes the <i>&gt;minimum field width</i> modifier. This is an integer that
represents the minimum number of characters to output. If the data item requires fewer characters,
it is padded on either the left or the right until the minimum width is reached. The default is to
pad on the left (right justify) but you can specify right padding with the left justification flag.
The padding character is space. If the data item is larger than the minimum field width, the field
is expanded to accommodate the data. The value is never truncated. </p>
<p>This behavior can be changed using the <i>maximum field width</i> modifier which is designated
by a period (.) followed by an integer. If the data item is longer than the maximum field, then the
extra characters are removed from the beginning of the data item and not from the end. For example,
it the maximum field width is eight and the data item is ten characters long, then the first two
characters of the data item are dropped. This behavior deviates from the printf function in C where
truncation is done from the end. </p>
<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>Justification</th>
<th>Minimum width</th>
<th>Maximum width</th>
<th>Comment</th>
</tr>
</thead>
<tbody>
<tr class="b">
<td align="center"><tt>%c</tt></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"><tt>%20c</tt></td>
<td align="center">right</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"><tt>%-20c</tt></td>
<td align="center">left</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"><tt>%.30c</tt></td>
<td align="center">none</td>
<td align="center">none</td>
<td align="center">30</td>
<td>Truncate from the beginning if the logger name is longer than 30 characters.</td>
</tr>
<tr class="b">
<td align="center"><tt>%20.30c</tt></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 truncate from the beginning.</td>
</tr>
<tr class="a">
<td align="center"><tt>%-20.30c</tt></td>
<td align="center">true</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 truncate from the beginning.</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.</p>
<p>Save the configuration to a file called <tt>layout_pattern.xml</tt>.</p>
<div class="auto-tabs">
<ul>
<li>XML</li>
<li>PHP</li>
</ul>
<div class="tab-content">
<div class="tab-pane">
<div class="prettyprint linenums"><pre>
&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;%d{Y-m-d H:i:s.u} %c %-5p %m%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 class="prettyprint linenums"><pre>
array(
'appenders' =&gt; array(
'default' =&gt; array(
'class' =&gt; 'LoggerAppenderEcho',
'layout' =&gt; array(
'class' =&gt; 'LoggerLayoutPattern',
'params' =&gt; array(
'conversionPattern' =&gt; '%d{Y-m-d H:i:s.u} %c %-5p %m%n'
)
)
)
),
'rootLogger' =&gt; array(
'appenders' =&gt; array('default')
),
)
</pre></div>
</div>
</div>
</div>
<p>Run the following code:</p>
<div class="prettyprint linenums"><pre>
Logger::configure(&quot;layout_pattern.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>Pattern example<a name="Pattern_example"></a></h4>
<p>Conversion pattern: <tt>%d %c %-5p %m%n</tt></p>
<p>Produces the following output:</p>
<div><pre>
2011-09-28 09:29:38,602 myLogger INFO Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2011-09-28 09:29:38,603 myLogger DEBUG Donec a diam lectus.
2011-09-28 09:29:38,604 myLogger WARN Sed sit amet ipsum mauris.
</pre></div>
<p>In this example, <tt>%d</tt> produces the event datetime in default format
(<tt>Y-m-d H:i:s,u</tt>), and <tt>%-5p</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>
</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>
</div>
</body>
</html>