Skip navigation.
Downloads | Product Documentation | Support

Configuring Log Files and Filtering Log Messages

# Configuring WebLogic Logging Services

The following sections describe WebLogic Server logging scenarios and basic configuration tasks. For detailed instructions on filtering and subscribing to messages, see Filtering WebLogic Server Log Messages and Subscribing to Messages.

- Configuration Scenarios
- Overview of Logging Services Configuration
- Logging Configuration Tasks: Main Steps
- Log4j and the Commons Logging API
- How to Use Log4j with WebLogic Logging Services
- How to Use the Commons API with WebLogic Logging Services
- Rotating Log Files
- Redirecting JVM Output

# Configuration Scenarios

WebLogic Server system administrators and developers configure logging output and filter log messages to troubleshoot errors or to receive notification for specific events.

The following tasks describe some logging configuration scenarios:

- Stop `DEBUG` and `INFO` messages from going to the log file.
- Allow `INFO` level messages from the HTTP subsystem to be published to the log file, but not to standard out.
- Specify that a handler publishes messages that are `WARNING` severity level or higher.
- Track log information for individual servers in a cluster.

# Overview of Logging Services Configuration

Volume control of logging is provided through the `LogMBean` interface. In the logging process, a logging request is dispatched to subscribed handlers or appenders. WebLogic Server provides handlers for sending log messages to standard out, the server log file, broadcasting messages to the domain log, remote clients, and a memory buffer for tail viewing log events in the WebLogic Server Administration Console. You can achieve volume control for each type of handler by filtering log messages based on severity level and other criteria. The `LogMBean` defines attributes for setting the severity level and specifying filter criteria for WebLogic Server handlers.

In earlier versions of WebLogic Server, system administrators and developers had only programmatic access to loggers and handlers. In this release of WebLogic Server, you can configure handlers using MBeans, eliminating the need to write code for most basic logging configurations. The Administration Console and WebLogic Server Scripting Tool (WLST) provide an interface for interacting with logging MBeans. Additionally, you can specify `LogMBean` parameters on the command line using `Dweblogic.log.``attribute-name``=``value`; for example, `Dweblogic.log.StdoutSeverity=Debug`. See "weblogic.Server Configuration Options" in weblogic.Server Command-Line Reference.

For advanced usage scenarios and for configuring loggers, you use the Java Logging APIs.

Setting the severity level on a handler is the simplest type of volume control; for example, any message of a lower severity than the specified threshold severity level, will be rejected. For example, by default, the Stdout Handler has a `NOTICE` threshold severity level. Therefore, `INFO` and `DEBUG` level messages are not sent to standard out.

Configuring a filter on a handler lets you specify criteria for accepting log messages for publishing; for example, only messages from the HTTP and JDBC subsystems are sent to standard out.

Note: java.util.logging.LoggingPermission is required for a user to change the configuration of a logger or handler. In production environments, BEA Systems recommends using the Java Security Manager with `java.util.logging.LoggingPermission` enabled for the current user.

See "Using the Java Security Manager to Protect WebLogic Resources" in Programming WebLogic Security and the Sun API documentation at http://java.sun.com/j2se/1.5.0/docs/guide/logging/overview.html.

The following sections describe in more detail the control points for configuring WebLogic Server logging behavior.

## Using Log Severity Levels

Each log message has an associated severity level. The level gives a rough guide to the importance and urgency of a log message. WebLogic Server has predefined severities, ranging from `TRACE` to `EMERGENCY`, which are converted to a log level when dispatching a log request to the logger. A log level object can specify any of the following values, from lowest to highest impact:

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

You can set a log severity level on the logger and the handler. When set on the logger, none of the handlers receive an event which is rejected by the logger. For example, if you set the log level to `NOTICE` on the logger, none of the handlers will receive `INFO` level events. When you set a log level on the handler, the restriction only applies to that handler and not the others. For example, turning `DEBUG` off for the File Handler means no `DEBUG` messages will be written to the log file, however, `DEBUG` messages will be written to standard out.

See the weblogic.logging.Severities class for a description of the supported severity levels.

You set log levels for handlers using the Administration Console, WLST, or the command line. Loggers are configured only through the API. See Setting the Severity Level for Loggers and Handlers.

## Using Log Filters

To provide more control over the messages that a `Logger` object publishes, you can create and set a filter. A filter is a class that uses custom logic to evaluate the log record content which you use to accept or reject a log message; for example, to filter out messages of a certain severity level, from a particular subsystem, or according to specified criteria. The `Logger` object publishes only the log messages that satisfy the filter criteria. You can create separate filters for the messages that each server instance writes to its server log file, standard out, memory buffer, or broadcasts to the domain-wide message log.

You can associate a filter with loggers and handlers. You configure filters for handlers using the Administration Console, WLST, or the command line. There are `LogFilterMBean` attributes to define filters for Stdout, Log File, Log Broadcaster, and Memory Handlers, or you can implement custom filtering logic programmatically. The `LogFilterMBean` interface defines the filtering criteria based on user ID and subsystem. Filters for loggers are configured only through the API.

See Setting a Filter for Loggers and Handlers.

# Logging Configuration Tasks: Main Steps

The following steps summarize how you configure and filter log messages that WebLogic Server generates. Related documentation and later sections in this guide describe these steps in more detail.

1. Use the Administration Console to manage log files and configure the following logging options:

1. Domain and server log file name and location, rotation pattern, location of archived log files, and number of log files stored. See "View and Configure Logs" in the Administration Console Online Help.
2. Types of messages that the server sends to standard out. See "Specify Messages for Standard Out" in the Administration Console Online Help.
3. Which messages a server instance sends to the domain log. See "Specifying the Messages That a Server Forwards to the Domain Log" in the Administration Console Online Help.
4. Log files for HTTP requests. See "Enabling and Configuring HTTP Access Logs" in the Administration Console Online Help.
5. Specify the logging implementation (Java Logging or Log4j). See How to Use Log4j with WebLogic Logging Services.
6. Specify message destination and configure filtering log messages by severity level or other criteria. See "Filter Log Messages" in the Administration Console Online Help.

2. Alternatively, configure filtering log messages on the message handler using the WebLogic Scripting Tool. See "Configuring Logging" in WebLogic Scripting Tool.
3. Filter log messages published by the logger using the Java APIs. See Filtering Messages by Severity Level or Other Criteria.

# Log4j and the Commons Logging API

Application developers who want to use the WebLogic Server message catalogs and logging services as a way for their applications to produce log messages must know XML and the Java APIs. Many developers and system administrators use Log4j, which is a predecessor to the Java Logging APIs. Log4j is an open source tool developed for putting log statements in your application. The Log4j Java logging facility was developed by the Jakarta Project of the Apache Foundation. You can learn more about Log4j at The Log4j Project at `http://logging.apache.org/log4j/docs/.`

WebLogic Server supports Log4j as a configuration option for WebLogic logging services. See How to Use Log4j with WebLogic Logging Services.

The Jakarta Commons Logging APIs provide an abstraction layer that insulates users from the underlying logging implementation, which can be Log4j or Java Logging APIs. WebLogic Server provides an implementation of the Commons `LogFactory` interface, letting you issue requests to the server `Logger` using this API. See How to Use the Commons API with WebLogic Logging Services.

## About Log4j

Log4j has three main components: loggers, appenders, and layouts. The following sections provide a brief introduction to Log4j.

### Loggers

Log4j defines a `Logger` class. An application can create multiple loggers, each with a unique name. In a typical usage of Log4j, an application creates a `Logger` instance for each application class that will emit log messages. Loggers exist in a namespace hierarchy and inherit behavior from their ancestors in the hierarchy.

### Appenders

Log4j defines appenders (handlers) to represent destinations for logging output. Multiple appenders can be defined. For example, an application might define an appender that sends log messages to standard out, and another appender that writes log messages to a file. Individual loggers might be configured to write to zero or more appenders. One example usage would be to send all logging messages (all levels) to a log file, but only `ERROR` level messages to standard out.

### Layouts

