JRas is a logging and tracing facility built into IBM WebSphere Application Server (WAS), which relies on JRas as its internal logging framework. Programmers can also leverage this powerful logging system infrastructure to keep an eye on their enterprise applications powered by WAS.

Developers can use the JRas Java APIs to generate both log and trace messages. Used properly, these two mechanisms can provide priceless information regarding the application's process of execution.

In this article, the reader will learn to use JRas through the context of a sample application. The provided source code will allow developers to immediately begin taking advantage of the JRas facility and start considering it for their own enterprise applications.

Why the Fuss about Tracing and Logging?
In a Utopian world, your applications would always work and there would be no need to monitor them, but the reality is that you don't live in Utopia. Your enterprise applications demand attention. You might leverage JRas to provide simple status messages to keep WebSphere administrators abreast of the execution of an enterprise application. At the same time, JRas diagnostic trace (trace) statements might be embedded within your code which can be extremely helpful to diagnose and remedy problems with your application.

Differentiating Between Messages and Traces
In JRas terminology, messages consist of information that is brief, clear, and useful to an end user. A simple example might be a status message saying an application was started successfully. Message entries are informational records intended for end users, system administrators, and support personnel.

In JRas terminology, message entries are informational records that are brief, clear, and useful intended for end users, system administrators, and support personnel. A simple example is a status message notifying that an application has been successfully started.

On the other hand, trace entries contain more detailed information that might include the timestamp, execution thread ID, method execution, and a description of the error. Typically, development teams and service engineers use this detailed information to dissect and troubleshoot an application. Enabling the trace facility is a costly operation in terms of taxing the system resources and should only be performed to troubleshoot the system.

Terminology
Before beginning our logging endeavors, let's review some terminology critical to understanding JRas.

• Event classes: JRas defines message and trace event classes.
• Event types: JRas ships with predefined event types for messages and tracing. For example, some message types include information, warning, and error messages. Some trace types include entry, exit, and trace.
• Loggers: These represent the workhorse of JRas. JRas defines message and trace loggers. As their names imply, message loggers create message records, while trace loggers are responsible for creating trace records.
• Message handlers: Loggers use registered handlers to output their events. For example, a file handler might be used to write an event to a file.
• Formatters: Formatters can be used with JRas handlers to format data destined to an output device. In this article, the default formatting will be used. To learn more about formatting, view the information provided in the WebSphere Application Server Information Center Reference Library.
• Message masks: Masks are configured for a logger to process only a subset of messages. For example, a mask can be configured for a logger to process only error messages and ignore informational/warning messages.

A Lab Rat
To demonstrate the usage of JRas, a simple stateless session Enterprise JavaBean (EJB) will be used. Download the provided EAR artifact and import it into your WebSphere Studio workspace or deploy it to WAS. The logging implementation will be contained in the business method of the JRasEJB. This method, as shown here, capitalizes an incoming String and prepends the following text: "Right back at you:"

public String echoMe(String argument)
{
	String whatToReturn = "Right back at you: " + argument;
	whatToReturn = whatToReturn.toUpperCase();
	return (whatToReturn);
		
}

The full implementation of the JRasEJBBean without the logging incorporated is shown in Listing 1.

Let's Do Some Logging!
The process of incorporating JRas logging into the application is rather straightforward.

1. Retrieve a reference to the JRas manager
2. From the returned manager, retrieve message and/or trace loggers.
3. Call methods on the message and trace loggers to create message and trace entries.

This exact process will be implemented into the EJB. Review Listing 2, as it shows the final implementation.

Our steps of retrieving a reference to the JRas manager as well as retrieving message and trace loggers was accomplished with the code shown in Listing 3.

The syntax is straightforward; note that that following arguments are provided to create the logger and tracer:

1. Name of our organization
2. Application name
3. Component identifier
4. Class name

The trace and message loggers are static final member variables allowing for a single initialization phase at instantiation.

Now modify the echoMe method to leverage the logger and tracer using the code shown in Listing 4.

The trace file will contain entries of method entrances and exits. This is facilitated through the use of entry and exit methods of the RASTraceLogger object, along with the predefined event type of RASITraceEvent.TYPE_ENTRY_EXIT. There are several other available RASITraceEvent enumerated types. Refer to the WebSphere Application Server Information Center for the full breakdown of available features. Note that trace events will appear only in the server's trace.log file, discussed later in this article.

Examine the source code and notice that the RASMessageLogger's textMessage method is used periodically to post messages to the console. Different RASIMessageEvent types, namely RASIMessageEvent.TYPE_INFO, RASIMessageEvent.TYPE_WARNING, and RASIMessageEvent.TYPE_ERROR, are used in the provided implementation. These different types are displayed differently on the console, as will be shown later.

Enabling Logging in Application Developer and WebSphere Application Server
To reap the benefits of the logging implementation, WebSphere Studio's trace facility must be enabled. Accomplish this by choosing the Trace tab in the Server Configuration view of the server housing the enterprise application. Ensure that "Enable Trace" is selected. By default, the String text box will have the value:

*=all=disabled

Modify this entry with the appropriate package hierarchy. For this exercise, add the following entry:

com.ibm.jrasdemo*=all=enabled

The modification is shown in Figure 1.

The tracing facility in WAS can be enabled through the Administrative Console. Select the appropriate application server instance housing the enterprise application and enable the tracing facility from the Configuration section. Choose "Logging and Tracing Option" and "Diagnostic Trace" (see Figure 2).

Test the business method of the sample EJB, echoMe, using WebSphere Studio's Universal Test Client. The successful execution is shown in Figure 3.

Understanding What Happened in Our Console
Running the EJB will output to the console messages we incorporated into the code (see Figure 4).

In Figure 4, note that the event types are signified by the "A", "W", and "E" notations displayed to the left of the class name. These stand for Audit, Warning, and Error respectively. In the JRas realm, the TYPE_INFO maps to a WAS platform native type of "Audit". Similarly, the TYPE_WARNING maps to the native type of "Warning", and TYPE_ERROR maps to the native type "Error". Take note that the trace messages don't appear in our console and appear only in the trace file, which we will now analyze.

Understanding What Happened in Our Trace File
Open the trace.log file and view the detailed information provided regarding the application's execution (see Figure 5).

Let's point out some interesting information to note about our trace file.

• Method entry and exit points are signified by ">" and "<" respectively, noted to the left of the fully qualified class name. Note that the incoming (i.e., Kulvir) and outgoing (i.e., RIGHT BACK AT YOU KULVIR) values are also displayed.
• Note that both message and trace information can be found in the trace file.
• The exception, hidden from the console, is vividly described in the form of a stack trace. End users may provide custom error codes mapping to more detailed information found in the trace file to diagnose application problems.

Performance Considerations
Enabling the use of JRas within the application code is a good technique for diagnosing an enterprise application. However, this benefit does not come without cost. Enabling the trace facility requires extensive disk I/O processing, potentially affecting the application's performance.

Conclusion
In this article, we introduced the JRas logging facility. Other popular logging systems such as Apache Log4J and Java 1.4 Java Logging API have a large industry following. However, JRas offers a tight integration with WAS's system management, in particular with the Administrative Console. As shown in this article, JRas integrates with both WebSphere Studio and WAS. Enterprises can leverage JRas to monitor applications in an extremely powerful fashion.

References

Using the JRas Message Logging and Trace Facility: JRas Message Logging and Trace Facility

WebSphere Application Server Information Center Reference Library: (WebSphere Application Server Information Center

• Figure 2
• Figure 3
• Figure 4
• Source Code
• Figure 1
• Figure 5