| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| |
| <!-- Content Stylesheet for Site --> |
| |
| |
| |
| |
| |
| <!-- start the processing --> |
| <!-- ====================================================================== --> |
| <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! --> |
| <!-- Main Page Section --> |
| <!-- ====================================================================== --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/> |
| |
| <meta name="author" value="Ceki Gulcu"> |
| <meta name="email" value="cgu@apache.org"> |
| |
| |
| |
| |
| <link href="./css/site.css" rel="stylesheet" type="text/css"/> |
| |
| |
| <title>Log4j project - Frequently Asked Questions about log4j</title> |
| </head> |
| |
| <body bgcolor="#ffffff" text="#000000" link="#525D76"> |
| <!-- START Header table --> |
| <table class="banner" border="0"> |
| <tr> |
| <td valign="top"> |
| <a href="http://logging.apache.org/"> |
| <img src="http://logging.apache.org/images/ls-logo.jpg" border="0"/> |
| </a> |
| </td> |
| <td align="right"> |
| <a href="http://logging.apache.org/log4j/docs/"> |
| <img src="./images/logo.jpg" alt="The log4j project" border="0"/> |
| </a> |
| </td> |
| </tr> |
| </table> |
| <!-- END Header table --> |
| |
| <div class="centercol"> |
| <hr noshade="" size="1"/> |
| |
| <center> |
| <h2>Frequently Asked Questions about log4j</h2> |
| <h3>Ceki Gülcü, Paul Smith, Chris Taylor<br /> |
| May 2002, last updated on September 15th, 2004</h3> |
| </center> |
| |
| |
| |
| <br/> |
| <div class="index-faqSection"> |
| Section 1. <a href="#1"> Generalities</a> |
| </div> |
| |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.1</td> |
| <td><a href="#1.1">What is log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.2</td> |
| <td><a href="#1.2">Is log4j a reliable logging system?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.3</td> |
| <td><a href="#1.3">What are the prerequisites for log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.4</td> |
| <td><a href="#1.4">What are the features of log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.5</td> |
| <td><a href="#1.5">Is there example code for using log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.6</td> |
| <td><a href="#1.6">What documentation should I read to learn more about |
| log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.7</td> |
| <td><a href="#1.7">Is log4j thread-safe?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.8</td> |
| <td><a href="#1.8">What does log output look like?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 1.9</td> |
| <td><a href="#1.9">Why should I use log4j when JDK 1.4 already ships with a |
| logging API?</a></td> |
| </table> |
| <br/> |
| <div class="index-faqSection"> |
| Section 2. <a href="#2"> Using log4j</a> |
| </div> |
| |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.1</td> |
| <td><a href="#2.1">What are <em>Loggers</em>?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.2</td> |
| <td><a href="#2.2">How can I change log behavior at runtime?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.3</td> |
| <td><a href="#2.3">What is the fastest way of (not) logging?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.4</td> |
| <td><a href="#2.4"> Are there any suggested ways for naming loggers?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.5</td> |
| <td><a href="#2.5">How do I get the fully-qualified name of a class in a static block?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.6</td> |
| <td><a href="#2.6">Can the log output format be customized? </a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.7</td> |
| <td><a href="#2.7">What are the configurable options for <code>FooBarAppender</code>?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.8</td> |
| <td><a href="#2.8">What is the recommended way of migrating from |
| java.util.logging to log4j?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.9</td> |
| <td><a href="#2.9">Is it possible to direct log output to |
| different appenders by level? </a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.10</td> |
| <td><a href="#2.10">What does the Windows NT Event Viewer complain about |
| missing descriptions for my event messages when I use the |
| <code>NTEventLogAppender</code>?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.11</td> |
| <td><a href="#2.11">Why can't I map my logger names to the loggers that |
| appear in the NT Event Log when I use the |
| NTEventLogAppender?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 2.12</td> |
| <td><a href="#2.12">Are there suggested approaches for logging in JSP pages?</a></td> |
| </table> |
| <br/> |
| <div class="index-faqSection"> |
| Section 3. <a href="#3"> Advanced questions</a> |
| </div> |
| |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.1</td> |
| <td><a href="#3.1">Can the outputs of multiple client request go to |
| different log files?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.2</td> |
| <td><a href="#3.2">Logger instances seem to be create only. Why isn't |
| there a method to remove logger instances?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.3</td> |
| <td><a href="#3.3">How do I get multiple process to log to the same file?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.4</td> |
| <td><a href="#3.4">How about the timesamps of events generated by multiple |
| processes across multiple hosts (possibly across multiple |
| timezones)? |
| </a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.5</td> |
| <td><a href="#3.5">Why can't log4j find my properties file in a J2EE or WAR |
| application?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 3.6</td> |
| <td><a href="#3.6">Is there a way to get log4j to automatically reload a |
| configuration file if it changes?</a></td> |
| </table> |
| <br/> |
| <div class="index-faqSection"> |
| Section 4. <a href="#4"> Contributing to the project</a> |
| </div> |
| |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 4.1</td> |
| <td><a href="#4.1">Why should I donate my extensions to log4j back to the |
| project? |
| </a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 4.2</td> |
| <td><a href="#4.2">What should I keep in mind when contributing code?</a></td> |
| </table> |
| <table class="index-question"> |
| <td nowrap="true" valign="top">Question 4.3</td> |
| <td><a href="#4.3">How can I contribute a new question/answer to this |
| document?</a></td> |
| </table> |
| <hr/> |
| |
| |
| <div class="faqSection"> |
| <a name="1">Section 1.</a> Generalities |
| </div> |
| |
| <p>This section contains general questions about log4j.</p> |
| |
| <div class="question"> |
| <a name="1.1">1.1 What is log4j?</a> |
| </div> |
| |
| <p>log4j is a tool to help the programmer output log statements to a |
| variety of output targets. |
| </p> |
| |
| <p>In case of problems with an application, it is helpful to |
| enable logging so that the problem can be located. With log4j |
| it is possible to enable logging at runtime without modifying |
| the application binary. The log4j package is designed so that |
| log statements can remain in <i>shipped</i> code without |
| incurring a high performance cost. It follows that the speed |
| of logging (or rather not logging) is capital. |
| </p> |
| |
| <p>At the same time, log output can be so voluminous that it quickly |
| becomes overwhelming. One of the distinctive features of log4j is the |
| notion of <i>hierarchical loggers</i>. Using loggers it is |
| possible to selectively control which log statements are output at |
| arbitrary granularity. |
| </p> |
| |
| <p>log4j is designed with two three goals in mind: |
| reliability, speed and flexibility. There is a tight balance |
| between these requirements. We believe that log4j strikes the |
| right balance. |
| </p> |
| |
| <div class="question"> |
| <a name="1.2">1.2 Is log4j a reliable logging system?</a> |
| </div> |
| |
| <p>No. log4j is not reliable. It is a best-effort |
| <em>fail-stop</em> logging system. |
| </p> |
| |
| <p>By fail-stop, we mean that log4j will not throw unexpected |
| exceptions at run-time potentially causing your application to |
| crash. <b>If for any reason, log4j throws an uncaught exception, |
| please send an email to the <a href="mailto:log4j-user@logging.apache.org">log4j-user@logging.apache.org</a> |
| mailing list</b>. Uncaught exceptions are handled as serious bugs |
| requiring immediate attention. |
| </p> |
| |
| <p>Moreover, log4j will not revert to System.out or System.err |
| when its designated output stream is not opened, is not writable or |
| becomes full. This avoids corrupting an otherwise working program by |
| flooding the user's terminal because logging fails. However, log4j |
| will output a single message to System.err indicating that logging can |
| not be performed. |
| </p> |
| |
| <div class="question"> |
| <a name="1.3">1.3 What are the prerequisites for log4j?</a> |
| </div> |
| |
| <ul> |
| <li><p>Log4j versions upto and including 1.2.8 are |
| compatible with JDK 1.1.x and later. Log4j version 1.3 will |
| be compatilble with JDK 1.2 and later. |
| </p></li> |
| |
| <li><p>The DOMConfigurator is based on the DOM Level 1 |
| API. The DOMConfigurator.configure(Element) method will work |
| with any XML parser that will pass it a DOM tree. |
| </p> |
| <p>The DOMConfigurator.configure(String filename) method and its |
| variants require a JAXP compatible XML parser, for example <a href="http://xml.apache.org/">Xerces</a> or Sun's |
| parser. Compiling the DOMConfigurator requires the presence of a |
| JAXP parser in the classpath. |
| </p> |
| </li> |
| |
| <li><p>The <code>org.apache.log4j.net.SMTPAppender</code> |
| relies on the <a href="http://java.sun.com/products/javamail/">JavaMail |
| API</a>. It has been tested with JavaMail API version |
| 1.2. The JavaMail API requires the <a href="http://java.sun.com/beans/glasgow/jaf.html">JavaBeans |
| Activation Framework</a> package. |
| </p></li> |
| |
| <li><p>The <code>org.apache.log4j.net.JMSAppender</code> |
| requires the presence of the JMS API as well as JNDI. |
| </p></li> |
| |
| <li><p>log4j test code relies on the <a href="http://www.junit.org">JUnit</a> testing framework. |
| </p></li> |
| </ul> |
| |
| <div class="question"> |
| <a name="1.4">1.4 What are the features of log4j?</a> |
| </div> |
| |
| <ul> |
| |
| <li><p>log4j is optimized for speed.</p></li> |
| |
| <li><p>log4j is based on a named logger hierarchy.</p></li> |
| |
| <li><p>log4j is fail-stop. However, altough it certainly |
| strives to ensure delivery, log4j does not guarantee that |
| each log statement will be delivered to its destination. |
| </p></li> |
| |
| <li><p>log4j is thread-safe.</p></li> |
| |
| <li><p>log4j is not restricted to a predefined set of |
| facilities.</p></li> |
| |
| <li><p>Logging behavior can be set at runtime using a |
| configuration file. Configuration files can be property |
| files or in XML format. </p></li> |
| |
| <li><p>log4j is designed to handle Java Exceptions from the |
| start.</p></li> |
| |
| <li><p>log4j can direct its output to a file, the console, |
| an <code>java.io.OutputStream</code>, |
| <code>java.io.Writer</code>, a remote server using TCP, a |
| remote Unix Syslog daemon, to a remote listener using JMS, |
| to the NT EventLog or even send e-mail. </p></li> |
| |
| <li><p>log4j uses 6 levels, namely TRACE, DEBUG, INFO, WARN, |
| ERROR and FATAL. </p></li> |
| |
| <li><p>The format of the log output can be easily changed by |
| extending the <code>Layout</code> |
| class. </p></li> |
| |
| <li><p>The target of the log output as well as the writing |
| strategy can be altered by implementations of the |
| <code>Appender</code> interface. </p></li> |
| |
| <li><p>log4j supports multiple output appenders per logger. |
| </p></li> |
| |
| <li><p>log4j supports internationalization.</p></li> |
| </ul> |
| |
| <div class="question"> |
| <a name="1.5">1.5 Is there example code for using log4j?</a> |
| </div> |
| |
| <p>See the <code>examples/</code> directory.</p> |
| |
| <div class="question"> |
| <a name="1.6">1.6 What documentation should I read to learn more about |
| log4j?</a> |
| </div> |
| |
| <p>Make sure to read the <a href="manual.html">short |
| manual</a>. It is also recommended to you read <a href="https://www.qos.ch/shop/products/log4j/log4j-Manual.jsp">The complete |
| log4j manual</a> which is much more detailed and up to |
| date. Both documents were written by Ceki Gülcü. |
| </p> |
| |
| <div class="question"> |
| <a name="1.7">1.7 Is log4j thread-safe?</a> |
| </div> |
| |
| <p>Yes, log4j is thread-safe. Log4j components are designed to |
| be used in heavily multithreaded systems.</p> |
| |
| <div class="question"> |
| <a name="1.8">1.8 What does log output look like?</a> |
| </div> |
| |
| |
| <p>The log output can be customized in many ways. Moreover, |
| one can completely override the output format by implementing |
| one's own Layout. |
| </p> |
| |
| <p>Here is an example output using <em>PatternLayout</em> with |
| the conversion pattern <b>"%r [%t] %-5p %c{2} %x - %m%n"</b> |
| </p> |
| |
| <pre class="screen_output"> |
| 176 [main] INFO examples.Sort - Populating an array of 2 elements in reverse order. |
| 225 [main] INFO examples.SortAlgo - Entered the sort method. |
| 262 [main] DEBUG SortAlgo.OUTER i=1 - Outer loop. |
| 276 [main] DEBUG SortAlgo.SWAP i=1 j=0 - Swapping intArray[0] = 1 and intArray[1] = 0 |
| 290 [main] DEBUG SortAlgo.OUTER i=0 - Outer loop. |
| 304 [main] INFO SortAlgo.DUMP - Dump of interger array: |
| 317 [main] INFO SortAlgo.DUMP - Element [0] = 0 |
| 331 [main] INFO SortAlgo.DUMP - Element [1] = 1 |
| 343 [main] INFO examples.Sort - The next log statement should be an error message. |
| 346 [main] ERROR SortAlgo.DUMP - Tried to dump an uninitialized array. |
| at org.log4j.examples.SortAlgo.dump(SortAlgo.java:58) |
| at org.log4j.examples.Sort.main(Sort.java:64) |
| 467 [main] INFO examples.Sort - Exiting main method. |
| </pre> |
| |
| <p>The first field is the number of milliseconds elapsed since |
| the start of the program. The second field is the thread |
| outputting the log statement. The third field is the level of |
| the log statement. The fourth field is the rightmost two |
| components of the logger making the log request. The fifth |
| field (just before the '-') is the <em>nested diagnostic |
| context</em> (NDC). Note the nested diagnostic context may be |
| empty as in the first two statements. The text after the '-' |
| is the message of the statement. |
| </p> |
| |
| <div class="question"> |
| <a name="1.9">1.9 Why should I use log4j when JDK 1.4 already ships with a |
| logging API?</a> |
| </div> |
| |
| <p> |
| Although both APIs are conceptually similar, the log4j API is |
| significantly more flexible and offers many more features, too |
| numerous to be listed here. You will discover that the |
| additional features and flexibility turn out to be |
| indispensable in the context of a mission-critical |
| application. |
| </p> |
| |
| <p>The open and collaborative way in which log4j is developped |
| ensures that it continues to preserve and even widen its |
| competitive edge. At some point, input from bright developpers |
| from all over the world is bound to make a difference. |
| </p> |
| |
| <div class="faqSection"> |
| <a name="2">Section 2.</a> Using log4j |
| </div> |
| |
| <p>This section contains answers to questions encountered while |
| using log4j.</p> |
| |
| <div class="question"> |
| <a name="2.1">2.1 What are <em>Loggers</em>?</a> |
| </div> |
| |
| <p>Lggers lie at the heart of log4j. Loggers define a hierarchy and give |
| the programmer <em>run-time</em> control on which statements are |
| printed or not. |
| </p> |
| |
| <p>Loggers are assigned levels. A log statement is printed |
| depending on its level <em>and</em> its logger. |
| </p> |
| |
| <p>Make sure to read the <a href="manual.html">log4j manual</a> |
| for more information. |
| </p> |
| |
| <div class="question"> |
| <a name="2.2">2.2 How can I change log behavior at runtime?</a> |
| </div> |
| |
| <p>Log behavior can be set using configuration files which are parsed |
| at runtime. Using configuration files the programmer can define |
| loggers and set their levels. |
| </p> |
| |
| <p>The <code>PropertyConfigurator</code> defines a particular format |
| of a configuration file. See also the <code>examples/Sort.java</code> |
| example and associated configuration files. |
| </p> |
| |
| <p>Configuration files can be specified in XML. See |
| <code>log4j.dtd</code> and |
| <code>org.log4j.xml.DOMConfigurator</code> for more details. |
| </p> |
| |
| <p>See the various Layout and Appender components for specific |
| configuration options. |
| </p> |
| |
| <p>In addition to configuration files, the user may disable all |
| messages belonging to a set of levels. See next item. |
| </p> |
| |
| <div class="question"> |
| <a name="2.3">2.3 What is the fastest way of (not) logging?</a> |
| </div> |
| |
| |
| <p> For some logger <code>l</code>, writing, |
| </p> |
| |
| <pre class="source"> |
| l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); |
| </pre> |
| |
| <p>incurs the cost of constructing the message parameter, that is |
| converting both integer <code>i</code> and <code>entry[i]</code> to a |
| String, and concatenating intermediate strings. This, regardless of |
| whether the message will be logged or not. |
| </p> |
| |
| <p>If you are worried about speed, then write</p> |
| <pre class="source"> |
| if(l.isDebugEnabled()) { |
| l.debug("Entry number: " + i + " is " + String.valueOf(entry[i])); |
| } |
| </pre> |
| |
| <p>This way you will not incur the cost of parameter |
| construction if debugging is disabled for logger |
| <code>l</code>. On the other hand, if the logger is debug |
| enabled, you will incur the cost of evaluating whether the |
| logger is enabled or not, twice: once in |
| <code>debugEnabled</code> and once in <code>debug</code>. |
| This is an insignificant overhead since evaluating a logger |
| takes less than 1% of the time it takes to actually log a |
| statement. |
| </p> |
| |
| <h3>Better alternative based on message patterns</h3> |
| <p>As of log4j version 1.3, there exists a significantly more |
| convenient alternative based on message patterns. Assuming |
| <code>entry</code> is an object, you can write: |
| </p> |
| |
| <p class="source"> |
| l.debug("The new entry is {}.", entry); |
| </p> |
| |
| <p>After evaluting whether to log or not, and only if the |
| decision is positive, will the logger instace format the |
| message and replace the '{}' pair with the string value of |
| <code>entry</code>. In other words, the paramerized form does |
| not incur the cost of parameter construction in case the log |
| statement is disabled. |
| </p> |
| |
| <p>Thus, the following two lines will yield the exact same |
| output. However, the second form will perform at least 30 |
| (thirty) times faster in case of a <em>disabled</em> logging |
| statement. |
| </p> |
| |
| <p class="source"> |
| l.debug("The new entry is "+entry+"."); <br /> |
| l.debug("The new entry is {}.", entry); |
| </p> |
| |
| <p>A two argument variant is also availalble. For example, you |
| can write: |
| </p> |
| <p class="source"> |
| l.debug("The new entry is {}. It replaces {}.", entry, oldEntry); |
| </p> |
| |
| |
| |
| |
| <div class="question"> |
| <a name="2.4">2.4 Are there any suggested ways for naming loggers?</a> |
| </div> |
| |
| |
| |
| <p>Yes, there are.</p> |
| |
| <p>You can name loggers by <strong>locality</strong>. It turns out |
| that instantiating a logger in each class, with the logger name |
| equal to the fully-qualified name of the class, is a useful and |
| straightforward approach of defining loggers. This approach has |
| many benefits: |
| </p> |
| |
| <ul> |
| <li>It is very simple to implement.</li> |
| |
| <li>It is very simple to explain to new developers.</li> |
| |
| <li>It automatically mirrors your application's own modular design. |
| </li> |
| <li>It can be further refined at will.</li> |
| |
| <li>Printing the logger automatically gives information on the locality |
| of the log statement. </li> |
| </ul> |
| |
| <p>However, this is not the only way for naming loggers. A |
| common alternative is to name loggers by <strong>functional |
| areas</strong>. For example, the "database" logger, "RMI" |
| logger, "security" logger, or the "XML" logger. |
| </p> |
| |
| <p>You may choose to name loggers by functionality and |
| subcategorize by locality, as in "DATABASE.com.foo.some.package.someClass" or |
| "DATABASE.com.foo.some.other.package.someOtherClass". |
| </p> |
| |
| <p><em>You are totally free in choosing the names of your |
| loggers.</em> The log4j package merely allows you to manage your |
| names in a hierarchy. However, it is your responsibility to define |
| this hierarchy. |
| </p> |
| |
| <p>Note by naming loggers by locality one tends to name things by |
| functionality, since in most cases the locality relates closely to |
| functionality. |
| </p> |
| |
| |
| <div class="question"> |
| <a name="2.5">2.5 How do I get the fully-qualified name of a class in a static block?</a> |
| </div> |
| |
| <p>You can easily retrieve the fully-qualified name of a class in a |
| static block for class X, with the statement |
| <code>X.class.getName()</code>. Note that <code>X</code> is the class |
| name and not an instance. The <code>X.class</code> statement does |
| <i>not</i> create a new instance of class <code>X</code>. |
| </p> |
| |
| <p>Here is the suggested usage template:</p> |
| |
| <pre class="source"> |
| package a.b.c; |
| |
| public class Foo { |
| final static Logger logger = Logger.getLogger(Foo.class); |
| ... other code |
| |
| } |
| </pre> |
| |
| <div class="question"> |
| <a name="2.6">2.6 Can the log output format be customized? </a> |
| </div> |
| |
| <p>Yes, you can extend the <code>Layout</code> class to create |
| you own customized log format. Appenders can be parameterized |
| to use the layout of your choice. |
| </p> |
| |
| <div class="question"> |
| <a name="2.7">2.7 What are the configurable options for <code>FooBarAppender</code>?</a> |
| </div> |
| |
| <p>Log4j uses JavaBeans style configuration.</p> |
| |
| <p>Thus, any setter method in <code>FooBarAppender</code> |
| corresponds to a configurable option. For example, in <a href="api\org\apache\log4j\RollingFileAppender.html"><code>RollingFileAppender</code></a> |
| the <a href="api/org/apache/log4j/RollingFileAppender.html#setMaxBackupIndex(int)"><code>setMaxBackupIndex(int |
| maxBackups)</code></a> method corresponds to the |
| <code>maxBackupIndex</code> option. The first letter of the |
| option can be upper case, i.e. <code>MaxBackupIndex</code> |
| and <code>maxBackupIndex</code> are equivalent but not |
| <code>MAXBACKUPIndex</code> nor <code>mAXBackupIndex</code>. |
| </p> |
| |
| <p>Layouts options are also defined by their setter methods. The same goes |
| for most other log4j components. |
| </p> |
| |
| <div class="question"> |
| <a name="2.8">2.8 What is the recommended way of migrating from |
| java.util.logging to log4j?</a> |
| </div> |
| |
| |
| <p>We suggest to just use global file search/replace. You should be able |
| to replace all the "java.util.Logger" references with |
| "org.apache.log4j.Logger", and you should be on your way. |
| </p> |
| |
| <p>If you're on a Win32 platform, we recommend <a href="http://www.textpad.com/">Textpad</a>. You can use the |
| CTRL+SHIFT+O to open all *.java files from a directory including all |
| its sub-directories, and then use the search/replace function to |
| replace in all files, and then CTRL+SHIFT+S to save all. Should take |
| about 60 seconds! :) |
| </p> |
| |
| <div class="question"> |
| <a name="2.9">2.9 Is it possible to direct log output to |
| different appenders by level? </a> |
| </div> |
| |
| <p>Yes it is. Setting the <b>Threshold</b> option of any appender |
| extending <a href="api/org/apache/log4j/AppenderSkeleton.html">AppenderSkeleton</a>, |
| (most log4j appenders extend AppenderSkeleton) to filter out all log |
| events with <em>lower</em> level than the value of the threshold |
| option. |
| </p> |
| |
| <p>For example, setting the threshold of an appender to DEBUG |
| also allow INFO, WARN, ERROR and FATAL messages to log along |
| with DEBUG messages. This is usually acceptable as there is |
| little use for DEBUG messages without the surrounding INFO, |
| WARN, ERROR and FATAL messages. Similarly, setting the |
| threshold of an appender to ERROR will filter out DEBUG, INFO |
| and WARN messages but not ERROR or FATAL messages. |
| </p> |
| |
| <p>This policy usually best encapsulates what the user |
| actually wants to do, as opposed to her mind-projected |
| solution. |
| </p> |
| <p>See <i>examples/sort4.lcf</i> for an example threshold |
| configuration.</p> |
| |
| <p>If you must filter events by exact level match, then you can |
| attach a <a href="api/org/apache/log4j/varia/LevelMatchFilter.html">LevelMatchFilter</a> |
| to any appender to filter out logging events by exact level match. |
| </p> |
| |
| |
| <div class="question"> |
| <a name="2.10">2.10 What does the Windows NT Event Viewer complain about |
| missing descriptions for my event messages when I use the |
| <code>NTEventLogAppender</code>?</a> |
| </div> |
| |
| <p>The NT Event Viewer relies on <i>message resource</i> DLLs |
| to properly view an event message. The NTEventLogAppender.dll |
| contains these message resources, but that DLL must be copied |
| to %SYSTEMROOT%\SYSTEM32 for it to work properly. |
| </p> |
| |
| <div class="question"> |
| <a name="2.11">2.11 Why can't I map my logger names to the loggers that |
| appear in the NT Event Log when I use the |
| NTEventLogAppender?</a> |
| </div> |
| |
| |
| <p>Unfotunately, the logger names are hardcoded within the |
| message resource DLL (see previous question about |
| NTEventLogAppender), so there isn't any easy way to override |
| those dynamically... in fact, I don't think it's possible to |
| do it, as you'd have to modify the DLL resources for every |
| application. Since most native applications don't use the |
| Logger column anyway... |
| </p> |
| |
| <div class="question"> |
| <a name="2.12">2.12 Are there suggested approaches for logging in JSP pages?</a> |
| </div> |
| |
| <p> |
| The suggested approach depends on your design requirements. If you or |
| your organization has no constraints on the use of Java in JSP pages, |
| simply use log4j normally in <code><% ... %></code> statements |
| as indicated in the Short Manual and the rest of the documentation. |
| </p> |
| <p> |
| However, if your design calls for a minimum amount of Java in your JSP |
| pages, consider using the |
| <a href="http://jakarta.apache.org/taglibs/doc/log-doc/intro.html">Log Taglib</a> |
| from the Jakarta Taglibs project. It provides logging JSP tags that invoke |
| log4j. |
| </p> |
| |
| <div class="faqSection"> |
| <a name="3">Section 3.</a> Advanced questions |
| </div> |
| |
| <p>This section contains answers to more advanced questions about log4j.</p> |
| |
| <div class="question"> |
| <a name="3.1">3.1 Can the outputs of multiple client request go to |
| different log files?</a> |
| </div> |
| |
| |
| <p>Many developers are confronted with the problem of |
| distinguishing the log output originating from the same class |
| but different client requests. They come up with ingenious |
| mechanisms to fan out the log output to different files. In |
| most cases, this is not the right approach. |
| </p> |
| |
| <p>It is simpler to use a nested diagnostic context |
| (NDC). Typically, one would <em>NDC.push()</em> client |
| specific information, such as the client's hostname, ID or any |
| other distinguishing information when starting to handle the |
| client's request. Thereafter, log output will automatically |
| include the nested diagnostic context so that you can |
| distinguish logs from different client requests even if they |
| are output to the same file. |
| </p> |
| |
| <p>See the <code>NDC</code> and the <code>PatternLayout</code> |
| classes for more information. The <code>NumberCruncher</code> |
| example shows how the NDC can be used to distinguish the log |
| output from multiple clients even if they share the same log |
| file. |
| </p> |
| |
| <p>For select applications, such as virtual hosting |
| web-servers, the NDC solution is not sufficient. As of version |
| 0.9.0, log4j supports multiple hierarchy trees. Thus, it is |
| possible to log to different targets from the same logger |
| depending on the current context. |
| </p> |
| |
| |
| <div class="question"> |
| <a name="3.2">3.2 Logger instances seem to be create only. Why isn't |
| there a method to remove logger instances?</a> |
| </div> |
| |
| <p>It is quite nontrivial to define the semantics of a |
| "removed" logger escecially if it is still referenced by the |
| user. Future releases <em>may</em> include a remove method in |
| the Logger class.</p> |
| |
| <div class="question"> |
| <a name="3.3">3.3 How do I get multiple process to log to the same file?</a> |
| </div> |
| |
| <p>You may have each process log to a |
| <a href="api/org/apache/log4j/net/SocketAppender.html"><code>SocketAppender</code></a>. |
| The receiving |
| <a href="api/org/apache/log4j/net/SocketServer.html"><code>SocketServer</code></a> |
| (or |
| <a href="api/org/apache/log4j/net/SimpleSocketServer.html"><code>SimpleSocketServer</code></a>) |
| can receive all the events and send them to a single |
| log file. |
| </p> |
| |
| <div class="question"> |
| <a name="3.4">3.4 How about the timesamps of events generated by multiple |
| processes across multiple hosts (possibly across multiple |
| timezones)? |
| </a> |
| </div> |
| |
| |
| <p>The timestamp is created when the logging event is created. |
| That is so say, when the <code>debug</code>, |
| <code>info</code>, <code>warn</code>, <code>error</code> or |
| <code>fatal</code> method is invoked. Thus, the timestamp is |
| unaffected by the time at which event arrive at a remote |
| socket server. |
| </p> |
| |
| <p>Timestamps are stored in UTC format inside the |
| event. Consequently, when displayed or written to a log file, |
| timestamps appear in the same timezone as the host displaying |
| or creating the logfile. Note that because the clocks of |
| various machines may not be synchronized, there may be |
| timestamp inconsistencies between events generated on |
| different hosts. |
| </p> |
| |
| <div class="question"> |
| <a name="3.5">3.5 Why can't log4j find my properties file in a J2EE or WAR |
| application?</a> |
| </div> |
| |
| |
| <p>The short answer: the log4j classes and the properties file |
| are not within the scope of the same classloader. |
| </p> |
| |
| <p>The long answer (and what to do about it): J2EE or Servlet |
| containers utilize Java's class loading system. Sun changed |
| the way classloading works with the release of Java 2. In |
| Java 2, classloaders are arranged in a hierarchial |
| parent-child relationship. When a child classloader needs to |
| find a class or a resource, it first delegates the request to |
| the parent. |
| </p> |
| |
| <p>Log4j only uses the default <code>Class.forName()</code> |
| mechanism for loading classes. Resources are handled |
| similarly. See the documentation for |
| <code>java.lang.ClassLoader</code> for more details. |
| </p> |
| |
| <p>So, if you're having problems, try loading the class or |
| resource yourself. If you can't find it, neither will |
| log4j. ;) |
| </p> |
| |
| |
| <div class="question"> |
| <a name="3.6">3.6 Is there a way to get log4j to automatically reload a |
| configuration file if it changes?</a> |
| </div> |
| |
| <p>Yes. Both the DOMConfigurator and the PropertyConfigurator support |
| automatic reloading through the <code>configureAndWatch</code> method. |
| See the API documentation for more details. |
| </p> |
| |
| |
| <p>Because the <code>configureAndWatch</code> launches a |
| separate wathdog thread, and because there is no way to stop |
| this thread in log4j 1.2, the <code>configureAndWatch</code> |
| method is unsafe for use in J2EE envrironments where |
| applications are recycled. |
| </p> |
| |
| |
| <div class="faqSection"> |
| <a name="4">Section 4.</a> Contributing to the project |
| </div> |
| |
| <p>This section includes questions about contributing to the |
| project</p> |
| |
| <div class="question"> |
| <a name="4.1">4.1 Why should I donate my extensions to log4j back to the |
| project? |
| </a> |
| </div> |
| |
| <p>Contrary to the GNU Public License (GPL) the Apache |
| Software License does not make any claims over your |
| extensions. By extensions, we mean totally new code that |
| invokes existing log4j classes. <em>You are free to do |
| whatever you wish with your proprietary log4j extensions.</em> |
| In particular, you may choose to never release your extensions |
| to the wider public. |
| </p> |
| |
| <p>We are very careful not to change the log4j client API so |
| that newer log4j releases are backward compatible with |
| previous versions. We are a lot less scrupulous with the |
| internal log4j API. Thus, if your extension is designed to |
| work with log4j version <code>n</code>, then when log4j |
| release version <code>n+1</code> comes out, you will probably |
| need to adapt your proprietary extensions to the new release. |
| </p> |
| |
| <p>Thus, you will be forced to spend precious resources in |
| order to keep up with log4j changes. This is commonly referred |
| to as the "stupid-tax." By donating the code and making it |
| part of the standard distribution, you save yourself the |
| unnecessary maintenance work. |
| </p> |
| |
| <p>If your extensions are useful then someone will eventually |
| write an extension providing the same or very similar |
| functionality. Your development effort will be wasted. Unless |
| the proprietary log4j extension is business critical, there is |
| little reason for not donating your extensions back to the |
| project. |
| </p> |
| |
| <div class="question"> |
| <a name="4.2">4.2 What should I keep in mind when contributing code?</a> |
| </div> |
| |
| <ol> |
| |
| <li> |
| <p>Write a test case for your contribution.</p> |
| |
| <p>There is nothing more irritating than finding the bugs |
| in debugging (i.e. logging) code. Writing a test case |
| takes some effort but is crucial for a widely used library |
| such as log4j. Writing a test case will go a long way in |
| earning you the respect of fellow developers. See the |
| tests/ directory for exiting test cases. |
| </p> |
| </li> |
| |
| |
| <li> |
| <p>Stick to the existing indentation style even if you hate it.</p> |
| |
| <p>Alternating between indentation styles makes it hard to |
| understand the source code. Make it a little harder on |
| yourself but easier on others. |
| </p> |
| |
| <p>Log4j has adopted a rather conservative approach by |
| following the <a href="http://java.sun.com/docs/codeconv/">Code Conventions |
| for the JavaTM Programming Language</a>. <b>We use 2 (two) |
| spaces for indentation and no tabs.</b> |
| </p> |
| </li> |
| |
| <li> |
| <p>Please do not both modify the code and change the |
| indentation in a single commit.</p> |
| |
| <p>If you change the code and reformat it at the same time |
| and then commit, the commit notification message will be |
| hard to read. It will contain many diffs associated with |
| the reformatting in addition to logical changes. |
| </p> |
| |
| <p>If you must reformat and change the code, then perform |
| each step separately. For example, reformat the code and |
| commit. Following that, you can change the logic and |
| commit. The two steps can be performed in the reverse |
| order just as well. You can first change the logic and |
| commit and only later reformat and commit. |
| </p> |
| |
| </li> |
| <li> |
| <p>Make every effort to stick to the JDK 1.1 API.</p> |
| |
| <p>One of the important advantages of log4j is its |
| compatibility with JDK 1.1.x. |
| </p> |
| </li> |
| |
| <li> |
| <p>Always keep it simple, small and fast when |
| possible.</p> |
| |
| <p>It's all about the application not about logging.</p> |
| </li> |
| |
| <li> |
| <p>Identify yourself as a contributor at the top of the |
| relevant file. |
| </p> |
| </li> |
| <li> |
| <p>Take responsibility for your code.</p> |
| |
| <p>Authoring software is very much like running a marathon. It |
| takes time and endurance. |
| </p> |
| </li> |
| <li> |
| <p>Did we mention sticking with the indentation style? </p> |
| </li> |
| <li><p>Did we mention writing test cases? </p> |
| </li> |
| |
| </ol> |
| |
| <div class="question"> |
| <a name="4.3">4.3 How can I contribute a new question/answer to this |
| document?</a> |
| </div> |
| |
| <p>Log4j uses <a href="http://jakarta.apache.org/velocity/anakia.html">velocity-anakia</a> |
| to generate its web-site, including this FAQ. We have devised |
| special macros to help us automatically generate labeled |
| question/answer pairs. |
| </p> |
| |
| <p>If you are not a commiter, you can simply submit your new |
| question/answer pair to the log4j-dev@logging.apache.org |
| mailing list. The committers will take it from there. |
| </p> |
| |
| <p>If you are a committer, then you must edit the |
| <em>/src/xdocs/faq.xml</em> file. The format of the file |
| should be self-evident. After you have made your changes, run |
| the command |
| </p> |
| <pre class="source">ant site</pre> |
| |
| <p>After the appropriate transformation, your changes should |
| appear in the file <em>/docs/faq.html</em>. |
| </p> |
| |
| |
| |
| |
| <!-- FOOTER --> |
| <div align="center"><font color="#525D76" size="-1"><em> |
| Copyright © 1999-2005, Apache Software Foundation |
| </em></font></div> |
| |
| <!-- END main table --> |
| |
| <!-- LEFT SIDE NAVIGATION --> |
| <!-- ============================================================ --> |
| <div class="leftcol"> |
| <div class="menu_header">Log4j Project</div> |
| <div class="menu_item"> <a href="./index.html">Introduction</a> |
| </div> |
| <div class="menu_item"> <a href="./download.html">Download</a> |
| </div> |
| <div class="menu_item"> <a href="./documentation.html">Documentation</a> |
| </div> |
| <div class="menu_item"> <a href="./contactUs.html">Contact us</a> |
| </div> |
| <div class="menu_item"> <a href="./contributors.html">Contributors</a> |
| </div> |
| <div class="menu_item"> <a href="./chainsaw.html">Chainsaw</a> |
| </div> |
| <div class="menu_item"> <a href="./history.html">History</a> |
| </div> |
| <div class="menu_header">Support</div> |
| <div class="menu_item"> <a href="http://logging.apache.org/site/binindex.cgi">Binary distributions</a> |
| </div> |
| <div class="menu_item"> <a href="http://logging.apache.org/site/cvs-repositories.html">CVS Repositories</a> |
| </div> |
| <div class="menu_item"> <a href="http://logging.apache.org/site/mailing-lists.html">Mailing Lists</a> |
| </div> |
| <div class="menu_item"> <a href="http://logging.apache.org/site/bugreport.html">Bug Reporting</a> |
| </div> |
| <div class="menu_header">Related Projects</div> |
| <div class="menu_item"> <a href="http://www.slf4j.org">SLF4J</a> |
| </div> |
| <div class="menu_header">Translations</div> |
| <div class="menu_item"> <a href="http://jakarta.apache-korea.org/log4j/index.html">Korean</a> |
| </div> |
| <div class="menu_item"> <a href="http://www.ingrid.org/jajakarta/log4j/">Japanese</a> |
| </div> |
| </div> |
| |
| |
| </body> |
| </html> |
| <!-- end the processing --> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |