Skip navigation.
Downloads | Product Documentation | Support

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:

- Overview of Distributing and Filtering Messages
- Setting the Level for Loggers and Handlers
- Setting a Filter for Loggers and Handlers

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

## 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:

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

2. 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):

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

2. Invokes the `Logger.getHandlers()` method.

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

3. 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.

4. 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:

1. 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.

2. Place the filter object in the classpath of the JVM on which the `Logger` object is running.
3. To set a filter for a `Logger` object, create a class that does the following:

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 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.

1. Invokes the `Logger.setFilter(Filter newFilter)` method.

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

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 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.

1. 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.

2. 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;
>             }
>         }
>     }