Package de.lmu.ifi.dbs.elki.logging

Logging facility for controlling logging behaviour of the complete framework.

See:
Description

Interface Summary

Loggable

Interface providing the methods required to log messages according to LogLevel levels.

Class Summary

AbstractLoggable	Abstract superclass for classes being loggable, i.e. classes intending to log messages.
DebugFilter	A filter for all (or specified) logs - suitable for handling debugging messages.
ExceptionFilter	A filter for exception logs - suitable for handling severe error messages.
ExceptionFormatter	A formatter to format exception messages.
ImmediateFlushHandler	ImmediateFlushHandler is a stream handler flushing each published LogRecord immediately.
InfoFilter	A filter for info logs - suitable for handling verbose messages.
LoggingConfiguration	Facility for configuration of logging.
LogLevel	This class provides a set of logging levels that should be used to control logging output.
MaskingOutputStream	An OutputStream to mask the underlying OutputStream.
MessageFilter	A filter for message logs - suitable for handling messages.
MessageFormatter	A formatter to simply retrieve the message of an LogRecord.
ProgressFilter	A filter for progress logs - suitable for handling progress messages.
ProgressLogRecord	Additionally to the functionality of a LogRecord, a ProgressLogRecord provides information concerning the progress as the name of the progressing task and the percentage of the progress.
SelectiveFilter	A selective filter filters exactly for a certain LogLevel of LogRecords.
StaticLogger	Subclass of AbstractLoggable , can be used in static environments.
WarningFilter	A filter for warning logs - suitable for handling warning messages.

Package de.lmu.ifi.dbs.elki.logging Description

Logging facility for controlling logging behaviour of the complete framework.

Logging

Any classes intending to log message should extend AbstractLoggable.

Level specific logging

• Debugging: for debug messages use levels below LogLevel.VERBOSE, such as DEBUG_FINE, DEBUG_FINER, or DEBUG_FINEST, and use the corresponding methods AbstractLoggable.debugFine(String), AbstractLoggable.debugFiner(String), AbstractLoggable.debugFinest(String), respectively.
• Verbose messages for regular user information: for "verbose" messages use the level VERBOSE and the corresponding method AbstractLoggable.verbose(String), respectively.
• Warning messages for user information: For warning messages use the level WARNING and the corresponding method AbstractLoggable.warning(String), respectively.
• Exception messages: For Exception messages use the level EXCEPTION and the corresponding method AbstractLoggable.exception(String, Throwable), respectively.
  • Regular user information: Regularly, the user should get information via the exception log message, that conveniently could equal the message of the exception that caused logging the entry.
  • Detailed information: In debug mode, furthermore, the name of the exception that caused logging the severe log-entry and the stacktrace should be provided. Thus, logging a exception log-entry should include the exception. Use e.g. something like the following code:

    catch(SomeException e)
    {
            exception(e.getMessage(), e);
    }
    

Handling

Level specific handling

• Debugging: A handler responsible for debug messages should process only LogRecords of level DEBUG_FINE, DEBUG_FINER, or DEBUG_FINEST (e.g. by using DebugFilter). Additionally to setting the global debug mode to false, the DebugFilter can be configured to process messages above a certain level, but below level DEBUG_FINE. Thus, the developer can make finegrained use of levels DEBUG_FINE, DEBUG_FINER, and DEBUG_FINEST.
• Verbose messages for regular user information: A handler responsible for regular user information should process only LogRecords of level VERBOSE. The user should get provided with the pure message of the record.
• Warning messages for user information: A handler responsible for occuring user warnings should process only LogRecords of level WARNING. The user should get provided with the pure message of the record.
• Exception messages
  The handler responsible for exception messages should process only LogRecords of level EXCEPTION.
  • Regular user information: If DEBUG is false, the handler responsible for exception messages should provide the message of the LogEntry only.
  • In debug mode, one should get provided with more detailed information, as the name of the causing exception and the stacktrace.

Handling for Command Line Interface

• Debugging: Debug messages are printed immediately to System.err.
• Verbose messages for regular user information are printed immediately to System.out.
• Warning messages for user information are printed immediately to System.err.
• Exception messages are printed immediately to System.err.

Efficiency considerations (for development)

Coding the logging of debugging messages conditionally by a final boolean variable can result in a considerable speedup if the final boolean is false. This is the purpose of the recommendation given above, to specify a variable in each class that owns a logger:

private static final boolean DEBUG = LoggingConfiguration.DEBUG;

A debugging message can then get coded as follows:

if(DEBUG)
{
    debugFine("message\n"); // or: finer, finest
}

Most compilers will remove the code in the if-clause during compiling if it can be taken for sure that the condition will always be false (e.g. if it is a final boolean set to false). For class specific debugging, the developer will code the attribute as

private static final boolean DEBUG = true;

while for general debugging the developer could also set the central attribute LoggingConfiguration.DEBUG to true.

For reasons similar to debugging, the verbosity of an algorithm is restricted by a boolean variable rather than by choosing the granularity of loggers. Any verbose message for information of users is of the level LogLevel.VERBOSE. One could switch off the handler for verbose messages, but the logging of those messages will still be time consuming. Thus, the developer should log verbose messages also conditionally, like:

if(isVerbose())
{
    logger.verbose("message\n");
}

Configuration of logging behaviour

If a class uses its own main method, it is advisable to configure the loggers as follows:

if(LoggingConfiguration.isChangeable())
{
    LoggingConfiguration.configureRoot(LoggingConfiguration.CLI);
}

This ensures the behaviour of output of the log-entries to be consistent over the framework.

To perform this configuration could also be necessary in constructors of classes, if they are created befor any method is called that performs the logging-configuration already and logging is used within the constructor.

If the logging configuration should not be changed in the following (e.g. in case of a graphical user interface, that sets GUI-related handlers), one uses:

LoggingConfiguration.configureRootFinally(LoggingConfiguration.GUI);