Using WebLogic Logging Services

Filtering WebLogic Server Log Messages

The WebLogic Server logging services provide several levels of filtering that give you the flexibility to determine which messages are written to the WebLogic Server log files and standard out, and to the log file and standard out that a client JVM maintains. Most of these filtering features are implementations of the JDK 1.4 logging APIs, which are available in the java.util.logging package.

The following sections describe how to filter messages that the WebLogic Server logging services generates:

Note: Prior to WebLogic Server 8.1, filtering was available only for the domain-wide log file and for any Java Management Extensions (JMX) listeners that you registered with the WebLogic Server logging services. For example, you could use a filter to determine which messages the Administration Server wrote to the domain-wide message log, but you could not use a filter to determine which messages a server instance wrote to its local log file. Server instances always wrote all messages to their local log files. With the introduction of the JDK 1.4 logging APIs in WebLogic Server 8.1, you can now create separate filters for the messages that each server instance writes to its local log file, to its standard out, or that it broadcasts to the domain-wide message log.

Overview of Distributing and Filtering Messages

When WebLogic Server message catalogs and the NonCatalogLogger generate messages, they distribute their messages to a java.util.logging.Logger object. The Logger object publishes the messages to any message handler that has subscribed to the Logger.

WebLogic Server instantiates Logger and Handler objects in three distinct contexts (See Figure 4-1):

In client JVMs that use WebLogic Server logging services. This client Logger object publishes messages that are sent from client applications running in the client JVM.

The following handlers subscribe to the Logger object in a client JVM:

ConsoleHandler, which prints messages from the client JVM to the client's standard out.

If you use the -Dweblogic.StdoutSeverityLevel Java startup option for the client JVM, WebLogic logging services create a filter for this handler that limits the messages that the handler writes to standard out. For more information, refer to Writing Messages from a Remote Application.

FileStreamHandler, which writes messages from the client JVM to the client's log file. For information about configuring log file for a client JVM, refer to Writing Messages from a Remote JVM to a File.

In each instance of WebLogic Server. This server Logger object publishes messages that are sent from subsystems and applications that run on a server instance.

The following handlers subscribe to the domain Logger object:

ConsoleHandler, which makes messages available to the server's standard out.
FileStreamHandler, which writes messages to the server's local log file.
The LogBroadcasterRuntimeMBean, which publishes to the domain Logger object on the Administration Server.

The Administration Server maintains a domain Logger object in addition to a server Logger object. The domain Logger object receives messages from each server's LogBroadcasterRuntimeMBean handler.

The following handler subscribes to the domain Logger object:

FileStreamHandler, which writes messages to the domain's log file.

Figure 4-1 JDK 1.4 and WebLogic Server Logging Services

JDK 1.4 and WebLogic Server Logging Services

Setting the Level and Filters

When WebLogic Server message catalogs and the NonCatalogLogger generate messages, they convert the message severity to a weblogic.logging.WLLevel object. A WLLevel object can specify any of the following values, from lowest to highest impact:

DEBUG, INFO, WARNING, ERROR, NOTICE, CRITICAL, ALERT, EMERGENCY

By default, a Logger object publishes messages of all levels. To set the lowest-level message that a Logger object publishes, you use a simple Logger.setLevel API. When a Logger object receives an incoming message, it checks the message level with the level set by the setLevel API. If the message level is below the Logger level, it returns immediately. If the message level is above the Logger level, the Logger allocates a WLLogRecord object to describe the message.

For example, if you set a Logger object's level to WARNING, the Logger object publishes only WARNING, ERROR, NOTICE, CRITICAL, ALERT, or EMERGENCY messages.

To provide more control over the messages that a Logger object publishes, you can also create and set a filter. A filter is a class that compares data in the WLLogRecord object with a set of criteria. The Logger object publishes only the WLLogRecord objects that satisfy the filter criteria. For example, a filter can configure a Logger to publish only messages from the JDBC subsystem. To create a filter, you instantiate a java.util.logging.Filter object and use the Logger.setFilter API to set it for a Logger object.

Instead of (or in addition to) setting the level and a filter for the messages that a Logger object publishes, you can set the level and filters on individual message handlers.

For example, you can specify that a Logger publishes messages that are of the WARNING level or higher. Then you can do the following for each handler:

For the ConsoleHandler, set a level and filter that selects only ALERT messages from the JDBC, JMS, and EJB subsystems. This causes standard out to display only ALERT messages from the JDBC, JMS, and EJB subsystems.
For the FileHandler, set no additional level or filter criteria. Because the Logger object has been configured to publish only messages of the WARNING level or higher, the log file will contain all messages from all subsystems that are of the WARNING level or higher.
The LogBroadcasterRuntimeMBean will publish all messages of the WARNING level or higher to the Logger object that the Administration Server uses to maintain the domain-wide message log.

Domain Log Filters

To filter the messages that the LogBroadcasterRuntimeMBean publishes, you can use the Administration Console to create a Domain Log Filter. Unlike the filters for Logger and Handler objects, a Domain Log Filter is implemented in JMX and is registered only with the LogBroadcasterRuntimeMBean that a server uses to publish messages to the domain Logger (in Figure 4-1, this filter is labeled Domain Log JMX Filter).

