Grace JavaLog

Events

Grace Software

JavaLog

$Revision: 1.3 $

$Date: 1999/10/28 11:17:24 $

Introduction

An item logged in JavaLog is called an event. An event encapsulates the time, stack trace, message, and object as well as an event type string. An event type is one word that indicates the general category of the event. Event types are one of the ways events can be filtered in JavaLog so it is important to design the event types assigned to an event carefully.

JavaLog events are initiated by calling one of the Log.log(String type, ...) functions. Some common event types have been broken out as separate functions so the event type argument does not have to be passed. These are error, warning, notice, and trace.

The remainder of this document shows how to use JavaLog to log various common conditions in code.

Exceptions

Typically, the programmer doesn't know exactly how to handle some exceptions while the code is being developed and tested. So, instead of simply calling Exception.printStackTrace(), using the exception logging functionality allows is easier and allows the extensive runtime control of JavaLog. The following is a the best way to handle exceptions:

    try {
        ... code that throws an exception ...
    }
    catch (Exception e) {
        Log.error(e);
    }

Now, rather that simply log the fact that an exception occurred, it is better to log the context under which the exception has occurred. However, since JavaLog logs automatically the class, function, and line number in which the exception occurred, the programmer should try to offer a more meaning full explanation of why the error occurred.

This high level description of the exception takes the form a string message that could contain two pieces of information:

the probable cause of the exception

how the code handled the exception. Here are some possible words to describe this:

ignored	Exception indicates an expected erroneous condition but one that leaves the program in a known runnable state.
aborted	Like ignored but indicates that the entire operation causing the exception was stopped.
confused or impossible	The programmer has determined that the condition under which the exception occurred is "impossible" but he was forced to handle the exception. If this exception occurs, it indicates that programmer didn't anticipate the condition and means, therefore, that the program may be in an foul or unrecoverable state.
fatal	The exception is not handleable and the program will be terminated.

So, a useful handled exception could look like this:


	 try { ... }
	 catch (Exception e) { Log.error("ignored"); }
    
         or

	 try { ... }
	 catch (Exception e) { Log.error("invalid input; aborted", e); }

Errors and Warnings

Errors and Warnings that are not caused by an exception are also useful in the log. In this case, the condition is determined and logged with only a message.


if (...) 
    Log.warning("something is wrong on Saturn 3"); }

Notices

Notices are useful for printing out messages or objects that are a normal part of program's output but are not used for debugging. This is useful if the program has no GUI and simply wants to print results to the log.


Log.notice("original", originalVector); }
Log.notice("sorted", sortedVector); }

Note in the above two examples that when objects are logged, the name of the object must also be passed to the logging function.

Traces

Traces are typically used during program debugging, testing, or performance analysis. Then, during productive runs of the software they can be turned off or partially filtered to reduce the noisy log output.


Log.trace("object", object); }

User defined

Log messages can have other event types than the error, warning, notice, and trace. The user can specify any type in the more general call to the logging functions that takes an event type as the first argument:


Log.log("statistic", "object", object); }

The above example would log an object with event type "statistic". Any string can be used for the event type. User defined event types are useful for many purposes because they add a more rich semantic meaning to the event and can be easily and quickly filtered in and out at runtime.

Older logging systems indicate the meaning of a log events with integer level numbers. This practice can be continued here as well. Simply specify the event type as a number:


Log.log("42", "object", object); }

Then, the runtime filtering mechanism can be used to filter in or out specific levels or a series of levels. However, since JavaLog allows text event types, it is a shame not to use them. Numbered levels do not provide semantically rich logs and therefore require a auxiliary lookup table to translate to the text description.