Log4j defines layouts to control the format of log messages. Each layout specifies a particular message format. A specific layout is associated with each appender. This lets you specify a different log message format for standard out than for file output, for example.

# How to Use Log4j with WebLogic Logging Services

WebLogic logging services use an implementation based on the Java Logging APIs, by default. Using the `LogMBean.isLog4jLoggingEnabled` attribute, you can direct the logging services to use Log4j instead.

In the Administration Console, you can specify Log4j or keep the default Java Logging implementation. (See "Specifying the Logging Implementation" in the Administration Console Online Help.)

Alternatively, you can configure Log4j logging through the `LogMBean` interface and by adding WebLogic-specific Log4j classes, `WL_HOME``/server/lib/wllog4j.jar`, and the `log4j.jar` file to the server `CLASSPATH`. The recommended way to do this is to place the `wllog4j.jar` and `log4j.jar` files in the `DOMAIN_NAME``/lib` directory; there, they will get added to the server `CLASSPATH` dynamically during server startup.

Note: WebLogic Server does not provide a Log4j version in its distribution.

When Log4j is enabled, you get a reference to the `org.apache.log4j.Logger` that the server is using from the `weblogic.logging.log4j.Log4jLoggingHelper` class.

With a Log4j `Logger` reference, you can attach you own custom appender to receive the server log events; for example, you might attach an appender that sends the server log events to Syslog or the Windows Event Viewer. Additionally, you can use the `Logger` reference to issue log requests to WebLogic logging services; this requires that the Log4j libraries be available to your deployed application.

If your application has no requirement to interact with WebLogic logging services, package the Log4j libraries in the application's `LIB` directory. The server logging will continue to use the default Java Logging implementation.

See Listing 3-2, a Log4j code example that demonstrates using the Log4j `Logger`.

## Enabling Log4j Logging

To specify logging to a Log4j `Logger` instead of the default Java Logging:

- When you start the Administration Server, include the following Java option in the `weblogic.Server` command:

`-Dweblogic.log.Log4jLoggingEnabled=true`

See "weblogic.Server Configuration Options" in weblogic.Server Command-Line Reference.

- After the Administration Server has started, use the Administration Console to specify the Log4j logging implementation. See "Specifying the Logging Implementation" in the Administration Console Online Help.
- Use the WLST to set the value of the `Log4jLoggingEnabled` property and re-start the server.

The WLST commands in Listing 3-1 enable logging to a Log4j `Logger` in the Administration Server:

Listing 3-1 Enabling Log4j Logging

>     #invoke WLST
>     C:\>java weblogic.WLST

>     #connect WLST to an Administration Server
>     wls:/offline> connect('username','password')

>     #navigate to the writable MBean configuration tree
>     wls:/mydomain/serverConfig> edit()
>     wls:/mydomain/edit> startEdit()

>     #set cmo to the server log config
>     wls:/mydomain/edit !> cd("Servers/myserver/Log/myserver")

>     #set log4j logging to true
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> cmo.setLog4jLoggingEnabled(true)

>     #save and activate the changes
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> save()
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> activate()

For more information about using WLST, see "Editing Configuration MBeans" in WebLogic Scripting Tool. For more information about `isLog4jLoggingEnabled`, see LogMBean in the WebLogic Server MBean Reference.

You can enable Log4j for the server `Logger` as well as the domain `Logger`, which resides only on the Administration Server. The domain Log4j `Logger` reference is provided by invoking the `weblogic.logging.log4j.Log4jLoggingHelper.getLog4jDomainLogger()` method.

See Listing 3-2 and Listing 3-3, Log4j logging configuration examples that show:

- The server `Logger` using Log4j and the domain `Logger` using the default Java `Logger`.
- How to specify a severity level for Stdout and a filter for messages going to the server log file in the `config.xml` file.

Listing 3-2 Log4j Code Example

>     import org.apache.log4j.Logger;
>     import weblogic.logging.log4j.Log4jLoggingHelper;
>     import weblogic.logging.LoggerNotAvailableException;

>     /**
>      * This example shows how to use the Log4j server Logger.
>      */

