Understanding WebLogic Logging Services

What You Can Do With WebLogic Logging Services

WebLogic Server subsystems use logging services to provide information about events such as the deployment of new applications or the failure of one or more subsystems. A server instance uses them to communicate its status and respond to specific events. For example, you can use WebLogic logging services to report error conditions or listen for log messages from a specific subsystem.

Each WebLogic Server instance maintains a server log. Because each WebLogic Server domain can run concurrent, multiple instances of WebLogic Server, the logging services collect messages that are generated on multiple server instances into a single, domain-wide message log. The domain log provides the overall status of the domain. See Server Log Files and Domain Log Files.

How WebLogic Logging Services Work

Learn about the WebLogic Server logging environment and the logging process.

Components and Environment

There are two basic components in any logging system: a component that produces log messages and another component to distribute (publish) messages. WebLogic Server subsystems use a message catalog feature to produce messages and the Java Logging APIs to distribute them, by default. Developers can also use message catalogs for applications they develop.

The message catalog framework provides a set of utilities and APIs that your application can use to send its own set of messages to the WebLogic server log. The framework is ideal for applications that need to localize the language in their log messages, but even for those applications that do not need to localize, it provides a rich, flexible set of tools for communicating status and output.

See Using Message Catalogs with WebLogic Server in Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.

In addition to using the message catalog framework, your application can use the following mechanisms to send messages to the WebLogic server log:

weblogic.logging.NonCatalogLogger APIs

With NonCatalogLogger, instead of calling messages from a catalog, you place the message text directly in your application code. See Using the NonCatalogLogger APIs in Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.
Server Logging Bridge

WebLogic Server provides a mechanism by which your logging application can have its messages redirected to WebLogic logging services without the need to make code changes or implement any of the propriety WebLogic Logging APIs. See Server Logging Bridge.

Use of either the NonCatalogLogger APIs or Server Logging Bridge is suitable for logging messages that do not need to be internationalized or that are internationalized outside the WebLogic I18n framework.

To distribute messages, WebLogic Server supports Java based logging by default. The LoggingHelper class provides access to the java.util.logging.Logger object used for server logging. This lets developers take advantage of the Java Logging APIs to add custom handlers, filters, and formatters. See the java.util.logging API documentation at http://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html.

Alternatively, you can configure WebLogic Server to use the Jakarta Project Log4j APIs to distribute log messages. See Log4j and the Commons Logging API.

Terminology

To understand the WebLogic Logging services, you must understand the following terminology associated with it:

Logger - A Logger object logs messages for a specific subsystem or application component. WebLogic logging services use a single instance of java.util.logging.Logger for logging messages from the Message Catalogs, NonCatalogLogger, and the Debugging system.
Handler - A class that extends java.util.logging.Handler and receives log requests sent to a logger. Each Logger instance can be associated with a number of handlers to which it dispatches log messages. A handler attaches to a specific type of a log message; for example, the File Handler for the server log file.
Appender - An appender is Log4j terminology for a handler, in this case, an instance of a class that implements org.apache.log4j.Appender and is registered with an org.apache.log4j.Logger to receive log events.

Overview of the Logging Process

WebLogic Server subsystems or application code send log requests to Logger objects. These Logger objects allocate LogRecord objects which are passed to Handler objects for publication. Both loggers and handlers use severity levels and (optionally) filters to determine if they are interested in a particular LogRecord object. When it is necessary to publish a LogRecord object externally, a handler can (optionally) use a formatter to localize and format the log message before publishing it to an I/O stream.

Figure 1-1 shows the WebLogic Server logging process: WebLogic Catalog APIs or Commons Logging APIs are used for producing messages; Java Logging (default) and Log4j are options for distributing messages.

Figure 1-1 WebLogic Server Logging Process

Description of "Figure 1-1 WebLogic Server Logging Process"

Figure 1-1 illustrates the following process:

The client, in this case, a WebLogic Server subsystem or Java EE application, invokes a method on one of the generated Catalog Loggers or the Commons Logging implementation for WebLogic Server.
1. When WebLogic Server message catalogs and the NonCatalogLogger generate messages, they distribute their messages to the server Logger object.
2. The Jakarta Commons Logging APIs define a factory API to get a Logger reference which dispatches log requests to the server Logger object.
  
  The server Logger object can be an instance of java.util.logging.Logger or org.apache.log4j.Logger.
The server Logger object publishes the messages to any message handler that has subscribed to the Logger.

For example, the Stdout Handler prints a formatted message to standard out and the File Handler writes formatted output to the server log file. The Domain Log Broadcaster sends log messages to the domain log, which resides on the Administration Server, and the JMX Log Broadcaster sends log messages to JMX listeners on remote clients.

Server Log Files and Domain Log Files

Each WebLogic Server instance writes all messages from its subsystems and applications to a server log file that is located on the local host computer. By default, the server log file is located in the logs directory below the server instance root directory; for example, DOMAIN_NAME\servers\SERVER_NAME\logs\SERVER_NAME.log, where DOMAIN_NAME is the name of the directory in which you located the domain and SERVER_NAME is the name of the server.

In addition to writing messages to the server log file, each server instance forwards a subset of its messages to a domain-wide log file. By default, servers forward only messages of severity level Notice or higher. While you can modify the set of messages that are forwarded, servers can never forward messages of the Debug severity level. See Forward messages to the domain log in Oracle WebLogic Server Administration Console Online Help.

The domain log file provides a central location from which to view the overall status of the domain. The domain log resides in the Administration Server logs directory. The default name and location for the domain log file is DOMAIN_NAME\servers\ADMIN_SERVER_NAME\logs\DOMAIN_NAME.log, where DOMAIN_NAME is the name of the directory in which you located the domain and ADMIN_SERVER_NAME is the name of the Administration Server. See Change domain log file name and location in Oracle WebLogic Server Administration Console Online Help.

The timestamp for a record in the domain log is the timestamp of the server where the message originated. Log records in the domain log are not written in the order of their timestamps; the messages are written as soon as they arrive. It may happen that a Managed Server remains out of contact with the Administration Server for some period of time. In that case, the messages are buffered locally and sent to the Administration Server once the servers are reconnected.

How a Server Instance Forwards Messages to the Domain Log

To forward messages to the domain log, each server instance broadcasts its log messages. A server broadcasts all messages and message text except for messages of the Debug severity level.

The Administration Server listens for a subset of these messages and writes them to the domain log file. To listen for these messages, the Administration Server registers a listener with each Managed Server. By default, the listener includes a filter that allows only messages of severity level Notice and higher to be forwarded to the Administration Server. (See Figure 1-2.)

Figure 1-2 WebLogic Server and Domain Logs

Description of "Figure 1-2 WebLogic Server and Domain Logs"

For any given WebLogic Server instance, you can override the default filter and create a log filter that causes a different set of messages to be written to the domain log file. For information about setting up a log filter for a WebLogic Server instance, see Create log filters in Oracle WebLogic Server Administration Console Online Help.

If the Administration Server is unavailable, Managed Servers continue to write messages to their local server log files. However, by default, when the servers are reconnected, not all the messages written during the disconnected period are forwarded to the domain log file. A Managed Server keeps a specified number of messages in a buffer so they can be forwarded to the Administration Server when the servers are reconnected.

The number of messages kept in the buffer is configured by the LogMBean attribute DomainLogBroadcasterBufferSize. DomainLogBroadcasterBufferSize controls the frequency with which log messages are sent from the Managed Server to the domain server. With the development default of 1, there is not batching of log messages; only the last logged message is forwarded to the Administration Server domain log. 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. See MSI Mode and the Domain Log File in Administering Server Startup and Shutdown for Oracle WebLogic Server. In production mode, the default buffer size on the Managed Server is 10. When the buffer reaches its capacity, the messages in the buffer are flushed by sending them to the domain log on the Administration Server. For performance reasons, it is recommended that you set this value to 10 or higher in production. A higher value will cause the buffer to be broadcast to the domain log less frequently.

If you have configured a value greater than 1, that number of messages will be forwarded to the domain log when the Managed Server is reconnected to the Administration Server.

Note:

This can result in a domain log file that lists messages with earlier timestamps after messages with later timestamps. When messages from the buffer of a previously disconnected Managed Server are flushed to the Administration Server, those messages are simply appended to the domain log, even though they were generated before the previous messages in the domain log.

Server and Subsystem Logs

Each subsystem within WebLogic Server generates log messages to communicate its status.

For example, when you start a WebLogic Server instance, the Security subsystem writes a message to report its initialization status. To keep a record of the messages that its subsystems generate, WebLogic Server writes the messages to log files.

Server Log

The server log records information about events such as the startup and shutdown of servers, the deployment of new applications, or the failure of one or more subsystems. The messages include information about the time and date of the event as well as the ID of the user who initiated the event.

You can view and sort these server log messages to detect problems, track down the source of a fault, and track system performance. You can also create client applications that listen for these messages and respond automatically. For example, you can create an application that listens for messages indicating a failed subsystem and sends E-mail to a system administrator.

The server log file is located on the computer that hosts the server instance. Each server instance has its own server log file. By default, the server log file is located in the logs directory below the server instance root directory; for example, DOMAIN_NAME\servers\SERVER_NAME\logs\SERVER_NAME.log, where DOMAIN_NAME is the name of the directory in which you located the domain and SERVER_NAME is the name of the server. See Change server log file name and location in Oracle WebLogic Server Administration Console Online Help.

To view messages in the server log file, you can log on to the WebLogic Server host computer and use a standard text editor, or you can log on to any computer and use the log file viewer in the WebLogic Server Administration Console. See View server logs in Oracle WebLogic Server Administration Console Online Help.

Note:

Oracle recommends that you do not modify log files by editing them manually. Modifying a file changes the timestamp and can confuse log file rotation. In addition, editing a file might lock it and prevent updates from WebLogic Server, as well as interfere with the Accessor.

For information about the Diagnostic Accessor Service, see Accessing Diagnostic Data With the Data Accessor in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.

In addition to writing messages to a log file, each server instance prints a subset of its messages to standard out. Usually, standard out is the shell (command prompt) in which you are running the server instance. However, some operating systems enable you to redirect standard out to some other location. By default, a server instance prints only messages of a Notice severity level or higher to standard out. (A subsequent section, Message Severity describes severity levels.) You can modify the severity threshold so that the server prints more or fewer messages to standard out.

If you use Node Manager to start a Managed Server, the messages that would otherwise be output to stdout or stderr when starting a Managed Server are instead displayed in the WebLogic Server Administration Console and written to a single log file for that server instance, SERVER_NAME.out. The server instance's output log is located in the same logs directory, below the server instance root directory, along with the WebLogic Server SERVER_NAME.log file; for example, DOMAIN_NAME\servers\SERVER_NAME\logs\SERVER_NAME.out, where DOMAIN_NAME is the name of the directory in which you located the domain and SERVER_NAME is the name of the server.

Node Manager writes its own startup and status messages to a single log file, NM_HOME/nodemanager.log, where NM_HOME designates the Node Manager root directory, by default, DOMAIN_HOME/nodemanager. See Node Manager Configuration and Log Files in Administering Node Manager for Oracle WebLogic Server.

Subsystem Logs

The server log messages and log file communicate events and conditions that affect the operation of the server or the application. Some subsystems maintain additional log files to provide an audit of the subsystem's interactions under normal operating conditions. The following list describes each of the additional log files:

The HTTP subsystem keeps a log of all HTTP transactions in a text file. The default location and rotation policy for HTTP access logs is the same as the server log. You can set the attributes that define the behavior of HTTP access logs for each server or for each virtual host that you define. See Setting Up HTTP Access Logs in Administering Server Environments for Oracle WebLogic Server and Enable and configure HTTP logs in Oracle WebLogic Server Administration Console Online Help.
Each server has a transaction log which stores information about committed transactions coordinated by the server that may not have been completed. WebLogic Server uses the transaction log when recovering from system crashes or network failures. You cannot directly view the transaction log - the file is in a binary format.

The Transaction Manager uses the default persistent store to store transaction log files. Using the WebLogic Server Administration Console, you can change where the default store is located. See Configure the default persistent store for Transaction Recovery Service migration in Oracle WebLogic Server Administration Console Online Help.
The WebLogic Auditing provider records information from a number of security requests, which are determined internally by the WebLogic Security Framework. The WebLogic Auditing provider also records the event data associated with these security requests, and the outcome of the requests. Configuring an Auditing provider is optional. The default security realm (myrealm) does not have an Auditing provider configured. See Configuring the WebLogic Auditing Provider in Administering Security for Oracle WebLogic Server.

All auditing information recorded by the WebLogic Auditing provider is saved in WL_HOME\DOMAIN_NAME\servers\SERVER_NAME\logs\DefaultAuditRecorder.log. Although an Auditing provider is configured per security realm, each server writes auditing data to its own log file in the server directory.
The JDBC subsystem records various events related to JDBC connections, including registering JDBC drivers and SQL exceptions. The events related to JDBC are now written to the server log, such as when connections are created or refreshed or when configuration changes are made to JDBC objects. See Monitoring WebLogic JDBC Resources in Administering JDBC Data Sources for Oracle WebLogic Server.
JMS logging is enabled by default when you create a JMS server, however, you must specifically enable it on message destinations in the JMS modules targeted to this JMS server (or on the JMS template used by destinations).

JMS server log files contain information on basic message life cycle events, such as message production, consumption, and removal. When a JMS destination hosting the subject message is configured with message logging enabled, then each of the basic message life cycle events will generate a message log event in the JMS message log file.

The message log is located in the logs directory, below the server instance root directory, DOMAIN_NAME\servers\SERVER_NAME\logs\jmsServers\SERVER_NAMEJMSServer\jms.messages.log, where DOMAIN_NAME is the name of the directory in which you located the domain and SERVER_NAME is the name of the server.

After you create a JMS server, you can change the default name of its log file, as well as configure criteria for moving (rotating) old log messages to a separate file. See Configure topic message logging in Oracle WebLogic Server Administration Console Online Help and Monitoring JMS Statistics and Managing Messages in Administering JMS Resources for Oracle WebLogic Server.

Log Message Format

When a WebLogic Server instance writes a message to the server log file, the first line of each message begins with #### followed by the message attributes. Each attribute is contained between angle brackets.

Here is an example of a message in the server log file:

####<Sept 22, 2004 10:46:51 AM EST> <Notice> <WebLogicServer> <MyComputer>
<examplesServer><main> <<WLS Kernel>> <> <null> <1080575211904> <BEA-000360> <Server started in RUNNING mode>

In this example, the message attributes are: Locale-formatted Timestamp, Severity, Subsystem, Machine Name, Server Name, Thread ID, User ID, Transaction ID, Diagnostic Context ID, Raw Time Value, Message ID, and Message Text. (A subsequent section, Message Attributes describes each attribute.)

If a message is not logged within the context of a transaction, the angle brackets for Transaction ID are present even though no Transaction ID is present.

If the message includes a stack trace, the stack trace is included in the message text.

WebLogic Server uses the host computer's default character encoding for the messages it writes.

Log File Format Compatibility with Previous WebLogic Server Versions

To configure the logging service to revert to the legacy log format used in earlier versions of WebLogic Server, set the DomainMBean.LogFormatCompatibilityEnabled attribute to true. In WebLogic Server 12.2.1 and later, the default value of this attribute is false.

Format of Output to Standard Out and Standard Error

When a WebLogic Server instance writes a message to standard out, the output does not include the #### prefix and does not include the Server Name, Machine Name, Thread ID, User ID, Transaction ID, Diagnostic Context ID, and Raw Time Value fields.

Here is an example of how the message from the previous section would be printed to standard out:

<Sept 22, 2004 10:51:10 AM EST> <Notice> <WebLogicServer> <BEA-000360> <Server started in RUNNING mode>

In this example, the message attributes are: Locale-formatted Timestamp, Severity, Subsystem, Message ID, and Message Text.

Message Attributes

The messages for all WebLogic Server instances contain a consistent set of attributes. Table 1-1 lists the server log message attributes. In addition, if your application uses WebLogic logging services to generate messages, its messages also contain these attributes.

