directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Directory Server v1.5 > 1.4.4 Configure logging
Date Wed, 28 Oct 2009 20:43:00 GMT
<html>
<head>
    <base href="http://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1519/1/1/_/styles/combined.css?spaceKey=DIRxSRVx11&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background-color: white" bgcolor="white">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
     <h2><a href="http://cwiki.apache.org/confluence/display/DIRxSRVx11/1.4.4+Configure+logging">1.4.4
Configure logging</a></h2>
     <h4>Page <b>edited</b> by             <a href="http://cwiki.apache.org/confluence/display/~seelmann">Stefan
Seelmann</a>
    </h4>
     
          <br/>
     <div class="notificationGreySide">
         <style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color:
#f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td
class='ScrollbarPrevIcon'><a href="/confluence/display/DIRxSRVx11/1.4.3+Adding+your+own+partition+resp.+suffix"><img
border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td
width='33%' class='ScrollbarPrevName'><a href="/confluence/display/DIRxSRVx11/1.4.3+Adding+your+own+partition+resp.+suffix">1.4.3
Adding your own partition resp. suffix</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a
href="/confluence/display/DIRxSRVx11/1.4.+Basic+configuration+tasks"><img border='0'
align='middle' src='/confluence/images/icons/up_16.gif' width='8' height='8'></a></sup><a
href="/confluence/display/DIRxSRVx11/1.4.+Basic+configuration+tasks">1.4. Basic configuration
tasks</a></td><td width='33%' class='ScrollbarNextName'>&nbsp;<a
href="/confluence/display/DIRxSRVx11/1.4.6+Enable+and+disable+anonymous+access">1.4.6 Enable
and disable anonymous access</a></td><td class='ScrollbarNextIcon'><a
href="/confluence/display/DIRxSRVx11/1.4.6+Enable+and+disable+anonymous+access"><img
border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table></div>

<h1><a name="1.4.4Configurelogging-Configurelogging"></a>Configure logging</h1>

<p>In order to detect and analyze problems, adjusting the log level of a server can
be a valuable tool. This section describes how to configure logging within a standalone ApacheDS.
</p>

<div>
<ul>
    <li><a href='#1.4.4Configurelogging-ApacheDSandlogging'>ApacheDS and logging</a></li>
    <li><a href='#1.4.4Configurelogging-Defaultbehaviorafterinstallation'>Default
behavior after installation</a></li>
    <li><a href='#1.4.4Configurelogging-Adjustingloggingtoyourneeds'>Adjusting
logging to your needs</a></li>
    <li><a href='#1.4.4Configurelogging-Exampleconfigurations'>Example configurations</a></li>
    <li><a href='#1.4.4Configurelogging-LogsettingsoftheWindowsdaemonprocess'>Log
settings of the Windows daemon process</a></li>
    <li><a href='#1.4.4Configurelogging-Resources'>Resources</a></li>
</ul></div>

<h2><a name="1.4.4Configurelogging-ApacheDSandlogging"></a>ApacheDS and
logging </h2>

<p>ApacheDS 1.5 uses <a href="http://www.slf4j.org/" title="SLF4j Homepage|www.slf4j.org"
rel="nofollow">SLF4J</a> as its logging solution. This is a simple facade for various
logging APIs. The default for ApacheDS 1.5 is <a href="http://logging.apache.org/log4j/"
title="logging.apache.org" rel="nofollow">log4j</a>.</p>

<h2><a name="1.4.4Configurelogging-Defaultbehaviorafterinstallation"></a>Default
behavior after installation</h2>

<p>By default, ApacheDS writes log files in the directory <em>&lt;APACHDS_HOME&gt;/var/log/</em>.
Besides stdout, a <a href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/RollingFileAppender.html"
title="log4j javadoc" rel="nofollow">RollingFileAppender</a> is used to collect warnings
and errors. It backups the log files when they reach a certain size. </p>

<p>Here is what the default configuration file <em>log4j.properties</em>,
which is located in <em>&lt;APACHDS_HOME&gt;/conf/</em>, looks like.<br/>
The name of the <em>RollingFileAppender</em> is "R":</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
log4j.rootCategory=WARN, stdout, R

log4j.appender.stdout=org.apache.log4j.ConsoleAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout

log4j.appender.R=org.apache.log4j.RollingFileAppender
log4j.appender.R.File=apacheds-rolling.log

log4j.appender.R.MaxFileSize=1024KB
# Keep some backup files
log4j.appender.R.MaxBackupIndex=5

log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n

log4j.appender.stdout.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n

# with these we'll not get innundated when switching to DEBUG
log4j.logger.org.apache.directory.shared.ldap.name=WARN
log4j.logger.org.springframework=WARN
log4j.logger.org.apache.directory.shared.codec=WARN
log4j.logger.org.apache.directory.shared.asn1=WARN
</pre>
</div></div>