>     public class MyLog4jTest {
>       public void testWLSLog4j() {
>         try {
>           Logger logger = Log4jLoggingHelper.getLog4jServerLogger();
>           logger.addAppender(myAppender); // The Appender is configured using either the log4j props file or other custom mechanism.
>           logger.info("Test log message");
>         } catch(LoggerNotAvailableException lex) {
>         System.err.println("Unable to get a reference to the log4j Logger: "+
>           lex.getMessage())
>         }
>       }
>     }

Listing 3-3 Logging Configuration Example

>     <con:log>
>         <con:name>medrec</con:name>
>         <con:file-name>medrec.log</con:file-name>
>         <con:rotation-type>bySize</con:rotation-type>
>         <con:file-min-size>20000</con:file-min-size>
>         <con:log4j-logging-enabled>false</con:log4j-logging-enabled>
>     </con:log>

>     <con:log>
>         <con:name>MedRecServer</con:name>
>         <con:rotation-type>bySize</con:rotation-type>
>         <con:file-min-size>20000</con:file-min-size>
>         <con:stdout-severity>Debug</con:stdout-severity>
>         <con:stdout-filter>MyFilter</con:stdout-filter>
>         <con:log4j-logging-enabled>true</con:log4j-logging-enabled>
>     </con:log>

>     <con:log-filter>
>         <con:name>MyFilter</con:name>
>         <con:subsystem-name>HTTP</con:subsystem-name>
>         <con:subsystem-name>IIOP</con:subsystem-name>
>         <con:subsystem-name>JDBC</con:subsystem-name>
>         <con:subsystem-name>JMS</con:subsystem-name>
>     </con:log-filter>

You have programmatic access to the Log4j `Logger` and its appenders (handlers) and layouts (formatters) for configuration purposes. See Setting a Severity Level and Filter on a Log4j Appender.

Java Logging is the default for client and server-side logging; Log4j is available only for server-side and not client-side logging.

# How to Use the Commons API with WebLogic Logging Services

WebLogic logging services provide the Commons `LogFactory` and `Log` interface implementations that direct requests to the underlying logging implementation being used by WebLogic logging services.

To use Commons Logging, put the WebLogic-specific Commons classes, `WL_HOME``/server/lib/wlcommons-logging.jar`, together with the `commons-logging.jar` file in one of the following locations:

- `APP-INF/LIB` or `WEB-INF/LIB` directory
- DOMAIN_NAME`/LIB` directory
- server `CLASSPATH`

Note: WebLogic Server does not provide a Commons logging version in its distribution.

Listing 3-4 illustrates how to use the Commons interface:

1. Set the system property `org.apache.commons.logging.LogFactory` to `weblogic.logging.commons.LogFactoryImpl`.

This `LogFactory` creates instances of `weblogic.logging.commons.LogFactoryImpl` that implement the `org.apache.commons.logging.Log` interface.

2. From the `LogFactory`, get a reference to the Commons `Log` object by name.

This name appears as the subsystem name in the log file.

3. Use the `Log` object to issue log requests to WebLogic logging services.

The Commons `Log` interface methods accept an object. In most cases, this will be a string containing the message text. In addition, WebLogic logging supports passing a `weblogic.logging.commons.CommonsLogObject` reference as argument to the `Log` methods.

The Commons `LogObject` takes a message ID, subsystem name, and a string message argument in its constructor. See org.apache.commons.logging at `http://jakarta.apache.org/commons/logging/api/index.html`.

4. The `weblogic.logging.commons.LogImpl` log methods direct the message to the server log.

Listing 3-4 Commons Code Example

>     import org.apache.commons.logging.LogFactory;
>     import org.apache.commons.logging.Log;
>     import weblogic.logging.commons.CommonsLogObject;

>     public class MyCommonsTest {
>       public void testWLSCommonsLogging() {
>         System.setProperty(LogFactory.FACTORY_PROPERTY,
>           "weblogic.logging.commons.LogFactoryImpl");
>         Log clog = LogFactory.getFactory().getInstance("MyCommonsLogger");
>         // Log String objects
>         clog.debug("Hey this is common debug");
>         clog.fatal("Hey this is common fatal", new Exception());
>         clog.error("Hey this is common error", new Exception());
>         clog.trace("Dont leave your footprints on the sands of time");
>         // Log using the CommonsLogObject
>         clog.fatal(new CommonsLogObject("BEA-420000", "Console", "Just a test"));
>       }
>     }

# Rotating Log Files

By default, when you start a WebLogic Server instance in development mode, the server automatically renames (rotates) its local server log file as `SERVER_NAME.``log``.n`. For the remainder of the server session, log messages accumulate in `SERVER_NAME``.log` until the file grows to a size of 500 kilobytes.

Each time the server log file reaches this size, the server renames the log file and creates a new `SERVER_NAME``.log` to store new messages. By default, the rotated log files are numbered in order of creation `filenamennnnn`, where `filename` is the name configured for the log file. You can configure a server instance to include a time and date stamp in the file name of rotated log files; for example, `server-name-%yyyy%-%mm%-%dd%-%hh%-%mm%`.`log`.

By default, when you start a server instance in production mode, the server rotates its server log file whenever the file grows to 5000 kilobytes in size. It does not rotate the local server log file when you start the server. For more information about changing the mode in which a server starts, see "Change to Production Mode" in the Administration Console Online Help.

You can change these default settings for log file rotation. For example, you can change the file size at which the server rotates the log file or you can configure a server to rotate log files based on a time interval. You can also specify the maximum number of rotated files that can accumulate. After the number of log files reaches this number, subsequent file rotations delete the oldest log file and create a new log file with the latest suffix.

Note: WebLogic Server sets a threshold size limit of 500 MB before it forces a hard rotation to prevent excessive log file growth.

For information on setting up log file rotation, see "Rotating Log Files" in the Administration Console Online Help.

To cause the immediate rotation of the server, domain, or HTTP access log file, use the `LogRuntime.forceLogRotation()` method. See LogRuntimeMBean in the WebLogic Server MBean Reference.

The WLST commands in Listing 3-5 cause the immediate rotation of the server log file.

Listing 3-5 Log Rotation on Demand

>     #invoke WLST
>     C:\>java weblogic.WLST

>     #connect WLST to an Administration Server
>     wls:/offline> connect('username','password')

>     #navigate to the ServerRuntime MBean hierarchy
>     wls:/mydomain/serverConfig> serverRuntime()
>     wls:/mydomain/serverRuntime>ls()

>     #navigate to the server LogRuntimeMBean
>     wls:/mydomain/serverRuntime> cd('LogRuntime/myserver')
>     wls:/mydomain/serverRuntime/LogRuntime/myserver> ls()
>     -r--   Name                                         myserver
>     -r--   Type                                         LogRuntime

>     -r-x   forceLogRotation                             java.lang.Void :

>     #force the immediate rotation of the server log file
>     wls:/mydomain/serverRuntime/LogRuntime/myserver> cmo.forceLogRotation()
>     wls:/mydomain/serverRuntime/LogRuntime/myserver>

The server immediately rotates the file and prints the following message:

>     <Mar 2, 2005 3:23:01 PM EST> <Info> <Log Management> <BEA-170017> <The log file C:\diablodomain\servers\myserver\logs\myserver.log will be rotated. Reopen the log file if tailing has stopped. This can happen on some platforms like Windows.>

>     <Mar 2, 2005 3:23:01 PM EST> <Info> <Log Management> <BEA-170018> <The log file has been rotated to C:\diablodomain\servers\myserver\logs\myserver.log00001. Log messages will continue to be logged in C:\diablodomain\servers\myserver\logs\myserver.log.>

## Specifying the Location of Archived Log Files

By default, the rotated files are stored in the same directory where the log file is stored. You can specify a different directory location for the archived log files by using the Administration Console or setting the `LogFileRotationDir` property of the `LogFileMBean` from the command line. See LogFileMBean in the WebLogic Server MBean Reference.

The following command specifies the directory location for the archived log files using the `-Dweblogic.log.LogFileRotationDir` Java startup option:

