faq.fml

apache的log4j源码

<?xml version="1.0"?>
<!--
 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.

-->
<faqs title="Frequently Asked Technical Questions">
  <part id="faq">

   <faq id="1.1">
       <question>What is log4j?</question>
       <answer>	<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>
</answer>
      </faq>


      <faq id="1.2"><question>Is log4j a reliable logging system?</question>
      <answer><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:[e-mail]">[e-mail]</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></answer></faq>

    <faq id="1.3"><question>What are the prerequisites for log4j?</question>
      <answer>
	  <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>

	  <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>

	  <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>

	  <p>The <code>org.apache.log4j.net.JMSAppender</code>
	  requires the presence of the JMS API as well as JNDI.
	  </p>

	  <p>log4j test code relies on the <a href="http://www.junit.org">JUnit</a> testing framework.
	  </p>
             </answer></faq>

      <faq id="1.4"><question>What are the features of log4j?</question>
      <answer>
	  <p>log4j is optimized for speed.</p>

	  <p>log4j is based on a named logger hierarchy.</p>

	  <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>

	  <p>log4j is thread-safe.</p>

	  <p>log4j is not restricted to a predefined set of
	  facilities.</p>

	  <p>Logging behavior can be set at runtime using a
	  configuration file. Configuration files can be property
	  files or in XML format.  </p>

	  <p>log4j is designed to handle Java Exceptions from the
	  start.</p>

	  <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>

	  <p>log4j uses 5 levels, namely DEBUG, INFO, WARN, ERROR and
	  FATAL.
	  </p>

	  <p>The format of the log output can be easily changed by
	  extending the <code>Layout</code>
          class.  </p>

	  <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>

	  <p>log4j supports multiple output appenders per logger.
	  </p>

	  <p>log4j supports internationalization.</p>
             </answer></faq>

      <faq id="1.5"><question>Is there example code for using log4j?</question>
      <answer>
	<p>See the <code>examples/</code> directory.</p>
      </answer>
      </faq>

      <faq id="1.6">
            <question>What documentation should I read to learn more about
      log4j?</question>
	<answer><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&#xfc;lc&#xfc;.
	</p></answer>
          </faq>

      <faq id="1.7"><question>Is log4j thread-safe?</question>
      <answer>
	<p>Yes, log4j is thread-safe. Log4j components are designed to
	be used in heavily multithreaded systems.</p>

      </answer></faq>

      <faq id="1.8"><question>What does log output look like?</question>
      <answer>
 	<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>
          </answer></faq>

    <faq id="1.9"><question>Why should I use log4j when JDK 1.4 already ships with a
      logging API?</question>
        <answer>

        <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 developers
        from all over the world is bound to make a difference.
        </p>
        </answer>
        </faq>


      <faq id="2.1"><question>What are <em>Loggers</em>?</question>
      <answer>

	<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>
          </answer></faq>

<faq id="2.2"><question>How can I change log behavior at runtime?</question>
      <answer>
	<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>

             </answer></faq>

      <faq id="2.3"><question>What is the fastest way of (not) logging?</question>
      <answer>
	<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>
</answer></faq>

      <faq id="2.4"><question>Are there any suggested ways for naming loggers?</question>
      <answer>
	<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>
             </answer></faq>

      <faq id="2.5"><question>How do I get the fully-qualified name of a class in a static block?</question>
      <answer>
	<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>
             </answer></faq>

      <faq id="2.6"><question>Can the log output format be customized? </question>
      <answer>
 	<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>
</answer></faq>