![]() |
![]() |
e-docs > WebLogic Server > Using WebLogic Logging Services > Writing Messages to the WebLogic Server Log |
Using WebLogic Logging Services
|
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 files:
In addition, this section includes the following sections:
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. 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.
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 optional, additional catalogs to contain messages in a local language.
To create and edit a properly formatted message catalog, use the WebLogic Message Editor utility, which is a graphical user interface that is installed with WebLogic Server.
To access the Message Editor, do the following from a WebLogic Server host:
For more information on using the Message Editor, refer to the following:
When you save your work in the Message Editor, WebLogic Server creates the XML files that comprise your message catalogs. Listing 2-1 provides a sample message catalog that defines three messages. This sample is installed along with WebLogic Server examples in the following location:
WL_HOME\samples\server\src\examples\i18n\msgcat\UserServerSCExample.xml.
Listing 2-1 Example Message Catalog
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE message_catalog PUBLIC "weblogic-message-catalog-dtd"
"http://www.bea.com/servers/wls700/msgcat.dtd">
<message_catalog
i18n_package="examples.i18n.logging.startup"
l10n_package="examples.i18n.logging.startup"
subsystem="UserStartupClass"
version="1.0"
baseid="909050"
endid="909059"
>
<logmessage
messageid="909050"
datelastchanged="973906351125"
datehash="-854388901"
severity="info"
method="logInitialMessage(int money 0)"
stacktrace="false"
>
<messagebody>
This message displays a number as currency:
{0,number,currency}.
</messagebody>
<messagedetail>
Just an example.
</messagedetail>
<cause>
</cause>
<action>
</action>
</logmessage>
<logmessage
messageid="909051"
datelastchanged="973906462765"
datehash="-1800319350"
severity="warning"
method="logStringAndPrevCallCount(String str0, int num1)"
stacktrace="false"
>
<messagebody>
This message displays the string "{0}". There
{1,choice,0#were no previous calls|1#was one previous
call|2#were {1,number} previous calls} to the logger method
for this message.
</messagebody>
<messagedetail>
</messagedetail>
<cause>
</cause>
<action>
</action>
</logmessage>
<logmessage
messageid="909052"
datelastchanged="973906532006"
datehash="-160371672"
severity="error"
method="logFinalMessage()"
stacktrace="false"
>
<messagebody>
This is not really an error, the example has finished
normally.
</messagebody>
<messagedetail>
</messagedetail>
<cause>
</cause>
<action>
</action>
</logmessage>
</message_catalog>
Step 2: Compile Message Catalogs
After you create message catalogs, you use the following utilities to generate Java class files from the XML files:
To generate and compile the Java class files, do the following:
For complete documentation of the i18ngen commands, refer to Using the BEA WebLogic Server Internationalization Utilities in the BEA WebLogic Server Internationalization Guide.
Step 3: Use Messages from Compiled Message Catalogs
The classes generated by i18ngen provide the interface for sending messages to the WebLogic Server log. Within these classes, each log message is represented by a method that your application calls.
For example, for the message catalog named UserServerSCExample.xml (see Listing 2-1), the i18ngen utility generates a class named examples.i18n.logging.startup.UserServerSCExampleLogger. If you want your application to write the logFinalMessage message, you call the UserServerSCExampleLogger.logFinalMessage() method. Listing 2-2 illustrates a JSP that calls this method.
Listing 2-2 Example JSP That Uses a Message Catalog
<html>
Order complete. Thanks for your order!
<%@ page import="examples.i18n.logging.message.UserServerSVExampleLogger" %>
<%
UserServerSVExampleLogger.logFinalMessage();
%>
</body>
</html>
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. We do not recommended using 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 in this topic, Writing Messages from a Remote 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:
Use the following methods to report a suspicious operation, event, or configuration that does not affect the normal operation of the server/application:
Use the following methods to report errors that the system/application can handle with no interruption and with limited degradation in service.
Use the following methods to provide detailed information about operations or the state of the application. These debug messages are not forwarded to the domain log. If you use this severity level, we recommend that you create a "debug mode" for your application. Then, configure your application to output debug mesages only when the application is configured to run in the debug mode. For information about using debug messages, refer to Writing Debug Messages.
All methods that take a Throwable argument can print the stack trace in the error log. For information on the NonCatalogLogger APIs, refer to the weblogic.logging.NonCatalogLogger Javadoc.
Listing 2-3 illustrates a servlet that uses NonCatalogLogger APIs to write messages of various severity levels to the WebLogic Server log.
Listing 2-3 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 2-4 NonCatalogLogger Output
####<Jun 26, 2002 12:04:21 PM EDT> <Info> <MyApplication> <peach> <examplesServer> <ExecuteThread: '10' for queue: 'default'> <kernel identity> <> <000000> <Application started.>
####<Jun 26, 2002 12:04:23 PM EDT> <Warning> <MyApplication> <peach> <examplesServer> <ExecuteThread: '10' for queue: 'default'> <kernel identity> <> <000000> <Can't establish connections. >
javax.naming.CommunicationException. Root exception is java.net.ConnectException: t3://localhost:8000: Destination unreachable; nested exception is:
...
Table 2-1 describes all of the fields that NonCatalogLogger log messages can contain.
Date and time when message originated, including the year, month, day of month, hours, minutes and seconds. For example, <Jun 26, 2002 12:04:21 PM EDT>. |
|
One of the following severity values, which corresponds to the type of method that you used to generate the message: |
|
Indicates the source of the message. This is the string that you supply for the NonCatalogLogger constructor. |
|
The name of the computer that hosts the JVM on which your application runs. |
|
The name of the WebLogic Server instance on which your application is running. |
|
Indicates the execute thread that the current process is using. You can fine-tune an application's access to execute threads (and thereby optimize or throttle its performance) by using multiple execute queues in WebLogic Server. For more information, refer to Using Execute Queues to Control Thread Usage in the BEA WebLogic Server Performance and Tuning guide. |
|
User on behalf of whom the system was executing when the error was reported. |
|
Present only for messages logged within the context of a transaction. |
|
A six-digit identifier for the message. The message ID for NonCatalogLogger messages is always 000000. |
|
If the message is logging an Exception, this field contains the name of the Exception. |
The javax.servlet.GenericServlet servlet specification provides the following APIs that your servlets can use to write a simple message to the WebLogic Server log:
For more information on using these APIs, refer to the J2EE Javadoc for javax.servlet.GenericServlet at http://java.sun.com/products/servlet/2.3/javadoc/javax/servlet/GenericServlet.html.
JSPs do not extend from GenericServlet and cannot use these APIs. If you want your JSPs to send messages to a log file, consider using the I18N message catalog services or NonCatalogLogger APIs.
Writing Messages from a Remote 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 a WebLogic Server log. Instead, the application's messages are written to the remote JVM's standard out.
If you want the WebLogic logging service to send these messages to a log file that the remote JVM maintains, include the following argument in the command that starts the remote 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 standard out as well as the remote JVM log file, include the following additional startup arguments:
-Dweblogic.StdoutEnabled=true
-Dweblogic.StdoutDebugEnabled=boolean
-Dweblogic.StdoutSeverityLevel = [64 | 32 | 16 | 8 | 4 | 2 | 1 ]
where boolean is either true or false and the numeric values for StdoutSeverityLevel correspond to the following severity levels:
INFO(64) WARNING(32), ERROR(16), NOTICE(8), CRITICAL(4), ALERT(2) and EMERGENCY(1).
Writing Messages from a Remote JVM to a File
A remote JVM can generate its own set of messages that communicate information about the state of the JVM itself. For example, you can configure a JVM to generate messages about garbage collection. By default, the JVM sends these messages to standard out. You cannot redirect these messages to the JVM's log file, but you can save them to a separate file. For more information, refer to "Redirecting System.out and System.err to a File" in the WebLogic Server Administration Guide.
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 the WebLogic Server log file. (Unlike Log4j, which is a third-party logging service that enables you to dynamically exclude log messages based on level of severity, the WebLogic Server log includes all levels of messages that your application generates.)
You also can configure the WebLogic Server to send DEBUG messages to standard out. For more information refer to Specifying General Log File Settings in the Administration Console Online Help.
If you use the DEBUG severity level, we recommend 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.
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 messages that use the message catalog framework and that use the NonCatalogLogger API.
![]() |
![]() |
![]() |
![]() |
||
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |