|
qflib 0.98.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--de.qfs.lib.log.Log
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.
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 |
public static final int ERR
public static final int ERRDETAIL
public static final int WRN
public static final int WRNDETAIL
public static final int MSG
public static final int MSGDETAIL
public static final int MTD
public static final int MTDDETAIL
public static final int DBG
public static final int DBGDETAIL
public static final int DEFAULT_OUTPUT_LEVEL
public static final int DEFAULT_PRE_QUEUE_LEVEL
public static final boolean DEFAULT_QUEUEING
public static final int DEFAULT_QUEUE_SIZE
public static final boolean DEFAULT_DROP_ON_OVERFLOW
public static final int DEFAULT_FLUSH_BUFFER_SIZE
public static final int DEFAULT_FLUSH_TRIGGER_LEVEL
public static final int DEFAULT_POST_FLUSH_SIZE
Constructor Detail |
public Log()
Method Detail |
public static void log(int level, long timestamp, java.lang.String clazz, java.lang.String method, java.lang.String message)
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.public static void log(int level, java.lang.String clazz, java.lang.String method, java.lang.Throwable throwable)
level
- The level of the message.clazz
- The name of the sending class.method
- The name of the sending method.throwable
- The Throwable.public static void log(int level, java.lang.String clazz, java.lang.String method, java.lang.Throwable throwable, java.lang.String detail)
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.public static LogWriter getLogWriter()
LogWriter
used for the default logging
mechanism, i.e. to log the messages that have passed through the filter
chain. public static void setLogWriter(LogWriter logWriter)
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.
logWriter
- The LogWriter to use.public static void excludeThread()
log
from the current Thread.public static void excludeThread(java.lang.Thread thread)
log
from the Thread.thread
- The Thread to exclude.public static void includeThread()
public static void includeThread(java.lang.Thread thread)
thread
- The Thread to log entries from.public static void addFilter(LogFilter filter)
filter
- The filter to add.public static void removeFilter(LogFilter filter)
filter
- The filter to removepublic static int getOutputLevel()
public static void setOutputLevel(int 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.
level
- Output log level to set.public static int getPreQueueLevel()
public static void setPreQueueLevel(int 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.
level
- The pre-queue level to set.public static int getFlushBufferSize()
public static void setFlushBufferSize(int size)
size
- The size of the flush buffer.public static int getFlushTriggerLevel()
public static void setFlushTriggerLevel(int level)
level
- The trigger level to set.public static int getPostFlushSize()
public static void setPostFlushSize(int size)
size
- The number of messages to pass.public static final boolean isQueueing()
public static final void setQueueing(boolean _queueing)
Setting the queueing flag to false will cause the queue to be flushed.
queueing
- The queueing state to set.public static int getQueueSize()
public static void setQueueSize(int size)
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.
size
- The new size of the queue.public static boolean isDropOnOverflow()
public static void setDropOnOverflow(boolean drop)
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.
drop
- Whether entries should be dropped.
|
qflib 0.98.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |