You are viewing a plain text version of this content. The canonical link for it is here.
Posted to log4j-cvs@jakarta.apache.org by ce...@apache.org on 2001/11/29 21:35:00 UTC
cvs commit: jakarta-log4j/src/docbook architecture.xml configuration.xml
ceki 01/11/29 12:35:00
Modified: src/docbook architecture.xml configuration.xml
Log:
more docs
Revision Changes Path
1.16 +33 -26 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- architecture.xml 2001/11/14 20:31:14 1.15
+++ architecture.xml 2001/11/29 20:35:00 1.16
@@ -188,9 +188,8 @@
one possible, albeit common, strategy for naming
loggers. Log4j does not impose any restriction on the name
of loggers. The user is free to name logger as she
- wishes.>Nevertheless, naming loggers after the class where
- they are located seems to be the best strategy known so
- far.
+ wishes. Nevertheless, naming loggers after the class where
+ they are located seems to be the best strategy known so far.
</para>
</sect2>
@@ -203,11 +202,13 @@
level. This greatly simplifies logging management. The set of
possible levels, that is
+ <ulink url="../api/org/apache/log4j/Level.html#ALL">ALL</ulink>,
<ulink url="../api/org/apache/log4j/Level.html#DEBUG">DEBUG</ulink>,
<ulink url="../api/org/apache/log4j/Level.html#INFO">INFO</ulink>,
<ulink url="../api/org/apache/log4j/Level.html#WARN">WARN</ulink>,
- <ulink url="../api/org/apache/log4j/Level.html#ERROR">ERROR</ulink> and
- <ulink url="../api/org/apache/log4j/Level.html#FATAL">FATAL</ulink>
+ <ulink url="../api/org/apache/log4j/Level.html#ERROR">ERROR</ulink>,
+ <ulink url="../api/org/apache/log4j/Level.html#FATAL">FATAL</ulink> and
+ <ulink url="../api/org/apache/log4j/Level.html#OFF">OFF</ulink>,
are defined in the <ulink
url="../api/org/apache/log4j/Level.html">org.apache.log4j.Level</ulink>
@@ -475,8 +476,8 @@
<para >This rule is at the heart of log4j. It is based on the
ordering of levels. For the standard levels, we have the
- following ordering <varname>DEBUG < INFO < WARN < ERROR
- < FATAL</varname>.
+ following ordering <varname>ALL < DEBUG < INFO < WARN < ERROR
+ < FATAL < OFF</varname>.
</para>
<para>Here is this rule in action.</para>
@@ -526,7 +527,7 @@
the respository-wide threshold to the <varname>info</varname>
level, then you have effectively disabled logging below the
info level such that all <varname>debug</varname> level
- requests will be dropped regardless of logger and its
+ requests will be dropped regardless of the logger and its
configuration.
</para>
@@ -537,7 +538,7 @@
linkend="performance"/>. By default, the repository-wide
level is set to the <varname>ALL</varname> level which is the
lowest possible level. Thus, the repository-wide threshold
- does not filter out any requests letting the basic selection
+ does not filter out any requests -- letting the basic selection
rule to apply.
</para>
@@ -908,7 +909,11 @@
url="../api/org/apache/log4j/AppenderSkeleton.html">AppenderSkeleton</ulink>
abstract class which implements the
<function>doAppend</function> method in a synchronized block
- ensuring thread-safety.
+ ensuring thread-safety. The <function>doAppend</function>
+ method of <classname>AppenderSkeleton</classname> also
+ invokes the <ulink
+ url="../api/org/apache/log4j/spi/Filter.html">filters</ulink>
+ attached to the appender, if any such filter exists.
</para>
</step>
@@ -1010,10 +1015,11 @@
to actually log.
</para>
- <para>In log4j, logging requests are made to instances of the Logger
- class. Logger is a class and not an interface. This measurably
- reduces the cost of method invocation at the cost of some
- flexibility.
+ <para>In log4j, logging requests are made to instances of the
+ Logger class. Logger is a class and not an interface. This
+ measurably reduces the cost of method invocation at the cost
+ of some flexibility, altough in some recent JVMs,
+ the performance difference became negligible.
</para>
<para>Certain users resort to preprocessing or compile-time
@@ -1023,7 +1029,13 @@
does not contain any log statements, logging cannot be
turned on for that binary. This is perhaps a
disproportionate price to pay in exchange for a small
- performance gain.
+ performance gain. The performance gain will be significant
+ only if log statements are placed in tight-loops where the
+ same log request is invoked potentially millions or even
+ billions of times. Inserting logging statements in
+ tight-loops is lose lose proposal. It will slow down your
+ application even if logging is turned off or generate
+ massive logging output if enabled.
</para>
</listitem>
@@ -1040,19 +1052,14 @@
ancestors.</para>
<para>There has been a serious effort to make this hierarchy
- walk to be as fast as possible. For example, child
- loggers link only to their existing ancestors. In the
- <classname>BasicConfigurator</classname> example shown
- earlier, the logger named
- <classname>com.foo.Bar</classname> is linked directly to the
- root logger, thereby circumventing the nonexistent
- <classname>com</classname> or <classname>com.foo</classname>
- loggers. This significantly improves the speed of the
- walk, especially in "sparse" hierarchies.
+ walk to be as fast as possible. For example, child loggers
+ link only to their existing ancestors. This significantly
+ improves the speed of the walk, especially in "sparse"
+ hierarchies.
</para>
- <para>The typical cost of walking the hierarchy is typically 3
- times slower than when logging is turned off entirely.</para>
+ <para>The cost of walking the hierarchy is typically 3 times
+ slower than when logging is turned off entirely.</para>
</listitem>
<listitem>
1.18 +2 -2 jakarta-log4j/src/docbook/configuration.xml
Index: configuration.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/configuration.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- configuration.xml 2001/11/28 23:00:41 1.17
+++ configuration.xml 2001/11/29 20:35:00 1.18
@@ -216,8 +216,8 @@
<para>As mention previously, log4j also supports configuration
files written in XML. These configuration files are parsed with
- <classname>org.apache.log4j.xml.DOMConfigurator</classname>. Here
- is how.
+ <ulink
+ url="../api/org/apache/log4j/xml/DOMConfigurator.html">org.apache.log4j.xml.DOMConfigurator</ulink>. Here is how.
</para>
<para>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>