Changes between Initial Version and Version 1 of LOGGING

Timestamp:

09/16/08 17:22:05 (17 years ago)

Author:

Tanya

Comment:

--

LOGGING

@@ +1 @@
+= Logging =
+For logging we use the log4j library.  [HTTP://logging.apache.org/log4j/1.2/index.html log4j]
+
+== Logging levels ==
+log4j has several levels for logging. They allow users to sort information according to its significance. Levels can be used for easy management of the amount and verbosity of the output information. The library can be easily configured to show only messages not less than a given level. That's why it is important to identify well the level of the information you are about to log.
+
+Currently there are six logging levels:
+
+ * FATAL - It is used to notify of an error that surely leads to application aborting.
+{{{
+public static void checkAssertions() {
+        Logger.getLogger(Main.class).fatal(
+                        "Assertions are disabled."
+                        + "Please enable them with the -ea option.");
+        throw new Error("Assertions are disabled."
+                        + "Please enable them with the -ea option.");
+}
+}}}
+
+ * ERROR - It is used when an operation fails to complete and is likely to cause the application to abort, but it may still survive.
+{{{
+try {
+        bi = ImageIO.read(in);
+} catch (IOException e) {
+        logger.error("Cannot load icon",e);
+}
+}}}
+
+ * WARN - Used when a potentially harmful situation has occurred. Like in: 
+{{{
+ public final void removeListener(PropertyListener<T> listener) {
+       if(!getListereners().contains(listener)) {
+           logger().warn("Property.removeListener(): removing not registered!");
+       }
+       assert getListereners().contains(listener);
+       getListereners().remove(listener);
+ }
+}}}
+
+ * INFO - Used to give information of major steps of the application life cycle. Like in:
+{{{
+public PageView(final Page page) {
+                getBean().init(model(), page);
+                
+                logger().info("PageView created");
+        }
+}}}
+
+ * DEBUG - Gives information about the step by step progress of the application. For example entering/leaving a method:
+{{{
+private void badLocationSafeRun() {
+        logger().debug("Chain " + this + " starts flushing");
+        try {
+                underFlow();
+                overFlow();
+        } catch (final BadLocationException e) {
+                throw new RuntimeException(e);
+        }
+        logger().debug("Chain " + this + " has been flushed");
+}
+}}}
+
+ * TRACE - The most verbose of levels. Used to watch the progress of a method. Also for variable output during debugs
+{{{
+private void overFlow() throws BadLocationException {
+        logger().debug("Overflowing starts");
+        while (baseOverflows()) {
+                Element cur = this.base
+                                .getCharacterElement(getBaseLength() - 1);
+                int startOffset = cur.getStartOffset();
+                int endOffset = cur.getEndOffset();
+
+                logger().trace("Overflowing from " + startOffset + " to " + endOffset);
+
+                String text = getText(this.base, startOffset, endOffset)
+                                .substring(getBaseLength() - startOffset - 1,
+                                                getBaseLength() - startOffset);
+                ...
+                logger().trace("Following text was overflowed - " + text);
+        }
+}
+}}}
+
+== Logging in instance methods ==
+It should be performed using a method that looks like:
+
+{{{
+modifier Logger logger(){
+                return Logger.getLogger(this.getClass());
+        }
+}}}
+
+It is advisable that all mutable base classes implement such a method (with "protected" modifier) so that their successors can easily access the proper Logger for their class.
+
+Classes that have a logger method:
+ * !BaseProObject
+ * Property
+ * Change
+
+== Logging in class methods ==
+The correct Logger is obtained like this
+{{{
+public class Logic {
+...
+       Logger logger = Logger.getLogger(Logic.class);
+...
+}
+}}}
+
+Depending on the intensity of logging, the logger may be stored in a local variable( low intensity) or a class variable( used in several static methods).
+
+== Configuring log4j in Veda ==
+
+Log4j configuration is stored in "log4j.properties" file. It is read at application startup.
+
+In order to change the lowest logged level edit the following line:
+{{{
+log4j.rootLogger=all, ConsoleLogging
+}}}
+and replace "all" with the desired level (choose on from - off, fatal, error, warn, info, debug, trace).
+
+Note that the Properties library is configured separately here:
+{{{
+log4j.logger.net.asteasolutions.veda.research.properties=all, ConsoleLogging
+}}}
+This reflects on all classes extending the Property class.
+
+Destination and format of logged messages can be changed by configuring the appropriate Appenders in "log4j.properties".
+
+== Logging overhead ==
+
+
+In general log4j has been optimized in speed, but do take note that logging adds some performance overhead.
+
+ * Computing of the arguments of logger methods is done before checking whether this message will be logged at all. 
+ * Also choosing whether to log or not takes some time. 
+ * And do not forget that the actual formating and output of the messages is also time-consuming.