<p>In this file "R" is configured like this:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property name </th>
<th class='confluenceTh'> Value in file above </th>
<th class='confluenceTh'> Meaning </th>
</tr>
<tr>
<td class='confluenceTd'> File </td>
<td class='confluenceTd'> apacheds-rolling.log </td>
<td class='confluenceTd'> path to the output log file, in our case relative to <em>var/log</em>
</td>
</tr>
<tr>
<td class='confluenceTd'> MaxFileSize </td>
<td class='confluenceTd'> 1024KB </td>
<td class='confluenceTd'> maximum size that the output file is allowed to reach before
being rolled over to backup files </td>
</tr>
<tr>
<td class='confluenceTd'> MaxBackupIndex </td>
<td class='confluenceTd'> 5 </td>
<td class='confluenceTd'> number of backup files kept </td>
</tr>
<tr>
<td class='confluenceTd'> layout.ConversionPattern </td>
<td class='confluenceTd'> [%d{HH:mm:ss}] %p [%c] - %m%n </td>
<td class='confluenceTd'> format string for logging events </td>
</tr>
</tbody></table>

<p>If the default logging does not meet your requirements, you can easily adjust the
configuration to your needs.</p>

<h2><a name="1.4.4Configurelogging-Adjustingloggingtoyourneeds"></a>Adjusting
logging to your needs</h2>

<h3><a name="1.4.4Configurelogging-Logfilelocation%28wherethelogfilesareplaced%29"></a>Log
file location (where the log files are placed)</h3>

<p>By default the log files are placed at <em>&lt;APACHDS_HOME&gt;/var/log/</em>,
but that can be changed.</p>

<h4><a name="1.4.4Configurelogging-Linux%2FMacOS%2FSolaris"></a>Linux/MacOS/Solaris</h4>
<p>On this systems the location of the log files is configured via an entry in <b>/bin/server.init</b>.
Look for the following lines and change it to your preferences:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>$DAEMON_HOME/apacheds \
...
-outfile $SERVER_HOME/var/log/apacheds-stdout.log \
-errfile $SERVER_HOME/var/log/apacheds-stderr.log \
...    
$APACHEDS_HOME start
</pre>
</div></div>

<h4><a name="1.4.4Configurelogging-Windows"></a>Windows</h4>

<p>On Windows you can use the configuration wizard for the service as shown in the screenshot
above. To adjust the log path you have to adjust the values of <b>Redirect Stdout</b>
and <b>Redirect Stderror</b></p>

<h3><a name="1.4.4Configurelogging-Loglevel%28howdetailedthelogsare%29"></a>Log
level (how detailed the logs are)</h3>

<p>The following log levels from log4j are used for messages within ApacheDS:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Level </th>
<th class='confluenceTh'> Description from log4j documentation </th>
</tr>
<tr>
<td class='confluenceTd'> DEBUG </td>
<td class='confluenceTd'> designates fine-grained informational events that are most
useful to debug an application </td>
</tr>
<tr>
<td class='confluenceTd'> INFO</td>
<td class='confluenceTd'> designates informational messages that highlight the progress
of the application at coarse-grained level </td>
</tr>
<tr>
<td class='confluenceTd'> WARN</td>
<td class='confluenceTd'> designates potentially harmful situations </td>
</tr>
<tr>
<td class='confluenceTd'> ERROR</td>
<td class='confluenceTd'> designates error events that might still allow the application
to continue running </td>
</tr>
<tr>
<td class='confluenceTd'> FATAL </td>
<td class='confluenceTd'> designates very severe error events that will presumably lead
the application to abort </td>
</tr>
</tbody></table>

<p>The default (global) log level in the configuration is <em>WARN</em>.
All messages of level WARN and more severe (ERROR, FATAL) are written to the rolling log file.
The easiest way to get finer log messages is to change it like this</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
log4j.rootCategory=DEBUG, stdout, R
...
</pre>
</div></div> 

<p>These detailed log messages took much file space and time and therefore should only
be enabled globally in order to analyze problems.</p>

<p>It is possible to configure the logging more fine grained by using categories. Within
the default configuration there are some examples:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"> 
...
# with these we'll not get innundated when switching to DEBUG
log4j.logger.org.apache.directory.shared.ldap.name=WARN
log4j.logger.org.springframework=WARN
log4j.logger.org.apache.directory.shared.codec=WARN
log4j.logger.org.apache.directory.shared.asn1=WARN
</pre>
</div></div>

<p>If the global level is switched to DEBUG, these definitions override the setting
with WARN for certain areas and therefore keep the file a little bit smaller. Learn more about
the concept of categories in the <a href="http://logging.apache.org/log4j/docs/manual.html"
rel="nofollow">Short introduction to log4j</a>. </p>

<h3><a name="1.4.4Configurelogging-Formatforlogmessages"></a>Format for
log messages</h3>

<p>The format of each line within a log file is controlled by a pattern. For the <em>RollingFileAppender</em>
in the default configuration it looks like this</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
...
log4j.appender.R.layout=org.apache.log4j.PatternLayout
log4j.appender.R.layout.ConversionPattern=[%d{HH:mm:ss}] %p [%c] - %m%n
...
</pre>
</div></div>

