Filtering
Grace Software
JavaLog

$Revision: 1.3 $
$Date: 2000/02/02 14:34:23 $




Introduction

JavaLog code is meant to remain in your source code forever. In other words, it should not be removed for production, like print statements. So to make this efficient, JavaLog provides a runtime filtering system that allows the runtime user to selectively include and exclude events based on regular expression pattern matching.

JavaLog uses the GNU regular expression library to express runtime filtering patterns. Events are filtered in two passes. In the first pass, the event type is filtered using a Hashtable lookup. This is fast so that users can efficiently filter in and out event types that are not pertinent to the mode of operation of the software. In the second pass, other attributes of an event can be used in include/exclude criteria. This pass is slower since each include/exclude criterion is evaluated against each event. The remainder of this page describes how to filter JavaLog events at runtime using regular expressions.

JavaLog has two types of filtering - old and new. The old is being maintained for compatibility but it will eventually go away. The rest of this document describes the old style global event formatting. Go here for a description of the new runtime filter expression system.

Event Type Filtering

Event type filtering can be accomplished at compile time and and run time using one ore more filters. A filter is simply a regular expression. In both run time and compile time cases, a collection of filters is specified as a string of space separated regular expressions. Obviously, this means that a filter can not contain a space. So, a filter like: "err.* s.*" means all events whose type begins with "err" or "s". Currently, filters can be included filters or exclude filters. Include filters are filters that pass the a potential event to the handlers and, thus, are logged. Exclude filters stop a potential event from being passed to the handlers and, thus, are not logged.

Include filters are, by default, set to include everything, ".*", and exclude filters are, by default, set to exclude nothing, "". If an include filter is then set, it replaces the default ".*" pattern. Also, note that the default include filter is affected by the -Dlog=false properties. If this property is set false, the default include pattern is set to include nothing, ".*".

Compile time filtering is accomplished using the Log.setEventsTypesToInclude(String filter) and setEventTypesToExclude(String filter) functions of the Log.

General Runtime Event Filtering

Run time filtering is accomplished using the -Dlog.event.include=filters and -Dlog.event.exclude=filters properties. 

    java -Dlog.event.include="error.*" -Dlog.event.exclude="error1.*"
would include all events whose type starts with "error" but then exclude those that started with "error1".

Numeric Event Type Filtering

Again, using numeric event types is discouraged but many systems use numeric logging levels so it may be useful to continue to use numeric levels in JavaLog with filtering. So, suppose one is using numeric event types such as in the following code: 
    Log.log("1", "information");    
    Log.log("2", "information");    
    Log.log("4", "information");    
    Log.log("20", "debug");    
    Log.log("25", "detailed debug");    
    Log.log("26", "detailed debug");    
    Log.log("30", "super detailed debug");
Then the using the command line filter -Dlog.events.include=filter, the user can filter these numeric levels to suit his debugging or logging needs. The following table illustrates some possibilities.

log.events.include Included Event Types
[12] 2. 1, 2, 20, 25, 26
1 2. 1, 20, 25, 26
[1-4] 2[5-9] 1, 2, 4, 25, 26

Function Filtering

Functions are filtered almost identically to the event types. They are filtered by the functions: Log.setFunctionsToInclude(String filter) and setFunctionsToExclude(String filter) functions of the Log. or at runtime using the properties -Dlog.function.include= filters and -Dlog.function.exclude= filters properties.