Table 1-1 Server Log Message Attributes

Attribute	Description
Locale-formatted Timestamp	Time and date when the message originated, in a format that is specific to the locale. The Java Virtual Machine (JVM) that runs each WebLogic Server instance refers to the host computer operating system for information about the local time zone and format.
Severity	Indicates the degree of impact or seriousness of the event reported by the message. See Message Severity.
Subsystem	Indicates the subsystem of WebLogic Server that was the source of the message; for example, Enterprise Java Bean (EJB) container or Java Messaging Service (JMS).
Machine Name Server Name Thread ID	Identifies the origins of the message: `Server Name` is the name of the WebLogic Server instance on which the message was generated. `Machine Name` is the DNS name of the computer that hosts the server instance. `Thread ID` is the ID that the JVM assigns to the thread in which the message originated. Log messages that are generated within a client JVM do not include these attributes. For example, if your application runs in a client JVM and it uses the WebLogic logging services, the messages that it generates and sends to the WebLogic client log files will not include these attributes.
User ID	The user ID under which the associated event was executed. To execute some pieces of internal code, WebLogic Server authenticates the ID of the user who initiates the execution and then runs the code under a special Kernel Identity user ID. Java EE modules such as EJBs that are deployed onto a server instance report the user ID that the module passes to the server. Log messages that are generated within a client JVM do not include this field.
Transaction ID	Present only for messages logged within the context of a transaction.
Diagnostic Context ID	Context information to correlate messages coming from a specific request or application.
Raw Time Value	The timestamp in milliseconds.
Message ID	A unique six-digit identifier. All message IDs that WebLogic Server system messages generate start with `BEA-` and fall within a numerical range of 0-499999. Your applications can use a Java class called `NonCatalogLogger` to generate log messages instead of using an internationalized message catalog. The message ID for `NonCatalogLogger` messages is always `000000`. See Writing Messages to the WebLogic Server Log in Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.
Message Text	A description of the event or condition.

Message Severity

The severity attribute of a WebLogic Server log message indicates the potential impact of the event or condition that the message reports.Table 1-2 lists the severity levels of log messages from WebLogic Server subsystems, starting from the lowest level of impact to the highest.

Table 1-2 Message Severity

