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/09/28 17:30:54 UTC
cvs commit: jakarta-log4j/src/java/org/apache/log4j/performance Logging.java
ceki 01/09/28 08:30:54
Modified: src/docbook architecture.xml changes.xml
src/java/org/apache/log4j/performance Logging.java
Log:
Revision Changes Path
1.12 +69 -62 jakarta-log4j/src/docbook/architecture.xml
Index: architecture.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/architecture.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- architecture.xml 2001/09/28 13:37:47 1.11
+++ architecture.xml 2001/09/28 15:30:54 1.12
@@ -436,20 +436,24 @@
selection rule.</para>
</sect2>
- <sect2 id="repositoryLevel" xreflabel="Respository-wide level">
- <title>Disabling levels on a repository-wide basis</title>
-
- <para>For performance reasons, you can turn off a level for
- entire repositories (=hierarchies) regardless of logger or its
- effective level. For example, If you choose to enable the
- <varname>info</varname> level, then you have effectively
- disabled logging below the info level such that the
- <varname>debug</varname> level requests will be dropped
- regardless of logger settings.
- </para>
+ <!-- ----------------------------------------------------------------- -->
+
+ <sect2 id="repositoryThreshold" xreflabel="Respository-wide Threshold">
+ <title>Respository-wide Threshold</title>
- <para>The repository-wide level acts as a filter which is
- applied prior to the <xref linkend="basicSelectionRule"/>.
+ <para>One can set a respository-wide threshold such that a
+ request below the threshold level is dropped regardless of the
+ logger or its effective level. For example, If you choose set
+ the respository-wide threshold to the <varname>info</varname>
+ level, then you have effectively disabled logging below the
+ info level such that the <varname>debug</varname> level
+ requests will be dropped regardless of the logger settings.
+ </para>
+
+ <para>The repository-wide threshold acts as a filter which is
+ applied prior to the <xref
+ linkend="basicSelectionRule"/>. This has important performance
+ implication which is futher discussed in <xref linkend="performance"/>.
</para>
<programlisting>
@@ -460,28 +464,28 @@
// get the containing repository
LoggerRepository repository = x.getLoggerRepository();
- // Set the repository-wide level to WARN effectively disabling the
- // all INFO and DEBUG level requests.
- repository.enable(Level.WARN);
+ // Set the repository-wide threshold to WARN effectively disabling the
+ // all INFO and DEBUG requests.
+ repository.setThreshold(Level.WARN);
// This request will be dropped because the repository-wide
- // level is set to WARN even if the logger x is enabled for the INFO level.
+ // threshold is set to WARN even if the logger x is enabled for the INFO level.
x.info("Hello world.");
// Now, let us disable all levels
- repository.enable(Level.OFF);
- // This request will be dropped because all levels are turned off.
+ repository.setThreshold(Level.OFF);
+ // This request even if FATAL will be dropped because all levels are turned off.
x.fatal("This is a serious message");
- // Now, let us set the repository-wide level to ALL
- repository.enable(LEVEL.ALL);
+ // Now, let us set the repository-wide threshold to ALL, the lowest possible level.
+ repository.setThreshold(Level.ALL);
// This request will be logged because the repository-wide
- // level is set to ALL and the logger x is enabled for the INFO level.
+ // threshold is set to ALL and the logger x is enabled for the INFO level.
x.info("Hello world.");
// This request will be logged because the repository-wide
- // level is set to ALL but the logger x is disabled for the DEBUG level.
+ // threshold is set to ALL but the logger x is disabled for the DEBUG level.
x.debug("Hello world.");
</programlisting>
@@ -831,7 +835,7 @@
method if the repository is not enabled for the request level.
</para>
- <para>See <xref linkend="repositoryLevel"/> for more details.</para>
+ <para>See <xref linkend="repositoryThreshold"/> for more details.</para>
</step>
<step performance="required">
@@ -884,18 +888,18 @@
<para>It is reponsability of the invoked appender to format
the logging event. However, most (but not all) appender
- delegate most of the formatting task to their
+ delegate the task of formatting the logging event to their
<classname>Layout</classname>. This layout formats the
- <classname>LoggingEvent</classname> instance and returns
- the event's information in a string form. The formatting
- of event message is delegated to object renderers attached
- to the repository of the logger
+ <classname>LoggingEvent</classname> instance and returns the
+ event's information in a string form. The formatting of
+ event <emphasis>message</emphasis> is usually delegated to
+ object renderers of the logger repository.
</para>
- <para>Note that some appenders, such as the SocketAppender,
- do not transform the logging event into a string but
- serailize it instead. Consequently, they do not require
- nor have a layout.
+ <para>Note that some appenders, such as the SocketAppender, do
+ not transform the logging event into a string but serialize
+ it instead. Consequently, they do not require nor have a
+ layout.
</para>
</step>
@@ -903,14 +907,15 @@
<title>Sending out the LoggingEvent</title>
<para>After the logging event is formatted it is sent to its
- destination depending on the appender.
+ destination.
</para>
</step>
</procedure>
-
-
</sect1>
- <sect1>
+
+ <!-- -------------------------------- Performance -------------------------------- -->
+
+ <sect1 id="performance">
<title>Performance</title>
<para>One of the often-cited arguments against logging is its
@@ -928,50 +933,52 @@
<orderedlist>
<listitem>
- <para>Logging performance when logging is turned off.</para>
+ <para>Logging performance when logging is turned off
+ entirely.</para>
- <para>When logging is <ulink
- url="api/org/apache/log4j/Hierarchy.html#disableAll()">turned
- off entirely</ulink> or just for a <ulink
- url="api/org/apache/log4j/Hierarchy.html#disable(org.apache.log4j.Priority)">set
- of levels</ulink>, the cost of a log request consists of a
- method invocation plus an integer comparison. On a 233
- MHz Pentium II machine this cost is typically in the 5 to
- 50 nanosecond range.
+ <para>You can turn off logging entirely by setting the
+ threshold of a repository to Level.OFF, the highest possible
+ level. See <xref linkend="repositoryThreshold"/> on how to set
+ a threshold of a repository. When logging is turned off
+ entirely or for level below the threshold, the cost of a log
+ request consists of a method invocation plus an integer
+ comparison. On a 233 MHz Pentium II machine this cost is
+ typically in the 5 to 50 nanosecond range.
</para>
- <para>However, The method invocation involves the "hidden" cost of
- parameter construction. </para>
+ <para>However, any method invocation involves the "hidden"
+ cost of parameter construction. For example, for some logger
+ <varname>x</varname> writing,
+ </para>
- <para>For example, for some logger <varname>x</varname> writing,
- <programlisting>
+ <programlisting>
x.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));</programlisting>
+ <para>
incurs the cost of constructing the message parameter, i.e.
converting both integer <varname>i</varname> and <varname>entry[i]</varname>
to a String, and concatenating intermediate strings,
regardless of whether the message will be logged or not.
</para>
-
- <para>This cost of parameter construction can be quite high and it
- depends on the size of the parameters involved.</para>
-
- <para>To avoid the parameter construction cost write:
+ <para>This cost of parameter construction can be quite high
+ and it depends on the size of the parameters involved. To
+ avoid the parameter construction cost write:
+ </para>
<programlisting>
if(x.isDebugEnabled() {
x.debug("Entry number: " + i + " is " + String.valueOf(entry[i]));
}</programlisting>
- </para>
+
<para>This will not incur the cost of parameter construction
- if debugging is disabled. On the other hand, if the logger is
- debug-enabled, it will incur twice the cost of evaluating
- whether the logger is enabled or not: once in
+ if the debug lebel is disabled. On the other hand, if the
+ logger is debug-enabled, it will incur twice the cost of
+ evaluating whether the logger is enabled or not: once in
<function>isDebugEnabled</function> and once in
- <function>debug</function>. This is an insignificant
- overhead because evaluating a logger takes about 1% of the
- time it takes to actually log.
+ <function>debug</function>. This is an insignificant overhead
+ because evaluating a logger takes about 1% of the time it takes
+ to actually log.
</para>
<para>In log4j, logging requests are made to instances of the Logger
1.4 +3 -5 jakarta-log4j/src/docbook/changes.xml
Index: changes.xml
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/docbook/changes.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- changes.xml 2001/09/28 13:37:47 1.3
+++ changes.xml 2001/09/28 15:30:54 1.4
@@ -89,11 +89,9 @@
<para>
In the <classname>Hierarchy</classname> class The
<function>disable</function> family of methods have been
- removed and replaced by <function>enable</function>
- methods. This was done at the expense of backward
- compatiebility. However, the disable family was the source of
- confusion. The enable family accomplishes the equivalent task
- using positive logic which is less confusing for most people.
+ removed and replaced by <function>setThresold</function> and
+ <function>getThresold</function> methods. This change is not
+ backward compatible.
</para>
</sect2>
1.9 +1 -1 jakarta-log4j/src/java/org/apache/log4j/performance/Logging.java
Index: Logging.java
===================================================================
RCS file: /home/cvs/jakarta-log4j/src/java/org/apache/log4j/performance/Logging.java,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- Logging.java 2001/06/06 21:49:16 1.8
+++ Logging.java 2001/09/28 15:30:54 1.9
@@ -141,7 +141,7 @@
<p><li>Format specifiers in conversion patterns have almost no impact
on performance.
- <p>Formating time and date information is costly. Using relative
+ <p><li>Formating time and date information is costly. Using relative
time has the least impact on performance. It is recommended that to
use log4j specific date formatters such as the {@link
org.apache.log4j.helpers.ISO8601DateFormat} instead of the standard {@link
---------------------------------------------------------------------
To unsubscribe, e-mail: log4j-cvs-unsubscribe@jakarta.apache.org
For additional commands, e-mail: log4j-cvs-help@jakarta.apache.org