<p>Some examples lines within the log file, formatted with the pattern "[%d{HH:mm:ss}]
%p [%c] - %m%n" are:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
...
[12:29:03] WARN [org.apache.directory.server.core.DefaultDirectoryService]
    - You didn't change the admin password of directory service instance '<span class="code-keyword">default</span>'.
    Please update the admin password as soon as possible to prevent a possible security breach.
...
[12:29:05] INFO [org.apache.directory.server.jndi.ServerContextFactory]
    - Successful bind of an LDAP Service (636) is complete.
[12:29:05] INFO [org.apache.directory.server.Service] - server: started in 6750 milliseconds
...
</pre>
</div></div>

<p>The pattern uses the following conversion characters:</p>

<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Character </th>
<th class='confluenceTh'> Outputs </th>
</tr>
<tr>
<td class='confluenceTd'> %d </td>
<td class='confluenceTd'> date of the logging event in the given format. like "12:29:05"
for %d{HH:mm:ss}  </td>
</tr>
<tr>
<td class='confluenceTd'> %p </td>
<td class='confluenceTd'> priority (level) of the logging event, like "INFO" or "WARN"
</td>
</tr>
<tr>
<td class='confluenceTd'> %c </td>
<td class='confluenceTd'> category of the logging event, like "org.apache.directory.server.Service"
</td>
</tr>
<tr>
<td class='confluenceTd'> %m </td>
<td class='confluenceTd'> application supplied message associated with the logging event
</td>
</tr>
<tr>
<td class='confluenceTd'> %n </td>
<td class='confluenceTd'> platform dependent line separator </td>
</tr>
</tbody></table>

<p>The <a href="http://logging.apache.org/log4j/docs/api/org/apache/log4j/PatternLayout.html"
title="javadoc of log4j PatternLayout class" rel="nofollow">javadoc of log4j</a>
contains a table with all valid %-characters and their meaning.</p>

<p>Simple adjust the pattern in the <em>log4j.properties file</em> to get
the log format of your choice, for instance</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
log4j.appender.R.layout.ConversionPattern=[%d{dd.MM.yyyy HH:mm:ss}] %p: %c{1}.%M() - %m%n
</pre>
</div></div>

<p>leads to messages of this form:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
...
[29.12.2006 13:50:44] INFO: ServerContextFactory.startLDAP0() 
    - Successful bind of an LDAP Service (636) is complete.
[29.12.2006 13:50:44] INFO: Service.init() - server: started in 3016 milliseconds
...
</pre>
</div></div>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Warning</b><br
/><p>"Generating caller location information like with %M or %L is extremely slow.
Its use should be avoided unless execution speed is not an issue." (from the log4j documentation)</p></td></tr></table></div>

<h3><a name="1.4.4Configurelogging-Advancedlog4jconfiguration"></a>Advanced
log4j configuration</h3>

<p>You can take advantage of other features of log4j as well, such as other appenders
like the daily rolling file appender. And you can configure logging to make it easier for
you to view the messages with tools like Log Factor 5 or <a href="http://logging.apache.org/log4j/docs/chainsaw.html"
title="logging.apache.org" rel="nofollow">Chainsaw</a>.</p>

<p>Learn more about log4j and related tools at its <a href="http://logging.apache.org/log4j/docs/index.html"
title="log4j homepage" rel="nofollow">homepage</a>.</p>

<h2><a name="1.4.4Configurelogging-Exampleconfigurations"></a>Example configurations</h2>

<p>The following example could be used to log all incoming search, add, delete, modify
and moddn requests:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
log4j.logger.org.apache.directory.server.ldap.handlers.SearchHandler=DEBUG
log4j.logger.org.apache.directory.server.ldap.handlers.AddHandler=DEBUG
log4j.logger.org.apache.directory.server.ldap.handlers.DeleteHandler=DEBUG
log4j.logger.org.apache.directory.server.ldap.handlers.ModifyHandler=DEBUG
log4j.logger.org.apache.directory.server.ldap.handlers.ModifyDnHandler=DEBUG
</pre>
</div></div>

<h2><a name="1.4.4Configurelogging-LogsettingsoftheWindowsdaemonprocess"></a>Log
settings of the Windows daemon process </h2>

<p>After installation on Windows, you have the option to configure the ApacheDS Windows
Service (you can do this later as well). If you do so, one option pane is dedicated to logging:</p>

<p><img src="/confluence/download/attachments/56702/w32_service_properties.png" align="absmiddle"
border="0" /></p>

<p>You can adjust the logging level and a log path. Note that this is for the daemon
only. The server itself is configured as described above.</p>

<h2><a name="1.4.4Configurelogging-Resources"></a>Resources</h2>

<ul>
	<li><a href="http://logging.apache.org/log4j/docs/manual.html" title="logging.apache.org"
rel="nofollow">Short introduction to log4j</a></li>
</ul>



     </div>
     <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="http://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>

       <a href="http://cwiki.apache.org/confluence/display/DIRxSRVx11/1.4.4+Configure+logging">View
Online</a>
       |
       <a href="http://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=56702&revisedVersion=11&originalVersion=10">View
Change</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message