Severity	Meaning
`Trace`	Used for messages from the Diagnostic Action Library. Upon enabling diagnostic instrumentation of server and application classes, `Trace` messages follow the request path of a method. See Diagnostic Action Library in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.
`Debug`	A debug message was generated.
`Info`	Used for reporting normal operations; a low-level informational message.
`Notice`	An informational message with a higher level of importance.
`Warning`	A suspicious operation or configuration has occurred but it might not affect normal operation.
`Error`	A user error has occurred. The system or application can handle the error with no interruption and limited degradation of service.
`Critical`	A system or service error has occurred. The system can recover but there might be a momentary loss or permanent degradation of service.
`Alert`	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`	The server is in an unusable state. This severity indicates a severe system failure or panic.

WebLogic Server subsystems generate many messages of lower severity and fewer messages of higher severity. For example, under normal circumstances, they generate many Info messages and no Emergency messages.

If your application uses WebLogic logging services, it can use an additional severity level, Debug. See Writing Debug Messages in Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.

Viewing WebLogic Server Logs

The WebLogic Server Administration Console provides a log viewer for all the log files in a domain.

The log viewer can find and display the messages based on any of the following message attributes: date, subsystem, severity, machine, server, thread, user ID, transaction ID, context ID, timestamp, message ID, or message. It can also display messages as they are logged or search for past log messages.

For information about viewing, configuring, and searching message logs, see the following topics in Oracle WebLogic Server Administration Console Online Help:

For a detailed description of log messages in WebLogic Server message catalogs, see Error Messages. This index of messages describes all of the messages emitted by WebLogic subsystems and provides a detailed description of the error, a possible cause, and a recommended action to avoid or fix the error. To view available details, click on the appropriate entry in the Range column (if viewing by range) or the Subsystem column (if viewing by subsystem).

Server Logging Bridge

The Server Logging Bridge is attached to the root logger of the logger tree by default with the Java API or Log4j Logging implementation.If WebLogic Server is using the default java.util.logging implementation and the application is using Log4j APIs, then to redirect the application log messages to the server log do the configuration and set up as follows:

Add the following lines to the log4j.properties file:

log4j.rootLogger=server
log4j.appender.server=weblogic.logging.log4j.ServerLoggingAppender

Obtain a copy of the log4j.jar file. WebLogic Server does not provide a Log4j version in its distribution, but you can download one from Apache at the following location:

http://logging.apache.org/log4j/
Copy the log4j.jar file and the WL_HOME/server/lib/wllog4j.jar file to the server classpath, which you can do simply by copying both files into the DOMAIN_NAME/lib directory. There, they will be added to the server classpath dynamically during server startup.

If you place these .jar files elsewhere, make sure that both are placed in the same directory and that you update the server classpath to include this directory

If WebLogic Server is configured to use the Log4j API as its logging implementation and the application is using java.util.logging, then configure the logging.properties to redirect the messages from java.util.logging to the server log as follows:

Specify the handlers to create in the root logger:

handlers = weblogic.logging.ServerLoggingHandler
Set the default logging level for new FileHandler instances

weblogic.logging.ServerLoggingHandler.level = ALL

Note:

See Server Logging Bridge in Upgrading Oracle WebLogic Server for important instructions about configuration changes that may be necessary when upgrading a WebLogic domain in which the Server Logging Bridge is configured.

Configuring java.util.logging Logger Levels

WebLogic Server supports configuring java.util.logging.Logger levels for named loggers in the JDK LogManager from within the WebLogic Server logging configuration.

You can configure java.util.logging levels for named loggers using the PlatformLoggerLevels attribute in the LogMBean. This configuration applies to java.util.logging.Logger instances in the JDK's default global LogManager.

Note:

This configuration is persisted as part of the WebLogic logging configuration and is not included in the logging.properties file.

If your WebLogic domain includes Oracle JRF and is configured to use Oracle Diagnostic Logging (ODL), the java.util.logging levels set on the LogMBean.PlatformLoggerLevels attribute are ignored. For more information about ODL logging, see Managing Log Files and Diagnostic Data in Administering Oracle Fusion Middleware.

To configure WebLogic Server loggers, use the LoggerSeverities attribute on the LogMBean. See Table 1-2. These loggers are not available in the JDK's default global LogManager.

For information about how to configure the java.util.logging logger levels using the WebLogic Server Administration Console, see Configure java.util.logging logger levels in Oracle WebLogic Server Administration Console Online Help.

Configuring java.util.logging Logger Levels Using WLST

The following example demonstrates using WLST to configure java.util.logging logger levels:

wls:/mydomain/serverConfig> edit()
wls:/mydomain/edit> startEdit()
wls:/mydomain/edit !> cd ('/Servers/myserver/Log/myserver')
wls:/mydomain/edit/Servers/myserver/Log/myserver !> props = java.util.Properties()
wls:/mydomain/edit/Servers/myserver/Log/myserver !> props.put("foo.bar","INFO")
wls:/mydomain/edit/Servers/myserver/Log/myserver !> 
wls:/mydomain/edit/Servers/myserver/Log/myserver !> cmo.setPlatformLoggerLevels(props)
wls:/mydomain/edit/Servers/myserver/Log/myserver !> save()
Saving all your changes ...
Saved all your changes successfully.
wls:/mydomain/edit/Servers/myserver/Log/myserver !> activate()
Activating all your changes, this may take a while ... 
The edit lock associated with this edit session is released once the activation is completed.
Activation completed

Best Practices

Learn the recommendations for using WebLogic logging services with Java Logging or Log4j.

If you are using Log4j for application logging, the log4j.properties file can use the generic overrides feature in WebLogic Server to have this file inserted into your existing deployment plan directory structure. The generic overrides feature provides a convenient means to insert, or make changes to, specific resource types used by an application and to continue using the existing ClassLoader and resource loading rules and behaviors for the application, without having to revise the application JAR files.

See Generic File Loading Overrides in Deploying Applications to Oracle WebLogic Server.