Using WebLogic Logging Services for Application Logging

Writing Messages to the WebLogic Server Log

The following sections describe how you can facilitate the management of your application by writing log messages to the WebLogic server log file:

Using the I18N Message Catalog Framework: Main Steps

The internationalization (I18N) 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.

To write log messages using the I18N message catalog framework, complete the following tasks:

Step 1: Create Message Catalogs

A message catalog is an XML file that contains a collection of text messages. Usually, an application uses one message catalog to contain a set of messages in a default language and optionally, additional catalogs to contain messages in other languages.

To create and edit a properly formatted message catalog, use the WebLogic Message Editor utility, which is a graphical user interface (GUI) that is installed with WebLogic Server. To create corresponding messages in local languages, use the Message Localizer, which is also a GUI that WebLogic Server installs.

To access the Message Editor, do the following from a WebLogic Server host:

To access the Message Localizer, do the following from a WebLogic Server host:

Step 2: Compile Message Catalogs

After you create message catalogs, you use the i18ngen and l10ngen command-line utilities to generate properties files and to generate and compile Java class files. The utilities take the message catalog XML files as input and create compiled Java classes. The Java classes contain methods that correspond to the messages in the XML files.

For more information, see Using the WebLogic Server Internationalization Utilities.

To compile the message catalogs, do the following:

For complete documentation of the i18ngen commands, see Using the WebLogic Server Internationalization Utilities .

Example: Compiling Message Catalogs

In this example, the Message Editor created a message catalog that contains one message of type loggable. The Message Editor saves the message catalog as the following file: c:\MyMsgCat\MyMessages.xml.

Listing 5-1 shows the contents of the message catalog.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
"http://www.bea.com/servers/wls90/dtd/msgcat.dtd">

<message_catalog
   i18n_package="com.xyz.msgcat"
   l10n_package="com.xyz.msgcat.l10n"
   subsystem="MyClient"
   version="1.0"
   baseid="700000"
   endid="800000"
   loggables="true"
   prefix="XYZ-"
>
<!--  Welcome message to verify that the class has been invoked-->
   <logmessage
     messageid="700000"
     datelastchanged="1039193709347"
     datehash="-1776477005"
     severity="info"
     method="startup()" 
>
     <messagebody>
         The class has been invoked.
      </messagebody>
      <messagedetail>
         Verifies that the class has been invoked 
         and is generating log messages
      </messagedetail>
      <cause>
         Someone has invoked the class in a remote JVM.
      </cause>
      <action> </action>
   </logmessage>
</message_catalog>

In addition, the Message Localizer creates a Spanish version of the message in MyMessages.xml. The Message Localizer saves the Spanish catalog as c:\MyMsgCat\es\ES\MyMessages.xml.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE locale_message_catalog PUBLIC
"weblogic-locale-message-catalog-dtd"
"http://www.bea.com/servers/wls90/dtd/l10n_msgcat.dtd">

<locale_message_catalog
version="1.0"
>
<!-- Mensaje agradable para verificar que se haya invocado la clase. -->
<logmessage
    messageid="700000"
   datelastchanged="1039546411623"
   >
      <messagebody>
         La clase se haya invocado.
      </messagebody>
      <messagedetail>
         Verifica que se haya invocado la clase y está 
         generando mensajes del registro.
      </messagedetail>
      <cause>Alguien ha invocado la clase en un JVM alejado.</cause>
      <action> </action>
   </logmessage>
</locale_message_catalog>

To compile the message catalog that the Message Editor created, enter the following command:

java weblogic.i18ngen -build -d c:\MessageOutput c:\MyMsgCat\MyMessages.xml

The i18ngen utility creates the following files:

To create properties files for the Spanish catalog, you do the following:

The l10ngen utility creates the following files:

Step 3: Use Messages from Compiled Message Catalogs

The classes and properties files generated by i18ngen and l10ngen provide the interface for sending messages to the WebLogic server log. Within the classes, each log message is represented by a method that your application calls.

To use messages from compiled message catalogs:

Listing 5-3 illustrates a simple class that calls this startup method.

import com.xyz.msgcat.MyMessagesLogger;

public class MyClass { 
     public static void main (String[] args) {
     MyMessagesLogger.startup();
     }
}

If the JVM's system properties specify that the current location is Spain, then the message is printed in Spanish.

Using the NonCatalogLogger APIs

In addition to using the I18N message catalog framework, your application can use the weblogic.logging.NonCatalogLogger APIs to send messages to the WebLogic server log. With NonCatalogLogger, instead of calling messages from a catalog, you place the message text directly in your application code. BEA Systems recommends that you do not use this facility as the sole means for logging messages if your application needs to be internationalized.

NonCatalogLogger is also intended for use by client code that is running in its own JVM (as opposed to running within a WebLogic Server JVM). A subsequent section, Writing Messages from a Client Application, provides more information.

To use NonCatalogLogger in an application that runs within the WebLogic Server JVM, add code to your application that does the following:

All methods that take a Throwable argument can print the stack trace in the server log. For information on the NonCatalogLogger APIs, see the weblogic.logging.NonCatalogLogger Javadoc.

Listing 5-4 illustrates a servlet that uses NonCatalogLogger APIs to write messages of various severity levels to the WebLogic server log.

import java.io.PrintWriter;
import java.io.IOException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.ServletException;
import javax.naming.Context;

import weblogic.jndi.Environment;
import weblogic.logging.NonCatalogLogger;

public class MyServlet extends HttpServlet {

     public void service (HttpServletRequest request,
        HttpServletResponse response)
        throws ServletException, IOException {

       PrintWriter out = response.getWriter();
       NonCatalogLogger myLogger = null;

       try {

          out.println("Testing NonCatalogLogger. See
                         WLS Server log for output message.");

// Constructing a NonCatalogLogger instance. All messages from this
// instance will include a <MyApplication> string.
          myLogger = new NonCatalogLogger("MyApplication");

// Outputting an INFO message to indicate that your application has started.
          mylogger.info("Application started.");

// For the sake of providing an example exception message, the next 
// lines of code purposefully set an initial context. If you run this
// servlet on a server that uses the default port number (7001), the
// servlet will throw an exception.
        Environment env = new Environment();
        env.setProviderUrl("t3://localhost:8000");

        Context ctx = env.getInitialContext();

     }

    catch (Exception e){
      out.println("Can't set initial context: " + e.getMessage());

// Prints a WARNING message that contains the stack trace.
     mylogger.warning("Can't establish connections. ", e);
      }
   }
}

When the servlet illustrated in the previous example runs on a server that specifies a listen port other than 8000, the following messages are printed to the WebLogic server log file. Note that the message consists of a series of strings, or fields, surrounded by angle brackets (< >).

####<May 27, 2004 8:45:42 AM EDT> <Error> <MySubsystem> <myhost> <adminServer> <ExecuteThread: '0' for queue: 'weblogic.kernel.Default (self-tuning)'> <system> <> <> <1085661942864> <OBJ-0011> <Test NonCatalogLogger message
java.lang.Exception: Test NonCatalogLogger message
...
>

Using ServletContext

The servlet specification provides the following APIs in javax.servlet.ServletContext that your servlets and JSPs can use to write a simple message to the WebLogic server log:

For more information on using these APIs, see the J2EE Javadoc for javax.servlet.ServletContext at http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/ServletContext.html.

Listing 5-6 illustrates JSP logging using the ServletContext.

<%@ page language="java" %>
<!DOCTYPE HTML PUBLIC "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
<title>INDEX</title>
</head>
<body bgcolor="#FFFFFF">
<%
config.getServletContext().log("Invoked ServletContext.log() From a JSP");
out.write("Request param arg0 = " + request.getParameter("arg0"));
%>
</body>
</html>

Configuring Servlet and Resource Adapter Logging

In this release of WebLogic Server, you can configure Web application and resource adapter logging behavior using WebLogic specific deployment descriptors. The logging configuration deployment descriptor elements define similar attributes used to configure server logging through the LogMBean interface, such as the log file name, location, and rotation policy.

When configured, application events are directed to a Web application specific log file. When the deployment descriptor does not include any logging configuration information, the default behavior is to write these events in the server log file.

Similarly, WebLogic logging services are provided to J2EE resource adapters for ManagedConnectionFactory scoped logging. You configure the log file name, location, and rotation policy for resource adapter logs through the weblogic-ra.xml deployment descriptor. See " weblogic-ra.xml Schema" in Programming WebLogic Resource Adapters.

Example: Logging Configuration Deployment Descriptors

Listing 5-7 illustrates a snippet of the deployment descriptor for configuring the logging behavior of Web application and resource adapter logging. The elements of logging correspond to attribute definitions on the LogMBean interface. All the LogMBean attributes are not listed in this example. Logging configuration is defined in the WEB-INF/weblogic.xml file for Web applications and in the META-INF/weblogic-ra.xml file for resource adapters.

<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 9.0//EN" "http://www.bea.com/servers/wls90/dtd/weblogic90-web-jar.dtd">
<weblogic-web-app>
  <logging>
    <log-filename>d:\tmp\mywebapp.log</log-filename>
    <rotation-type>bySize</rotation-type>
    <number-of-files-limited>true</number-of-files-limited>
    <file-count>3</file-count>
    <file-size-limit>50</file-size-limit>
    <rotate-log-on-startup>true</rotate-log-on-startup>
    <log-file-rotation-dir>config/MedRecDomain/WebApp</log-file-rotation-dir>
  </logging>
</weblogic-web-app>

<weblogic-connector xmlns="http://www.bea.com/ns/weblogic/90">
  <jndi-name>eis/900BlackBoxNoTxConnector</jndi-name>
  <outbound-resource-adapter>
    <connection-definition-group> 
      <connection-factory-interface>javax.sql.DataSource</connection-factory-interface>
      <connection-instance>
        <jndi-name>eis/900BlackBoxNoTxConnectorJNDINAME</jndi-name>
        <connection-properties>
          <pool-params>
            <initial-capacity>5</initial-capacity>
            <max-capacity>10</max-capacity>
            <capacity-increment>1</capacity-increment>
            <shrinking-enabled>true</shrinking-enabled>
            <shrink-frequency-seconds>60</shrink-frequency-seconds>
            <highest-num-waiters>1</highest-num-waiters>
            <highest-num-unavailable>3</highest-num-unavailable>
            <connection-reserve-timeout-seconds>11</connection-reserve-timeout-seconds>
          </pool-params>

          <logging>
            <log-filename>900BlackBoxNoTxOne.log</log-filename>
            <logging-enabled>true</logging-enabled>
            <rotation-type>bySize</rotation-type>
            <number-of-files-limited>true</number-of-files-limited>
            <file-count>3</file-count>
            <file-size-limit>100</file-size-limit>
            <rotate-log-on-startup>true</rotate-log-on-startup>
            <log-file-rotation-dir>c:/mylogs</log-file-rotation-dir>
            <rotation-time>3600</rotation-time>
            <file-time-span>7200</file-time-span>
          </logging>

          <properties>
            <property>
              <name>ConnectionURL</name>
              <value>jdbc:oracle:thin:@bcpdb:1531:bay920</value>
            </property>
            <property>
              <name>unique_ra_id</name>
              <value>blackbox-notx.oracle.810</value>
            </property>
          </properties>
        </connection-properties>
      </connection-instance>
    </connection-definition-group>
  </outbound-resource-adapter>
</weblogic-connector>

Writing Messages from a Client Application

If your application runs in a JVM that is separate from a WebLogic Server, it can use message catalogs and NonCatalogLogger, but the messages are not written to the WebLogic server log. Instead, the application's messages are written to the client JVM's standard out.

If you want the WebLogic logging service to send these messages to a log file that the client JVM maintains, include the following argument in the command that starts the client JVM:

-Dweblogic.log.FileName=logfilename

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

If you want a subset of the message catalog and NonCatalogLogger messages to go to standard out as well as the remote JVM log file, include the following additional startup argument:

-Dweblogic.log.StdoutSeverityLevel=String

where valid values for StdoutSeverityLevel are:

Debug, Info, Warning, Error, Notice, Critical, Alert, Emergency, and Off.

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

Writing Debug Messages

While your application is under development, you might find it useful to create and use messages that provide verbose descriptions of low-level activity within the application. You can use the DEBUG severity level to categorize these low-level messages. All DEBUG messages that your application generates are sent to all WebLogic server logging destinations, depending on the configured minimum threshold severity level.

If you use the DEBUG severity level, BEA recommends that you create a "debug mode" for your application. For example, your application can create an object that contains a Boolean value. To enable or disable the debug mode, you toggle the value of the Boolean. Then, for each DEBUG message, you can create a wrapper that outputs the message only if your application's debug mode is enabled.

For example, the following code can produce a debug message:

private static boolean debug = Boolean.getBoolean("my.debug.enabled");
if (debug) {
   mylogger.debug("Something debuggy happened");
}

You can use this type of wrapper both for DEBUG messages that use the message catalog framework and that use the NonCatalogLogger API.

To enable your application to print this message, you include the following Java option when you start the application's JVM:

-Dmy.debug.enabled=true