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

Logging facility for controlling logging behavior of the complete framework.

See: Description

Class Summary

Class	Description
CLISmartHandler	Handler that handles output to the console with clever formatting.
ELKILogRecord	Base LogRecord class used in ELKI.
ErrorFormatter	Format a log record for error output, including a stack trace if available.
Logging	This class is a wrapper around Logger and LogManager offering additional convenience functions.
Logging.Level	Logging Level class.
LoggingConfiguration	Facility for configuration of logging.
LoggingUtil	This final class contains some static convenience methods for logging.
MessageFormatter	A formatter to simply retrieve the message of an LogRecord without printing origin information.
OutputStreamLogger	Class to write to Output Streams, IGNORING OutputStreamLogger.close(), with a special newline handling and always flushing.

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

Logging facility for controlling logging behavior of the complete framework.

Logging in ELKI

Logging in ELKI is closely following the Logger approach.

However, system-wide configuration of logging does not seem appropriate, therefore ELKI uses a configuration file named

 logging - cli.properties
 

living in the package de.lmu.ifi.dbs.elki.logging (or an appropriately named directory) for command line interface based operation.

Logging levels can be configured on a per-class or per-package level using, e.g.:

 de.lmu.ifi.dbs.elki.index.level = FINE
 

to set the logging level for the index structure package to FINE.

Logging for Developers:

Developers working in ELKI are encouraged to use the following setup to make configurable logging:

1. Introduce one or multiple static final debug flags in their classes:
   protected static final boolean debug = true || LoggingConfiguration.DEBUG;
   After development, it should be changed to false || LoggingConfiguration.DEBUG.
2. If the class contains 'frequent' logging code, acquire a static Logger reference:
   protected static final Logging logger = Logging.getLogger(Example.class);
3. Wrap logging statements in appropriate level checks:
   if (logger.isVerbose()) { // compute logging message logger.verbose(expensive + message + construction); }
4. For infrequent logging, the following static convenience function is appropriate: LoggingUtil.exception("Out of memory in algorithm.", exception);
   This function is expensive (it acquires a stack trace to obtain class and method references, retrieves a logger reference etc.) and thus should only be used for 'rare' logging events.
5. In cases where many tests would occur, also consider using:

    final boolean verbose = logger.isVerbose();
    // ... for, while, anything expensive
    if (verbose) {
      logger.verbose(...);
    }