# workshopLogCfg.xml Configuration File

The workshopLogCfg.xml file specifies the WebLogic Workshop logging configuration and logging levels for WebLogic Server. You may use this logging facility in your applications. You may also be directed by BEA Technical Support personnel to modify WebLogic Workshop's logging behavior in order to diagnose problems you experience. This topic describes the basic features of WebLogic Workshop's logging mechanism.

- log4j Library
- WebLogic Workshop Logging
- Understanding the Contents of workshopLogCfg.xml
- Adding Log4j Log Messages to Your Application Code
- Tracking Log Information in a Clustered Environment

## log4j Library

WebLogic Workshop uses the Log4j Java logging facility developed by the Jakarta Project of the Apache Foundation. The names of the XML tags in workshopLogCfg.xml directly correspond to names of classes and fields defined in the Log4j API Specification. You can learn more about Log4j at The Log4j Project. A brief introduction to Log4j is included below.

### Loggers

Log4j defines the Logger class. An application may 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. The name of the logger is typically the same as the partially qualified name of the application class. For example, the application class com.mycompany.MyClass might create a Logger with the name "mycompany.MyClass". Loggers exist in a namespace hierarchy and inherit behavior from their ancestors in the hierarchy.

The Logger class defines four methods for emitting log messages: debug, info, warn and error. The application class invokes the appropriate method (on its local Logger) for the situation being reported.

### Appenders

Log4j defines Appenders to represent destinations for logging output. Multiple Appenders may be defined. For example, an application may define an Appender that sends log messages to the console, and another Appender that writes log messages to a file. Individual Loggers may 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 the console.

### Layouts

Log4J defines Layouts to control the format of log messages. Each Layout specifies a particular message format in which may be substituted the data such as the current time and date, the log level, the Logger name, the log message and other information. A specific Layout is associated with each Appender. This allows you to specify a different log message format for console output than for file output, for example.

### Configuration

All aspects of Log4j configuration at runtime. This is typically accomplished with an XML configuration file whose format is defines by the Log4j library. The configuration file may be specified at runtime using the log4j.configuration Java property.

The configuration file may declare Loggers, Appenders and Layouts and configure combinations of them to provide the logging style desired by the application.

## WebLogic Workshop Logging

By default, WebLogic Workshop's logging configuration is defined in the file <BEA_HOME>/<WEBLOGIC_HOME>/common/lib/workshopLogCfg.xml. The workshopLogCfg.xml file contains XML tags that describe how the WebLogic Workshop environment logs various types of messages. The names of these tags directly correspond to names of classes and fields defined in the log4j API Specification.

If you want to customize the way WebLogic Workshop logs messages, you can either modify workshopLogCfg.xml, or provide your own Log4j configuration file. If you provide your own version, you need to set the log4j.configuration Java property to the location of this file. For example, using the same command line that you used to start WebLogic Server, type -Dlog4j.configuration=<path to config file>.

It is helpful to understand the contents of the workshopLogCfg.xml. Once you understand the elements and attributes defined in this file, you can either use this knowledge to customize workshopLogCfg.xml, or write a separate Log4j configuration file that better suits your logging requirements.

## Understanding the Contents of workshopLogCfg.xml

The workshopLogCfg.xml file contains two major sets of configuration values. The first set of configurations use the <appender> element to define log files that receive messages from the WebLogic Workshop environment. Note that this element shares the same name as the Appender class defined in the Log4j API Specification. The following snippet illustrates an entry in this section of the configuration file:

      <appender name="SYSLOGFILE" class="org.apache.log4j.RollingFileAppender">
        <param name="File"   value="workshop_debug.log" />
        <param name="Append" value="true" />
        <param name="MaxFileSize" value="500000KB" />
        <layout class="org.apache.log4j.PatternLayout">
          <param name="ConversionPattern" value="%d{DATE} %-5p %-15c{1} [%t][%x]: %m%n"/>
        </layout>
      </appender>

This entry causes WebLogic Workshop to create a Log4j Appender object of type RollingFileAppender. RollingFileAppender is a special kind of Log4j Appender class that backs up log files when they reach a certain size. The Log4j specification defines several different types of Appender classes. You can use the class attribute of the <appender> element to use any of these types. For instance, if you would like WebLogic Workshop to send certain types of messages to the console, then you can set the class attribute of an <appender> element to org.apache.log4j.ConsoleAppender. The name attribute of the <appender> element assigns a variable name to the Appender object. workshopLogCfg.xml uses that name later in the configuration file to assign specific messages to that Appender.

The <param> elements use name-value pairs to assign values to various fields of the Appender object. The File value defines the name of the physical file to which message sources log their messages. To learn more about the default log files to which WebLogic Workshop writes log messages, see Message Logging. The Append value indicates that WebLogic Workshop should append any new log messages to the end of the log file. The MaxFileSize value specifies the file size limit of this log file.

Finally the class attribute of the layout element defines a Log4j Layout class. Layout classes define the format of log messages. The ConversionPattern value further defines these formats. For more information on providing conversion patterns, see the log4j API Specification.

The second set of configurations use the <category> element to define message sources. It also relates these sources to log files defined in the <append> elements of the workshopLogCfg.xml. The following snippet illustrates an entry in this portion of the configuration file:

    <category name="weblogic.servlet.jsp">
        <priority value="warn" />
        <appender-ref ref="SYSLOGFILE" />
        <appender-ref ref="SYSERRORLOGFILE" />
      </category>

Note that the ref attribute of the <appender-ref> element refers to the names of Appender objects defined in the first half of workshopLogCfg.xml. The priority value defines the lowest priority message type that WebLogic Workshop will send to these Appender objects. In this case, weblogic.servlet.jsp reports all messages of type warn or higher. This means that weblogic.servlet.jsp will also log messages of type error since messages of type error have a higher priority than messages of type warn. Info, warn, and error are all Log4j message types. For more information, see the log4j Specification.

The name attribute of the <category> element defines the message source. In this case, WebLogic Workshop sends all warning messages originating from a JSP file to both the SYSLOGFILE and SYSERRORLOGFILE Appender objects.

The workshopLogCfg.xml file also defines three category elements that are useful when debugging the request-response chain associated with a JWS (WebLogic Workshop web service) invocation. The categories are defined in the configuration file as shown here:

      <category name="WLW.REQUEST">
          <priority value="info"/>
          <appender-ref ref="APPLOGFILE"/>
      </category>

      <category name="WLW.RESPONSE">
          <priority value="info"/>
          <appender-ref ref="APPLOGFILE"/>
      </category>

      <category name="WLW.INVOKE">
          <priority value="warn"/>
          <appender-ref ref="APPLOGFILE"/>
      </category>

You may adjust the priority levels of these categories to enable or disable logging for the entire call stack that is involved in web service method invocation.

## Adding log4J Log Messages To Your Application Code

To cause your code to emit messages to the workshop.log file, obtain a Logger for your file. You may obtain a Logger by calling the JwsContext.getLogger method, typically with the qualified name of your class as the Logger name (e.g. "async.HelloWorldAsync" for the sample web service async/HelloWorldAsync.jws). Then simply call the Logger's debug, info, warn or error methods as appropriate.

The default logging level is info. This means log messages emitted by Logger.debug() will not be logged by default. To enable logging of all message levels, set the log level for the "wlw" category to debug in workshopLogCfg.xml, as shown here:

      <!-- The wlw category is used for messages logged using the Logger API from JwsContext and ControlContext -->
      <category name="wlw">
        <priority value="debug" />
        <appender-ref ref="APPLOGFILE" />
      </category>

The example code below illustrates use of logging in a JWS file. Portions of the source file have been omitted for brevity.

    package async;
    import com.bea.control.JwsContext;
    import com.bea.control.TimerControl;
    import com.bea.wlw.util.Logger;

    public class HelloWorldAsync
    {
        /** @common:context */
        JwsContext context;
        /**
         * @common:operation
         * @jws:conversation phase="start"
         */
        public void HelloAsync()
        {
            Logger logger = context.getLogger("async.HelloWorldAsync");
            logger.debug("about to start timer");
            // all we do here is start the timer.
            helloDelay.start();
            logger.debug("timer started");
            return;
        }
        private void helloDelay_onTimeout(long time)
        {
            Logger logger = context.getLogger("async.HelloWorldAsync");
            // send the client a hello message.
            logger.debug("in timer handler: calling client");
            callback.onHelloResult("Hello, asynchronous world");

            // we don't want any more timer events for this conversation.
            logger.debug("in timer handler: stopping timer");
            helloDelay.stop();

            return;
        }
    }

The code above results in the following content in workshop.log when the HelloAsync method of HelloWorldAsync.jws is invoked. Log entries not emitted by the preceding code have been removed from the output below.

    13 Jun 2003 14:49:23,796 DEBUG HelloWorldAsync: about to start timer
    13 Jun 2003 14:49:24,171 DEBUG HelloWorldAsync: timer started
    13 Jun 2003 14:49:33,921 DEBUG HelloWorldAsync: in timer handler: calling client
    13 Jun 2003 14:49:33,937 DEBUG HelloWorldAsync: in timer handler: stopping timer

## Tracking Log Information in a Clustered Environment

If you deploy your application to a clustered environment, you may want to track log information for individual servers in the cluster. You can modify the configuration for Appenders in workshopLogCfg.xml to include a variable that returns the name of the server which logged the message. When WebLogic Server starts, it sets an environment variable weblogic.Name with the server name. You can refer to this variable from the log file.

If the number of log messages you expect is fairly low and there are not too many servers in the cluster writing to a single log file all at once, you can modify each Appender so that the server name is written out for each logged message. In this case you should modify the value of the <param> tag named ConversionPattern, which is a child of the <layout> tag, to include the server variable. Here's an example of what the modified Appender would look like:

    <appender name="APPLOGFILE" class="org.apache.log4j.RollingFileAppender">
      <param name="File" value="workshop.log" />
      <param name="Append" value="true" />
      <param name="MaxFileSize" value="3000KB" />
      <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="server:${weblogic.Name} %d{DATE} %-5p %-15c{1}: %m%n"/>
      </layout>
    </appender>

Note that the value of the ConversionPattern parameter includes the variable ${weblogic.Name}. This pattern now writes an entry like the following example to the log file when a message is logged. Note that the name of the server appears as cgServer.

    server:cgServer 05 Jun 2003 10:50:21,194 INFO RMClient: ConversationID=1054835390772; Protocol=java-call;
    URI=/R MClientWeb/TestDriver.jws;Method=onTimeout; Phase=continue;Callback=null

If you are expecting a high volume of log messages, you can modify each Appender so that a separate log file is written for each server. In this case you modify the value of the <param> tag named File to prepend the server name to generate a unique log file for each server, as shown in the following example:

    <appender name="APPLOGFILE" class="org.apache.log4j.RollingFileAppender">
      <param name="File" value="${weblogic.Name}.workshop.log" />
      <param name="Append" value="true" />
      <param name="MaxFileSize" value="3000KB" />
      <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d{DATE} %-5p %-15c{1}: %m%n"/>
      </layout>
    </appender>

Related Topics

Message Logging

Configuration File Reference