Skip navigation.
Downloads | Product Documentation | Support

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
- Using the NonCatalogLogger APIs
- Using ServletContext
- Configuring Servlet and Resource Adapter Logging
- Writing Messages from a Client Application
- Writing Debug Messages

# 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
- Step 2: Compile Message Catalogs
- Step 3: Use Messages from Compiled Message Catalogs

## 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:

1. Set the classpath by entering `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX), where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command: `java weblogic.MsgEditor`
3. To create a new catalog, choose File—>New Catalog.

For information on using the Message Editor, see Using the WebLogic Server Message Editor.

4. When you finish adding messages in the Message Editor, select File—>Save Catalog.
5. Then select File—>Exit.

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

1. Set the classpath by entering `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX), where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command: `java weblogic.MsgLocalizer`
3. Use the Message Localizer GUI to create locale-specific catalogs.

For basic command line help, type: java weblogic.MsgEditor -help

## 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:

1. From a command prompt, use `WL_HOME``\server\bin\setWLSEnv.cmd` (`setWLSEnv.sh` on UNIX) to set the classpath, where `WL_HOME` is the directory in which you installed WebLogic Server.
2. Enter the following command:

`java weblogic.i18ngen -build -d` `targetdirectory``` `source-files`

where:

- `targetdirectory` is the root directory in which you want the `i18ngen` utility to locate the generated and compiled files. The Java files are placed in sub-directories based on the `i18n_package` and `l10n_package` values in the message catalog.

The catalog properties file, `i18n_user.properties`, is placed in the `targetdirectory`. The default target directory is the current directory.

- `source-files` specifies the message catalog files that you want to compile. If you specify one or more directory names, `i18ngen` processes all XML files in the listed directories. If you specify file names, the names of all files must include an XML suffix. All XML files must conform to the `msgcat.dtd` syntax.

Note that when the `i18ngen` generates the Java files, it appends `Logger` to the name of each message catalog file.

3. If you created locale-specific catalogs in Step 1: Create Message Catalogs, do the following to generate properties files:

1. In the current command prompt, add the `targetdirectory` that you specified in step 2. to the CLASSPATH environment variable. To generate locale-specific properties files, all of the classes that the `i18ngen` utility generated must be on the classpath.
2. Enter the following command:
   `java weblogic.l10ngen -d` `targetdirectory``` `source-files`

where:

- `targetdirectory` is the root directory in which you want the `l10ngen` utility to locate the generated properties files. Usually this is the same `targetdirectory` that you specified in step 2. The properties files are placed in sub-directories based on the `l10n_package` values in the message catalog.
- `source-files` specifies the message catalogs for which you want to generate properties files. You must specify top-level catalogs that the Message Editor creates; you do not specify locale-specific catalogs that the Message Localizer creates. Usually this is the same set of `source-files` or source directories that you specified in step 2.

4. In most cases, the recommended practice is to include the message class files and properties files in the same package hierarchy as your application.

However, if you do not include the message classes and properties in the application's package hierarchy, you must make sure the classes are in the application's classpath.

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.

Listing 5-1 Sample 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`.

Listing 5-2 Locale-Specific Catalog for Spanish

>     <?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:

- `c:\MessageOutput\i18n_user.properties`
- `c:\MessageOutput\com\xyz\`msgcat\MyMessagesLogger.java
- `c:\MessageOutput\com\xyz\msgcat\MyMessagesLogger.class`
- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizer.properties`
- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizerDetails.properties`

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

1. Add the `i18n` classes to the command prompt's classpath by entering the following:
   `set CLASSPATH=%CLASSPATH%;c:\MessageOutput`
2. Enter
   `java weblogic.l10ngen -d c:\MessageOutput c:\MyMsgCat\MyMessages.xml`

The `l10ngen` utility creates the following files:

- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizer_es_ES.properties`
- `c:\MessageOutput\com\xyz\msgcat\l10n\MyMessagesLogLocalizerDetails_es_ES.properties`

## 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:

1. In the class files for your application, import the `Logger` classes that you compiled in Step 2: Compile Message Catalogs.

To verify the package name, open the message catalog XML file in a text editor and determine the value of the `i18n_package` attribute. For example, the following segment of the message catalog in Listing 5-1 indicates the package name:

`<message_catalog
i18n_package="com.xyz.msgcat"`

To import the corresponding class, add the following line:

`import com.xyz.msgcat.MyMessagesLogger;`

2. Call the method that is associated with a message name.

Each message in the catalog includes a `method` attribute that specifies the method you call to display the message. For example, the following segment of the message catalog in Listing 5-1 shows the name of the method:

`<logmessage
messageid="700000"
datelastchanged="1039193709347"
datehash="-1776477005"
severity="info"
method="startup()"
>`

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

Listing 5-3 Example Class That Uses a Message Catalog

>     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:

1. Imports the `weblogic.logging.NonCatalogLogger` interface.
2. Uses the following constructor to instantiate a `NonCatalogLogger` object:

`NonCatalogLogger(java.lang.String` `myApplication``)`

where `myApplication` is a name that you supply to identify messages that your application sends to the WebLogic server log.

3. Calls any of the `NonCatalogLogger` methods.

Use the following methods to report normal operations:

- `info(java.lang.String msg)`
- `info(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to report a suspicious operation, event, or configuration that does not affect the normal operation of the server or application:

- `warning(java.lang.String msg)`
- `warning(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to report errors that the system or application can handle with no interruption and with limited degradation in service.

- `error(java.lang.String msg)`
- `error(java.lang.String msg, java.lang.Throwable t)`

Use the following methods to provide detailed information about operations or the state of the application. These debug messages are not broadcast as JMX notifications. If you use this severity level, we recommend that you create a "debug mode" for your application. Then, configure your application to output debug messages only when the application is configured to run in the debug mode. For information about using debug messages, see Writing Debug Messages.

- `debug(java.lang.String msg)`
- `debug(java.lang.String msg, java.lang.Throwable t)`

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.

Listing 5-4 Example NonCatalogLogger Messages

>     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 (`< >`).

Listing 5-5 NonCatalogLogger Output

>     ####<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:

- `log(``java.lang.String msg``)`
- `log(``java.lang.String msg``,` `java.lang.Throwable` `t``)`

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.

Listing 5-6 Example JSP Logging

>     <%@ 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.

Listing 5-7 Configuring Web Application and Connector Logging

>     <!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`