The Logging Architecture

WebLogic provides various facilities to create, view, and listen for log messages. Its internal subsystems, such as its web and EJB containers, constantly generate a number of informational, error, and warning log events while a server is running. These log events are visible on the console window for the server, and also may be found in the appropriate log files.

WebLogic manages a distributed log infrastructure. A typical domain is composed of an Administration Server and one or more Managed Servers. The logging infrastructure supports a Logger on each server, which collects the log events generated by your own applications and WebLogic's internal subsystems. These messages then are written to a log file and console that is local to each server instance. In addition, the Logger forwards all but the debug-level messages to a Log Broadcaster. The Log Broadcaster then sends these messages through an optional filter to the Domain Logger on the Administration Server. The Domain Logger gathers all of the messages received from the different servers in the domain and writes these messages to a unified log called the domain log file. This distributed logging infrastructure is depicted in Figure 21-1.

Figure 21-1. The distributed logging architecture

The logging architecture is extensible, letting you create your own set of log messages. You then can instrument your code with the necessary log messages as you see fit. A major advantage of integrating your application logging with WebLogic's logging framework is ease of management. If an application sends log events in this way, its notifications will be treated in the same way as WebLogic's notifications are. This unified handling of your application's log messages will make it easier to manage your application and the WebLogic platform on which it runs. As you shall see later in this chapter, you can write applications that listen for particular log events. The same application can quite easily listen to events generated by WebLogic's internal subsystems or by your own applications.

21.1.1 Under the Hood

Let's examine how WebLogic 8.1 implements its logging infrastructure. The logging in WebLogic 7.0 is similar in structure, though it doesn't rely on the JDK 1.4 API. As a result, it doesn't have the extensible handler system. The logger, sitting on each WebLogic instance, is in fact implemented by a java.util.logging.Logger instance. Each logger instance is equipped with a number of handlers; it is these handlers that provide the ability to stream the messages to a combination of local log files, the console, and the domain log file. The Administration Server has an additional logger that is responsible for the domain log.

WebLogic's ConsoleHandler is responsible for writing the messages to the console, and the FileStreamHandler is responsible for writing the messages to the log files. The JMX MBean LogBroadcasterRuntimeMBean handles message distribution from the Logger in each Managed Server to the Administration Server.

WebLogic provides direct access to the logger on each server. Because these loggers are a part of the JDK 1.4 Logging API, you can easily benefit from other features of the API, such as log filters. In particular, note that loggers and handlers can be assigned a logging level. For a logger, this log level determines the lowest-level message that the logger will publish. For a handler, this log level determines the lowest-level message that the handler will process. Likewise, loggers and handlers can be assigned filters, which determine the subset of messages that will be published by the logger or accepted by the handler.

As the placement of the domain filter in Figure 21-1 suggests, only those log messages that pass through the log level or filter assigned to the logger on the Managed Server will reach the domain filter. So, the logger filter and level settings supersede any domain filter.

21.1.2 Viewing Log Files

You can view all the log files from the Administration Console. Right-click any server name in the left frame and choose View Server Log to view the local log for that server. Right-click the domain name and choose View Domain Log to view the central log for the domain. If you choose the "Customize this View" option, you can determine which subset of messages you wish to see. For instance, you can restrict the view to only those error-level messages that occurred in the past 60 minutes.

The local log files are stored on each server instance in a subdirectory under the domain's root directory named after the server. For instance, the server logs for a Managed Server ServerA, which belongs to the WebLogic domain myclusterdomain, can be found in the myclusterdomain/ServerA/ServerA.log file. This naming scheme avoids any potential conflicts if you have several WebLogic instances that use a shared directory. The domain log file can be found under the domain's root directory in a file called wl-domain.log. This domain log file lives on the machine that hosts the Administration Server.

21.1.3 Anatomy of a Log Message

Each log message emitted by WebLogic adheres to the following pattern:

####      
    

Table 21-1 lists each of these attributes and their meanings.

Table 21-1. Log message attributes and their meanings

Attribute	Meaning
Timestamp	This attribute registers the time and date when the log message was sent.
Severity	This attribute indicates the degree of seriousness of the event.
Subsystem	This attribute indicates which subsystem generated the event. For example, its value could be EJB, JMS, Clustering, or any custom subsystem name that you've chosen for your own events.
Machine Name	This attribute indicates the machine on which the message was generated.
Server Name	This attribute indicates which server instance generated the message.
Thread ID	This attribute determines the ID of the thread that ran the code that generated the message.
User ID	If the log message was generated by a thread with an active security context, this attribute indicates the ID of the user used to create the security context.
Transaction ID	If the message was generated from within a transaction, this attribute represents the transaction ID.
Message ID	This attribute is a unique six-digit message identifier identifying the message template. Messages generated by WebLogic's internal subsystems begin with the string BEA-. Messages generated by noncatalog loggers always have a Message ID of 000000.
Message Text	This attribute generally provides a description of the event.

Each message has a severity level, indicating the degree of seriousness of the message. Table 21-2 provides a list of the different severity levels supported by WebLogic.

Table 21-2. Severity levels and their meanings

Severity	Integer value	Meaning
INFO	64	This indicates that the message represents a general information notification.
WARNING	32	This indicates that something suspicious may have happened, though it will probably not affect normal operation.
ERROR	16	This indicates that an error has occurred, and that the system has handled the error with little interruption of service.
NOTICE	8	This is an INFO or WARNING level message that is useful for monitoring the server.
CRITICAL	4	This indicates that a system or service level error has occurred. The system should be able to recover, but there may be a loss or degradation of service.
ALERT	2	This indicates that a service is in an unusable state and that automatic recovery is not possible.
EMERGENCY	1	This indicates that the server is in an unusable state.

As you'll see later in this chapter, the integer representation for the severity level of log messages is quite useful when you build your own applications that listen for log messages.

21.1.4 Managing the Domain Log

The Administration Console lets you manage all of the log files and related options. To configure logging for the domain, select the domain name from the left frame of the Administration Console and then select the Configuration/Logging tab. Table 21-3 lists the various configuration options available for domain-level logging.

Table 21-3. Configuration options for the domain log file

Attribute	Description	Default
File Name	This specifies the name of the file to which the central domain log entries will be written.	domainName.log
Rotation Type	This can be set to either None, By Size, or By Time. If set to None, the single domain file continues to grow until you delete it. If set to By Time, a new log file is created according to the value of File Time Span. If set to By Size, a new file is created when the log file reaches a specified size.	By Size
Minimum File Size	If the rotation type is set to By Size, the log file is rotated when it reaches this size.	500 kb
Rotation Time and File Time Span	If the rotation type is set to By Time, the log files are rotated at an hourly interval determined by the File Time Span attribute. Such a rotation will begin at the time specified by the Rotation Time attribute.	00:00 and 24 hours
Limit Number of Retained Logs and Log Files to Retain[1]	If you have file rotation configured, choosing to limit the number of files will ensure that no more than the specified number of files is retained.	No limit

[1] In WebLogic 7.0, these options are labeled Limit Number of Files and File Count respectively.

It is important to properly configure your log file rotation so that your files do not consume unnecessary space.

21.1.5 Managing the Local Log

You can find the logging options for a server by selecting the desired server from the left pane of the Administration Console and then navigating to the Logging tab. Table 21-4 describes the various settings that can be configured from the Logging/Server tab.

Table 21-4. General logging options for a server

Attribute	Description	Default
File Name	This specifies the file to which the local log entries will be written.	ServerName/ServerName.log
Log to Stdout	This writes log output to the standard output. It allows you to enable or disable the console handler on the logger.	Selected
Debug to Stdout	This writes messages with DEBUG severity to the standard output.	Selected
Stdout Severity Threshold	This determines the minimum severity of a message that the server sends to standard output.	WARNING[2]
Minimum File Size	If the rotation type is set to Size, the log file is rotated when it reaches this size.	500 kb

[2] The default value in WebLogic 7.0 is ERROR.

The remaining options on this tab configure the log file rotation policy and were explained earlier in Table 21-3. The Stdout Severity Threshold sets up a log filter for the messages that are sent to the standard output stream (by the FileStreamHandler) and does not affect which messages are sent to the domain log.

21.1.6 Creating a Domain Log Filter

As depicted in Figure 21-1, each server can filter the events that are sent to the Domain Logger on the Administration Server. The Logging/Domain tab for a server instance has a Log to Domain Log File option that determines whether log messages generated by a server instance should be forwarded. In addition, you can create and target a Domain Filter to server instances to determine the exact subset of log messages that should be delivered to the domain log.

To create a Domain Filter, click the Domain Log Filters in the left frame of the Administration Console and select the "Configure a new Domain Log Filter" link. The severity level that you set here determines the minimum severity level for messages that will be forwarded to the central log. You also can select which subsystems and user identifiers ought to be filtered. For instance, by choosing the EJB subsystem, only log messages generated in the EJB subsystem will be forwarded to the domain-wide log.

The Targets tab lets you target the domain filter to various server instances. Log messages generated by the loggers on these servers must then pass through this configured domain filter before they can reach the Domain Logger.

21.1.7 WebLogic Message Catalogs

The list of message catalogs that describe all of the messages that can be emitted by the various WebLogic subsystems is available on the Web at the following address: http://edocs.bea.com/wls/docs81/messages/index.html. Use these pages to look up any errors generated by WebLogic. Each entry includes a detailed description of the error, a possible cause, and a recommended action to avoid or fix the error.