Any JDK 1.4 level or filter that you set on the Logger object that manages a server instance's local log file supersedes a Domain Log Filter. For example, if the level of the server's Logger object is set to WARNING, a Domain Log Filter will receive only messages of the WARNING level or higher.

Setting the Level for Loggers and Handlers

The Administration Console and the weblogic.Admin utility do not provide a way to set JDK 1.4 level and filters. You must use the Logger, ConsoleHandler, and FileStreamHandler APIs.

Setting the Level for Loggers

To set the level for a Logger object, create a class that does the following:

Invokes one of the following LoggingHelper methods:

getClientLogger if the current context is a client JVM.
getServerLogger if the current context is a server JVM and you want to retrieve the Logger object that a server uses to manage its local server log.
getDomainLogger if the current context is the Administration Server and you want to retrieve the Logger object that manages the domain log.

The LoggerHelper method returns a Logger object. For more information, refer to the Sun API documentation for Logger: http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html

Invokes the Logger.setLevel(WLevel level) method.

To set the level of a WebLogic Server Logger object, you must pass a value that is defined in the weblogic.logging.WLLevel class. For a list of valid values, refer to the WLLevel Javadoc.
For example:
setLevel(WLLevel.ALERT)

Setting the Level for Handlers

To set the level for a Handler object, create a class that does the following (see Listing 4-1):

Invokes one of the following LoggingHelper methods:

getClientLogger if the current context is a client JVM.
getServerLogger if the current context is a server JVM and you want to retrieve the Logger object that a server uses to manage its local server log.
getDomainLogger if the current context is the Administration Server and you want to retrieve the Logger object that manages the domain log.

The LoggerHelper method returns a Logger object. For more information, refer to the Sun API documentation for Logger: http://java.sun.com/j2se/1.4/docs/api/java/util/logging/Logger.html

Invokes the Logger.getHandlers() method.

The method returns an array of all handlers that are registered with the Logger object.

Iterates through the list of handlers until it finds the Handler object for which you want to set a level.

Use Handler.getClass().getName() to determine the type of handler to which the current array index refers.

Invokes the Handler.setLevel(WLevel level) method.

To set the level of a WebLogic Server Handler object, you must pass a value that is defined in the weblogic.logging.WLLevel class. For a list of valid values, refer to the WLLevel Javadoc.
For example:
setLevel(WLLevel.ALERT)

Listing 4-1 Example: Setting Level for a Handler Object

import java.util.logging.Logger;
import java.util.logging.Handler;

import weblogic.logging.LoggingHelper;
import weblogic.logging.WLLevel;

public class LogLevel {

    public static void main(String[] argv) throws Exception {

        Logger serverlogger = LoggingHelper.getServerLogger();
        Handler[] handlerArray = serverlogger.getHandlers();
        for (int i=0; i < handlerArray.length; i++) {
            Handler h = handlerArray[i];
            if(h.getClass().getName().equals
                      ("weblogic.logging.ConsoleHandler")){
                h.setLevel(WLLevel.getLevel( WLLevel.ALERT) ); 
            }
        }
    }
}

Setting a Filter for Loggers and Handlers

When you set a filter on the Logger object, the filter specifies which messages the object publishes; therefore, the filter affects all handlers that are registered with the Logger object. When you set a filter on a handler, the filter affects only the behavior of the specific handler.

To set a filter:

Create a class that implements java.util.logging.Filter. See Listing 4-2.

The class must include the Filter.isLoggable method and logic that evaluates incoming messages. If the logic evaluates as true, the isLoggable method enables the Logger object to publish the message.

Place the filter object in the classpath of the JVM on which the Logger object is running.

To set a filter for a Logger object, create a class that does the following:

Invokes one of the following LoggingHelper methods:

getClientLogger if the current context is a client JVM.
getServerLogger if the current context is a server JVM and you want to filter the Logger object that a server uses to manage its local server log.
getServerLogger if the current context is the Administration Server and you want to filter the Logger object that manages the domain server log.

Invokes the Logger.setFilter(Filter newFilter) method.

To set a filter for a Handler object, create a class that does the following:

Invokes one of the following LoggingHelper methods:

getClientLogger if the current context is a client JVM.
getServerLogger if the current context is a server JVM and you want to filter the Logger object that a server uses to manage its local server log.
getServerLogger if the current context is the Administration Server and you want to filter the Logger object that manages the domain server log.

Iterates through the list of handlers until it finds the Handler object for which you want to set a level.

Use Handler.getClass().getName() to determine the type of handler to which the current array index refers.

Invokes the Handler.setFilter(Filter newFilter) method.

Listing 4-2 provides an example class that rejects all messages from the Deployer subsystem.

Listing 4-2 Example Filter for a JDK 1.4 Logger Object

import java.util.logging.Logger;
import java.util.logging.Filter;
import java.util.logging.LogRecord;

import weblogic.logging.WLLogRecord;
import weblogic.logging.WLLevel;

public class MyFilter implements Filter {
    public boolean isLoggable(LogRecord record) {
        if (record instanceof WLLogRecord) {
            WLLogRecord rec = (WLLogRecord)record;
            if (rec.getLoggerName().equals("Deployer")) {
              return false;
            } else {
              return true;
            }
        } else {
          return false;
        }
    }
}