qflib 0.98.0

de.qfs.lib.log
Class Log

java.lang.Object
  |
  +--de.qfs.lib.log.Log

public class Log
extends java.lang.Object

The Log class coordiantes the logging of error and debug messages of different levels of importance. Currently 10 different levels of importance are defined, ranging from ERR for errors to DBGDETAIL for detailed debugging messages.

Apart from the messages themselves, the sending class and method will be noted, as well as the current time and the active Thread.

Log messages are best dispatched with the help of the Logger class.

Once logging is used seriously, the number of logged messages tends to grow rapidly. There are various ways to filter out messages, while still keeping important information, to reduce the impact of logging on CPU time and memory consumption.

The most expensive part of creating log messages is the construction of the message String, which often involves calls of toString() methods or concatenation. This cost can only be reduced by protecting the log call with some flag or level checking mechanism. A very flexible scheme that allows simple configuration of these levels as well as optional runtime modification is provided by the Logger class.

Once messages are created, the cheapest and most effective method to reduce logging is to set the pre-queue filter level with setPreQueueLevel. Messages with a level higher than the pre-queue level will be (almost) instantly discarded.

Messages passing the pre-queue filter mechanism can either be queued to be processed by a low level background thread at a later time, or passed on immediately. This is controlled with the setQueueing method. Queueing will reduce logging overhead drastically, but can increase memory consumption if the program is running constantly on a high load.

Queueing should be turned off before terminating a program, so that all pending messages will be flushed.

Once messages really get dispatched, they will be passed through a chain of filters, that must implement the LogFilter or the LogUser interface. These filters are intended primarily for diverting the messages to a log file or a remote log server.

Finally, if a message is still not filtered out, its level is checked against the current print level set with setOutputLevel and, if its level is less than or equal to the print level, it is passed to a LogWriter that can be cutomized with setLogWriter. The default writer used prints the messages to System.err.

To complicate things further, there is an additional mechanism. The pre-queue filter level is most useful when set rather low, so only error messages will pass. But if an error happens, the information needed to find out why is not available. To get at that information, a flush buffer can be used.

The flush buffer will save the last n messages that were filtered out during the pre-queue stage, where n can be set with setFlushBufferSize. When a message is logged that has a level less than or equal to a trigger level set with setFlushTriggerLevel, all saved messages will be recovered from the flush buffer und flushed onto the queue.

Since valuable information may also be logged after an error happened, the number of messages set with setPostFlushSize will pass unfiltered through the pre-queue stage after a flush was triggered.

Yet another filter mechanism is used for completely different reasons. If a LogFilter causes more messages to be logged, endless recursion or deadlocks are almost inevitable. To avoid those, filters that are creating log messages themselves, or call methods that may use logging, must make sure they call excludeThread before they start their work and includeThread when they are finished, preferably in a finally clause.

Version:
$Revision: 1.3 $
Author:
Gregor Schmid

Field Summary
static int DBG
          The level for debugging messages.
static int DBGDETAIL
          The level for details for debugging messages.
static boolean DEFAULT_DROP_ON_OVERFLOW
          The default drop on overflow flag: false.
static int DEFAULT_FLUSH_BUFFER_SIZE
          The default size of the flush buffer: 0.
static int DEFAULT_FLUSH_TRIGGER_LEVEL
          The default value for the flush trigger level: ERR.
static int DEFAULT_OUTPUT_LEVEL
          The default value for the output level: ERRDETAIL.
static int DEFAULT_POST_FLUSH_SIZE
          The default value for the post flush size: 10.
static int DEFAULT_PRE_QUEUE_LEVEL
          The default value for the pre queue level: ERRDETAIL.
static int DEFAULT_QUEUE_SIZE
          The default queue size: 3000.
static boolean DEFAULT_QUEUEING
          The default queueing flag: true.
static int ERR
          The level for error messages and other messages that should always be logged.
static int ERRDETAIL
          The level for details for error messages.
static int MSG
          The level for normal messages of medium importance.
static int MSGDETAIL
          The level for details for normal messages.
static int MTD
          The level for method calls.
static int MTDDETAIL
          The level for details for Method calls i.e. detailed parameter values.
static int WRN
          The level for warnings.
static int WRNDETAIL
          The level for details for warnings.
 
Constructor Summary
Log()
           
 
Method Summary
static void addFilter(LogFilter filter)
          Add a LogFilter to the front of the filter chain.
static void excludeThread()
          Exclude the current Thread from logging i.e. ignore every call to log from the current Thread.
static void excludeThread(java.lang.Thread thread)
          Exclude a Thread from logging i.e. ignore every call to log from the Thread.
static int getFlushBufferSize()
          Get the size of the flush buffer.
static int getFlushTriggerLevel()
          Get the level that will trigger a flush of the messages saved in the flush buffer.
static LogWriter getLogWriter()
          Get the LogWriter used for the default logging mechanism, i.e. to log the messages that have passed through the filter chain.
static int getOutputLevel()
          Get the current output log level.
static int getPostFlushSize()
          Get the number of messages to pass unfiltered through the pre-queue stage after a flush happened.
static int getPreQueueLevel()
          Return the current pre-queue level.
static int getQueueSize()
          Get the size of the queue where it starts to either block or drop entries.
static void includeThread()
          Let the current Thread log again.
static void includeThread(java.lang.Thread thread)
          Let a Thread log again.
static boolean isDropOnOverflow()
          Query whether the queue drops entries when it overflows.
static boolean isQueueing()
          Get the queueing state of the Log.
static void log(int level, long timestamp, java.lang.String clazz, java.lang.String method, java.lang.String message)
          Log a message.
static void log(int level, java.lang.String clazz, java.lang.String method, java.lang.Throwable throwable)
          Log an exception.
static void log(int level, java.lang.String clazz, java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
          Log an exception.
static void removeFilter(LogFilter filter)
          Remove a LogFilter from the filter chain.
static void setDropOnOverflow(boolean drop)
          Set whether entries should be dropped when the log queue overflows.
static void setFlushBufferSize(int size)
          Set the size of the flush buffer.
static void setFlushTriggerLevel(int level)
          Set the level that will trigger a flush of the messages saved in the flush buffer.
static void setLogWriter(LogWriter logWriter)
          Set the LogWriter to use for the default logging mechanism, i.e. to log the messages that have passed through the filter chain.
static void setOutputLevel(int level)
          Set the current output log level.
static void setPostFlushSize(int size)
          Set the number of messages to pass unfiltered through the pre-queue stage after a flush happened.
static void setPreQueueLevel(int level)
          Set the current pre-queue level.
static void setQueueing(boolean _queueing)
          Set the queueing state of the Log.
static void setQueueSize(int size)
          Set the maximum size of the log queue.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERR

public static final int ERR
The level for error messages and other messages that should always be logged.

ERRDETAIL

public static final int ERRDETAIL
The level for details for error messages.

WRN

public static final int WRN
The level for warnings.

WRNDETAIL

public static final int WRNDETAIL
The level for details for warnings.

MSG

public static final int MSG
The level for normal messages of medium importance.

MSGDETAIL

public static final int MSGDETAIL
The level for details for normal messages.

MTD

public static final int MTD
The level for method calls.

MTDDETAIL

public static final int MTDDETAIL
The level for details for Method calls i.e. detailed parameter values.

DBG

public static final int DBG
The level for debugging messages.

DBGDETAIL

public static final int DBGDETAIL
The level for details for debugging messages. These can sometimes produce an enormous amount of data.

DEFAULT_OUTPUT_LEVEL

public static final int DEFAULT_OUTPUT_LEVEL
The default value for the output level: ERRDETAIL.

DEFAULT_PRE_QUEUE_LEVEL

public static final int DEFAULT_PRE_QUEUE_LEVEL
The default value for the pre queue level: ERRDETAIL.

DEFAULT_QUEUEING

public static final boolean DEFAULT_QUEUEING
The default queueing flag: true.

DEFAULT_QUEUE_SIZE

public static final int DEFAULT_QUEUE_SIZE
The default queue size: 3000.

DEFAULT_DROP_ON_OVERFLOW

public static final boolean DEFAULT_DROP_ON_OVERFLOW
The default drop on overflow flag: false.

DEFAULT_FLUSH_BUFFER_SIZE

public static final int DEFAULT_FLUSH_BUFFER_SIZE
The default size of the flush buffer: 0.

DEFAULT_FLUSH_TRIGGER_LEVEL

public static final int DEFAULT_FLUSH_TRIGGER_LEVEL
The default value for the flush trigger level: ERR.

DEFAULT_POST_FLUSH_SIZE

public static final int DEFAULT_POST_FLUSH_SIZE
The default value for the post flush size: 10.
Constructor Detail

Log

public Log()
Method Detail

log

public static void log(int level,
                       long timestamp,
                       java.lang.String clazz,
                       java.lang.String method,
                       java.lang.String message)
Log a message.
Parameters:
level - The level of the message.
timestamp - The time when the message originated.
clazz - The name of the sending class.
method - The name of the sending method.
message - The message.

log

public static void log(int level,
                       java.lang.String clazz,
                       java.lang.String method,
                       java.lang.Throwable throwable)
Log an exception.
Parameters:
level - The level of the message.
clazz - The name of the sending class.
method - The name of the sending method.
throwable - The Throwable.

log

public static void log(int level,
                       java.lang.String clazz,
                       java.lang.String method,
                       java.lang.Throwable throwable,
                       java.lang.String detail)
Log an exception.
Parameters:
level - The level of the message.
clazz - The name of the sending class.
method - The name of the sending method.
throwable - The Throwable.
detail - Some extra info to log with the Exception name.

getLogWriter

public static LogWriter getLogWriter()
Get the LogWriter used for the default logging mechanism, i.e. to log the messages that have passed through the filter chain.

Returns:
The LogWriter currently in use.
Since:
0.98.0

setLogWriter

public static void setLogWriter(LogWriter logWriter)
Set the LogWriter to use for the default logging mechanism, i.e. to log the messages that have passed through the filter chain.

The default writer is a StreamLogWriter that writes the messages to System.err using a DefaultLogFormat.

Setting the writer to null will suppress the output.

Parameters:
logWriter - The LogWriter to use.
Since:
0.98.0

excludeThread

public static void excludeThread()
Exclude the current Thread from logging i.e. ignore every call to log from the current Thread.

excludeThread

public static void excludeThread(java.lang.Thread thread)
Exclude a Thread from logging i.e. ignore every call to log from the Thread.
Parameters:
thread - The Thread to exclude.

includeThread

public static void includeThread()
Let the current Thread log again.

includeThread

public static void includeThread(java.lang.Thread thread)
Let a Thread log again.
Parameters:
thread - The Thread to log entries from.

addFilter

public static void addFilter(LogFilter filter)
Add a LogFilter to the front of the filter chain.
Parameters:
filter - The filter to add.

removeFilter

public static void removeFilter(LogFilter filter)
Remove a LogFilter from the filter chain.
Parameters:
filter - The filter to remove

getOutputLevel

public static int getOutputLevel()
Get the current output log level.
Returns:
The current output log level.

setOutputLevel

public static void setOutputLevel(int level)
Set the current output log level.

After passing through both filter chains and the pre-queue level test, messages will be checked against this value. If their level is equal to or less than the current outout log level, thy will be printed to System.err.

Parameters:
level - Output log level to set.

getPreQueueLevel

public static int getPreQueueLevel()
Return the current pre-queue level.
Returns:
The current pre-queue level.

setPreQueueLevel

public static void setPreQueueLevel(int level)
Set the current pre-queue level.

Messages that have passed through the pre-queue filter chain will have their level checked against this value. If it is greater, they will be discarded, otherwise they will be passed on, either to be queued or sent through the post-queue filter chain directly.

Parameters:
level - The pre-queue level to set.

getFlushBufferSize

public static int getFlushBufferSize()
Get the size of the flush buffer.
Returns:
The flush buffer size or 0 to indicate no flush buffer.

setFlushBufferSize

public static void setFlushBufferSize(int size)
Set the size of the flush buffer. Setting it to 0 will turn the flush buffer off.
Parameters:
size - The size of the flush buffer.

getFlushTriggerLevel

public static int getFlushTriggerLevel()
Get the level that will trigger a flush of the messages saved in the flush buffer.
Returns:
The flush buffer's trigger level.

setFlushTriggerLevel

public static void setFlushTriggerLevel(int level)
Set the level that will trigger a flush of the messages saved in the flush buffer.
Parameters:
level - The trigger level to set.

getPostFlushSize

public static int getPostFlushSize()
Get the number of messages to pass unfiltered through the pre-queue stage after a flush happened.
Returns:
The number of messages to pass.

setPostFlushSize

public static void setPostFlushSize(int size)
Set the number of messages to pass unfiltered through the pre-queue stage after a flush happened.
Parameters:
size - The number of messages to pass.

isQueueing

public static final boolean isQueueing()
Get the queueing state of the Log.
Returns:
The queueing state of the Log.

setQueueing

public static final void setQueueing(boolean _queueing)
Set the queueing state of the Log. If queueing is true, log entries will be put on a queue and read by a low priority Thread during idle time. In this way, logging has the least performance impact, but entries logged just before a call to System.exit probably will not be logged.

Setting the queueing flag to false will cause the queue to be flushed.

Parameters:
queueing - The queueing state to set.

getQueueSize

public static int getQueueSize()
Get the size of the queue where it starts to either block or drop entries.
Returns:
The maximum size of the queue.

setQueueSize

public static void setQueueSize(int size)
Set the maximum size of the log queue.

When the log queue is full it will either block until entries are processed ore start to drop old entries, as determined by setDropOnOverflow.

The default maximum size is 3000.

Parameters:
size - The new size of the queue.

isDropOnOverflow

public static boolean isDropOnOverflow()
Query whether the queue drops entries when it overflows.
Returns:
True if the queue drops entries on overflow.

setDropOnOverflow

public static void setDropOnOverflow(boolean drop)
Set whether entries should be dropped when the log queue overflows. If this is set to false, as is the default, the queue will block when it is full, otherwise it will silently throw away old entries.

This setting should be used with care, especially when logging to a file, since missing log entries can be misleading. It is useful during debugging though, when only the last few messages are of interest anyway.

Parameters:
drop - Whether entries should be dropped.

qflib 0.98.0