>     java -Dweblogic.log.LogFileRotationDir=c:\foo
>     -Dweblogic.management.username=installadministrator
>     -Dweblogic.management.password=installadministrator weblogic.Server

## Notification of Rotation

When the log file exceeds the rotation threshold that you specify, the server instance prints a log message that states that the log file will be rotated. Then it rotates the log file and prints an additional message that indicates the name of the file that contains the old messages.

For example, if you set up log files to rotate by size and you specify 500K as the minimum rotation size, when the server determines that the file is greater than 500K in size, the server prints the following message:

>     <Sept 20, 2004 1:51:09 PM EST> <Info> <Log Management> <MachineName> <MedRecServer> <ExecuteThread: '2' for queue: 'weblogic.kernel.System'> <<WLS Kernel>> <> <> <1095692939895> <BEA-170017> <The log file C:\bea\wls\samples\domains\medrec\servers\MedRecServer\logs\medrec.log will be rotated. Reopen the log file if tailing has stopped. This can happen on some platforms like Windows.>

The server immediately rotates the file and prints the following message:

>     <Sept 20, 2004 1:51:09 PM EST> <Info> <Log Management> <MachineName> <MedRecServer> <ExecuteThread: '2' for queue: 'weblogic.kernel.System'> <<WLS Kernel>> <> <> <1095692939895> <BEA-170018> <The log file has been rotated to C:\bea\wls\samples\domains\medrec\servers\MedRecServer\logs\medrec.log00001. Log messages will continue to be logged in C:\bea\wls\samples\domains\medrec\servers\MedRecServer\logs\medrec.log.>

Note that the severity level for both messages is `INFO`. The message ID for the message before rotation is always `BEA-170017` and the ID for the message after rotation is always `BEA-170018`.

File systems such as the standard Windows file system place a lock on files that are open for reading. On such file systems, if your application is tailing the log file, or if you are using a command such as the DOS `tail -f` command in a command prompt, the tail operation stops after the server has rotated the log file. The `tail -f` command prints messages to standard out as lines are added to a file. For more information, enter `help tail` in a DOS prompt.

To remedy this situation for an application that tails the log file, you can create a JMX listener that notifies your application when the server emits the log rotation message. When your application receives the message, it can restart its tailing operation. To see an example of a JMX listener, see Subscribing to Messages.

# Redirecting JVM Output

The JVM in which a WebLogic Server instance runs, sends messages to standard error and standard out. Server as well as application code write directly to these streams instead of using the logging mechanism. Through a configuration option, you can redirect the JVM output to all the registered log destinations, like the server terminal console and log file. When enabled, a log entry appears as a message of `NOTICE` severity. Redirecting the JVM output does not capture output from native code, for example thread dumps from the JVM.

For example, to redirect the JVM standard out messages:

- When you start the Administration Server, include the following Java option in the `weblogic.Server` command:

`-Dweblogic.log.RedirectStdoutToServerLogEnabled=true`

See "weblogic.Server Configuration Options" in weblogic.Server Command-Line Reference.

- After the Administration Server has started, use the Administration Console to redirect the JVM standard out messages. See "Redirect JVM Output" in the Administration Console Online Help.
- Use the WLST to change the value of the `RedirectStdoutToServerLogEnabled` property of the `LogMBean` and re-start the server.

The WLST commands in Listing 3-6 redirect the JVM standard out messages in the Administration Server to the server logging destinations.

Listing 3-6 Redirecting Stdout to Server Logging Destinations

>     C:\>java weblogic.WLST
>     wls:/offline> connect('username','password')
>     wls:/mydomain/serverConfig> edit()
>     wls:/mydomain/edit> startEdit()
>     wls:/mydomain/edit !> cd("Servers/myserver/Log/myserver")
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> cmo.setRedirectStdoutToServerLogEnabled(true)
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> save()
>     wls:/mydomain/edit/Servers/myserver/Log/myserver !> activate()

For more information about using WLST, see "Editing Configuration MBeans" in WebLogic Scripting Tool. For more information about `RedirectStdoutToServerLogEnabled`, see LogMBean in the WebLogic Server MBean Reference.