BEA Home | Events | Solutions | Partners | Products | Services | Download | Developer Center | WebSUPPORT
| WebLogic Server Doc Home | Administration Guide | Previous Topic | Next Topic | Contents | Index | View as PDF

Using Log Messages to Manage WebLogic Servers

The following sections describe the functions of the logging subsystem:

- Overview of Logging Subsystem

- Local Server Log Files

- Message Attributes

- Message Catalog

- Message Severity

- Browsing Log Files

- Creating Domain Log Filters

Overview of Logging Subsystem

Log messages are a useful tool for managing systems. They allow you to detect problems, track down the source of a fault, and track system performance. Log messages generated by the WebLogic Server software are stored in two locations:

- WebLogic Server component subsystems generate messages that are logged to a local file, that is, a file that resides on the machine where the server is running. If there are multiple servers on a machine, each server has its own log file. Applications deployed on your WebLogic Servers may also log messages to the server's local log file.

- In addition, a subset of messages logged locally are stored in a central domain-wide log file maintained by the Administration Server.

Java Management Extension (JMX) facilities, embedded in the WebLogic Server, are used to transmit log messages from WebLogic Servers to the Administration Server. A message forwarded to other entities on the initiative of a local WebLogic Server is called a notification in JMX terminology.

When a WebLogic server starts, the Administration Server's message handler registers with that server to receive log messages. At the time of registration, a user-modifiable filter is provided that is used by the local server to select the messages to be forwarded to the Administration Server. These messages are collected in the domain log.

If the Administration Server is unavailable, Managed Servers continue to write messages to their local log files, but they do not keep track of which messages they generate while the Administration Server is unavailable. For example, if the Administration Server is unavailable for two hours and then is restored, the domain log will not contain any messages that were generated during the two hours.

By default, only the most important log messages (as determined by Message Severity) are forwarded from the local servers to the domain log. The domain log gives you an overall view of the entire domain while focusing on just the most critical messages.

If you want to modify the filter, to receive a different subset of logged messages from a local server, you can do so dynamically, using the Administration Console. You do not need to restart the local server for your changes to take effect. (See Creating Domain Log Filters.)

Developers can also build custom message handlers that can register with a WebLogic Server to receive log messages via JMX notifications.

Figure 6-1 WebLogic Server Logging Subsystem

Local Server Log Files

In versions of WebLogic Server prior to 6.0, a new log file is created once the log file reaches a maximum log file size. This type of automatic log file creation is called log rotation. In the current release, you have the option of basing log file rotation either on size or on time. To configure rotation, open the Administration Console and do the following:

1. In the left pane, select a server.

2. In the right pane, select Logging—>Rotation.

3. In the Rotation Type field, select `By Size` or `By Date`.

   - `By Size:` Rotates the log when it exceeds the value entered into the File Min Size parameter.

   - `By Date:` Rotates the log after the number of minutes specified with the File Time Span parameter.

4. If you have selected `Size` as the Rotation Type, in the File Min Size field specify the file size (1 - 65535 kilobytes) that triggers the server to move log messages to a separate file.

   After the log file reaches the specified size, the next time the server checks the file size, it will rename the current log file and create a new one to store subsequent messages.

5. If you have selected Date as the Rotation Type, set the Rotation Time to the first date when you want the log file to rotate.

   Use the following format: `hh`:`mm`, where `hh` is the hour in a 24-hour format and `mm` is the minute.

   If the time that you specify has already past, then the server starts its file rotation immediately.

6. If you have selected Date as the Rotation Type, set the File Time Span to the number of hours after which the log file will rotate.

7. To include a time or date stamp in the file name when the log file is rotated, in the File Name field, add `java.text.SimpleDateFormat` variables to the file name. Surround each variable with percentage (`%`) characters.

   For example, if you enter the following value in the File Name field:
   `myserver_%yyyy%_%MM%_%dd%_%hh%_%mm%.log`

   the server's log file will be named:
   `myserver_yyyy_MM_dd_hh_mm.log`

   When the server instance rotates the log file, the rotated file name contains the date stamp. For example, if the server instance rotates its local log file on 2 April, 2003 at 10:05 AM, the log file that contains the old log messages will be named:
   `myserver_2003_04_02_10_05.log`

   If you do not include a time and date stamp, the rotated log files are numbered in order of creation `filename` `nnnnn`, where `filename` is the name configured for the log file. For example: `myserver.log00007`.

By default, the local server log file is called `servername``.log` (where `servername` is the name of the server) and is created in the directory where you started the WebLogic Server. You can set the file name also on the Configuration—>Logging page for the server.

You can specify the maximum number of rotated files that can accumulate by setting an appropriate value for the `File Count` field. Once the number of log files reaches this number, the oldest log file is deleted each time a log file rotation occurs.

The local server log always has all the messages that have been logged.

Configuring logging by the local server also includes the ability to specify which messages are logged to `stdout`. You can exclude messages of lower severity by specifying the lowest severity to be logged. You can also enable or disable logging of debug messages to `stdout`.

Note: It is recommended that you not modify the server log files by manually editing them. Log rotation by time is based on the timestamp of the files. If you modify the file, this changes the timestamp and log rotation may become confused. If you edit the file manually this may lock the file and prevent updating of the file by the server.

Client Logging

Java clients that use the WebLogic logging facility may also generate log messages. However, messages logged by clients are not forwarded to the domain log. You configure logging properties of a client by entering the appropriate argument on the command line:

>     -Dweblogic.log.attribute=value

where `attribute` is any `LogMBean` attribute.

By default, logging to a log file is turned off for clients and messages are logged to `stdout`. You can turn on logging to a file and set the file name for the log if you include the following argument on the command line:

>     -Dweblogic.log.FileName=logfilename

where `logfilename` is the name that you want to use for the client log file.

The following command line arguments can also be used for client logging:

>     -Dweblogic.StdoutEnabled=boolean

>     -Dweblogic.StdoutDebugEnabled=boolean

>     -Dweblogic.StdoutSeverityLevel = [64 | 32 | 16 | 8 | 4 | 2 | 1 ]

where `boolean` is either `true` or `false` and the numeric values for `StdoutSeverityLevel` correspond to the following severity levels:
`INFO`(`64`) `WARNING`(`32`), `ERROR`(`16`), `NOTICE`(`8`), `CRITICAL`(`4`), `ALERT`(`2`) and `EMERGENCY`(`1`).

Log File Format

The first line of each message in a log file begins with `####` followed by the message header. The message header provides the run-time context of the message. Each attribute of the message is contained between angle brackets.

Lines following the message body are only present for messages logging an exception and display the stack trace for the exception. If a message is not logged within the context of a transaction, the angle brackets (separators) for Transaction ID are present even though no Transaction ID is present.

The following is an example of a log message:

>     ####<Jun 2, 2000 10:23:02 AM PDT> <Info> <SSL> <bigbox> <myServer>
>         <SSLListenThread> <harry> <> <004500> <Using exportable strength SSL>

In this example, the message attributes are: Timestamp, Severity, Subsystem, Machine Name, Server Name, Thread ID, User ID, Transaction ID, Message ID, and Message Text.

Note: Log messages logged by clients do not have the attributes Server Name or Thread ID.

Note: The character encoding used in writing the log files is the default character encoding of the host system.

Message Attributes

Each log message saved in a server log file the attributes listed in the following table may be defined. The Message Id may also associate the message with additional attributes (such as Probable Cause and Recommended Action) contained in the Message Catalog.

Attribute | Description
--- | ---
Timestamp | The time and date when the message originated, in a format that is specific to the locale.
Severity | Indicates the degree of impact or seriousness of the event reported by the message. See Message Severity.
Subsystem | This attribute denotes the particular subsystem of WebLogic Server that was the source of the message. For example, EJB, RMI, JMS.
Server Name Machine Name Thread ID Transaction ID | These four attributes identify the origins of the message. Transaction ID is present only for messages logged within the context of a transaction. Note: Server Name and Thread ID are not present in log messages generated by a Java client and logged to a client log.
User ID | The user from the security context when the message was generated.
Message ID | A unique six-digit identifier. Message IDs through 499999 are reserved for WebLogic Server system messages.
Message Text | For WebLogic Server messages, this contains the Short Description as defined in the system message catalog. (See Message Catalog.) For other messages, this is text defined by the developer of the program.

Message Catalog

In addition to the information contained in a log message, messages generated by WebLogic Server system components (or possibly by user-written code) include additional pre-defined or canned information that is stored in a message catalog. The additional attributes stored in the message catalog are described below.

Attribute | Description
--- | ---
Message Body | This is a short textual description of the condition being reported. This is the same as Message Text in the message.
Message Detail | A more detailed description of the condition that the message is reporting.
Probable Cause | An explanation as to why the message was logged. The probable cause of the condition the message is reporting.
Recommended Action | A recommendation for action by the administrator to resolve or avoid the condition reported in the message.

You can access these additional message attributes from log views in the Administration Console.

Message Severity

WebLogic Server log messages have an attribute called severity which reflects the importance or potential impact on users of the event or condition reported in the message.

Defined severities are described below. Severities are listed in order of severity with `Emergency` being the highest severity.

Severity | Forwarded to Domain Log by Default? | Meaning
--- | --- | ---
Informational | No | Used for reporting normal operations.
Warning | No | A suspicious operation or configuration has occurred but it may not have an impact on normal operation.
Error | Yes | A user error has occurred. The system or application is able to handle the error with no interruption, and limited degradation, of service.
Notice | Yes | A warning message: A suspicious operation or configuration has occurred which may not affect the normal operation of the server.
Critical | Yes | A system or service error has occurred. The system is able to recover but there might be a momentary loss, or permanent degradation, of service.
Alert | Yes | A particular service is in an unusable state while other parts of the system continue to function. Automatic recovery is not possible; the immediate attention of the administrator is needed to resolve the problem.
Emergency | Yes | The server is in an unusable state. This severity indicates a severe system failure or panic.

Debug Messages

Messages with a severity of `debug` are a special case. Debug messages are not forwarded to the domain log. Debug messages may contain detailed information about an application or the server. These messages should only occur when the application is running in debug mode.

Browsing Log Files

The log browsing capabilities of the Administration Console allow you to do the following:

- View the local log file of any server.

- View the domain-wide log file.

When viewing either the domain log or the local server log, you can:

- Select log messages to be viewed based on the time of occurrence, user ID, subsystem, message severity, or the message short description.

- View messages as they are logged, or search for past log messages.

- Select the log message attributes to be displayed in the Administration Console and the order in which the attributes are displayed.

Viewing the Logs

You can access both the domain log and the local server log files from the Administration Console. How to do these tasks is discussed in the Console Online Help:

- Viewing the Domain Log

- Viewing the Local Server Log

Creating Domain Log Filters

The log messages forwarded by WebLogic Servers to the domain log are, by default, a subset of messages logged locally. You can configure a log filter that selects log messages for forwarding based on message severity, subsystem, or user ID. (Debug messages are a special case and are not forwarded to the domain log.) You can create or modify domain log filters from the domain log filters table. The domain log filters table is accessible from the domain monitoring tab page. See the Administration Console online help for more information on creating domain log filers.

Copyright © 2001 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.