faq.fml

apache的log4j源码

      <faq id="2.7"><question>What are the configurable options for <code>FooBarAppender</code>?</question>
      <answer>
	<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="apidocs\org\apache\log4j\RollingFileAppender.html"><code>RollingFileAppender</code></a>
	the <a href="apidocs/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>
    </answer></faq>

             <faq id="2.8"><question>What is the recommended way of migrating from
      java.util.logging to log4j?</question>
        <answer>

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

             <faq id="2.9"><question>Is it possible to direct log output to
      different appenders by level? </question><answer>
	<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="apidocs/org/apache/log4j/varia/LevelMatchFilter.html">LevelMatchFilter</a>
	to any appender to filter out logging events by exact level match.
	</p>
    </answer></faq>


             <faq id="2.10"><question>What does the Windows NT Event Viewer complain about
      missing descriptions for my event messages when I use the
      <code>NTEventLogAppender</code>?</question>

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

             <faq id="2.11"><question>Why can't I map my logger names to the loggers that
      appear in the NT Event Log when I use the
      NTEventLogAppender?</question>

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

    <faq id="2.12"><question>Are there suggested approaches for logging in JSP pages?</question>
    <answer>
        <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>&lt;% ... %&gt;</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>
    </answer>
    </faq>

             <faq id="3.1"><question>Can the outputs of multiple client request go to
      different log files?</question>
                 <answer>
	<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>
    </answer></faq>


    <faq id="3.2"><question>Logger instances seem to be create only. Why isn't
      there a method to remove logger instances?</question>
     <answer>
	<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></answer></faq>

    <faq id="3.3"><question>How do I get multiple process to log to the same file?</question>
      <answer>
	<p>You may have each process log to a
	<a href="apidocs/org/apache/log4j/net/SocketAppender.html"><code>SocketAppender</code></a>.
	The receiving
	<a href="apidocs/org/apache/log4j/net/SocketServer.html"><code>SocketServer</code></a>
	(or
	<a href="apidocs/org/apache/log4j/net/SimpleSocketServer.html"><code>SimpleSocketServer</code></a>)
	can receive all the events and send them to a single
	log file.
	</p>
     </answer></faq>

             <faq id="3.4"><question>How about the timesamps of events generated by multiple
      processes across multiple hosts (possibly across multiple
      timezones)?</question>
                 <answer>
	<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>
    </answer></faq>

             <faq id="3.5"><question>Why can't log4j find my properties file in a J2EE or WAR
      application?</question><answer>
	<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></answer></faq>


             <faq id="3.6"><question>Is there a way to get log4j to automatically reload a
      configuration file if it changes?</question><answer>

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


        <faq id="4.1"><question>Why should I donate my extensions to log4j back to the
      project?</question><answer>
	<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></answer></faq>

    <faq id="4.2"><question>What should I keep in mind when contributing code?</question>
      <answer>
	<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>
      </answer></faq>


    <faq id="duplicate-messages">
      <question>Why am I getting multiple copies of messages in my log file?</question>
      <answer>
	    <p>There are several reasons this can occur:
		<ul>
			<li>Repeated configuration of log4j:  By default, each call to 
			PropertyConfigurator.configure or DOMConfigurator.configure is
			culmulative.  If your configuration file defines a file appender,
			calling PropertyConfigurator.configure three times will create
			three distinct instances and connect each of them to the specified logger.</li>
			<li>Attaching the same appender to multiple loggers: if an appender is
			attached to the root logger and child logger, then any message
			sent to the child logger will go to the appender twice (unless 
			additivity is set to false).</li>
		</ul></p>
	  </answer>
    </faq>
      <faq id="custom-level">
        <question>How do I add a custom level?</question>
        <answer>
          <p>It is possible, but rarely appropriate.  The
          request is commonly for a level named something like "audit"
          that doesn't obviously fit in the progression "trace", "debug",
          "info", "warn", "error" and "fatal".  In that case, the request
          for a level is really a request for a mechanism to specify
          a different audience.  The appropriate mechanism is to use a distinct
          logger name (or tree) for "audit" related messages.</p>
        </answer>
      </faq>
  </part>
</faqs>