Using the JRockit Runtime Analyzer

Using the BEA JRockit Runtime Analyzer

This product is provided "as-is," without any expressed or implied warranties or support by BEA Systems, Inc. This product, which may or may not become an officially supported product from BEA Systems, may contain errors and/or inaccuracies. Use of this product is left solely upon the discretion of the user without any endorsement from BEA Systems. The JRA functionality may or may not be available in future BEA JRockit versions. Questions and problems may be reported via online BEA JRockit newsgroups at http://newsgroups.bea.com.

The BEA JRockit Runtime Analyzer (JRA) tool provides a wealth of information on internals in BEA JRockit that are interesting to the development team of BEA JRockit. Some of these metrics are also interesting to Java developers using BEA JRockit as their runtime VM.

Note: The JRA tool itself requires J2SE version 1.4 or higher; however, you can create JRA recordings from BEA JRockit version 7.0 sp6 or higher.

The BEA JRockit Runtime Analyzer consists of two parts. One is running inside the JVM and recording information about the JVM and the Java application currently running. This information is saved to a file which is then opened in the other part: the analyzer tool. This is a regular Java application used to visualize the information contained in the JRA recording file.

This section describes how to get started with JRA, i.e. downloading, creating a recording, and open the tool. The following subjects will be covered:

Downloading the JRA Tool

Download a copy of the JRA tool from:

http://dev2dev.bea.com/wljrockit/tools.html

Creating a Recording

There are several ways to create and start a JRA recording:

Start Recording from Management Console (JRockit J2SE 1.4 or higher)

Start your Java application with BEA JRockit, and add the -Xmanagement option to the command line.

Start the Management Console and connect to the JRockit instance you just started. (See the BEA JRockit Management Console documentation for details on how to do this.)

Make sure that your application is running and is under load.

If you run the application without stress, the data captured from that application will not show where there is room for improvements.

In the BEA JRockit Management Console, click Plugins > Start JRA recording.

The JRA Recording dialog box appears (Figure 1-1). Figure 1-1 JRA Recording Dialog Box

Type a descriptive name for the recording in the File name field.

This is the name of the file on the host machine where the recording is made. The file is created in the current directory of the BEA JRockit process, unless you specify a different path. It will be overwritten if it already exists.

Set a time for the length of the recording (in seconds).

Note: If you set a time that is too short, e.g. shorter than 30 seconds, you will probably not get enough sample data for the recording to be meaningful.

Select none, one, or all of the following sampling options:

Method sampling—records samples of methods
GC sampling—records garbage collection events
Native sampling—records samples of native code

Click Start recording.

The JRA Recording Progress box appears (Figure 1-2). Figure 1-2 JRA Recording Progress Box
This box indicates that the recording has started. You will see a confirmation message, in the JRockit command line window, halfway through the recording and when the recording is finished. After the final message is printed you can shut down your application if you want.

Start Recording with the JraRecordingStarter Command

Add the startup command -Xmanagement when you start your Java application with BEA JRockit. This tells BEA JRockit to open a port and listen to commands from the management server (for more information, please refer to Enable the Management Server in Using the BEA JRockit 5.0 Management Console document for your corresponding JRockit version).

Make sure that your application is running and is under load.

If you run the application without stress, the data captured from that application will not show where there is room for improvements.

Use the following command to initiate a recording:

java -jar JraRecordingStarter_15.jar <server> <port> <filename> <recording_ time>

Where the arguments are:

server—the host name (or IP address) of the machine where your application is running (usually "localhost").
port—the port that BEA JRockit is listening to (usually 7091 for JRockit 1.4 or earlier, it is usually 7090).
filename—the name of the file you want to save the recording to (for example jrarecording.xml). This is the name of the file on the host where the recording is done (server above). The file will be created in the current directory of the BEA JRockit process. It will be overwritten if it already exists.
recording_time — the duration of the recording in seconds (a good length is 300 seconds, i.e., five minutes).

For example:

java -jar JraRecordingStarter_15.jar localhost 7091 jrarecording.xml 300
Note: For JRockit versions 1.4 or older, the command to start a JRockit recording is JraRecordingStarter_14.jar.
After the recording is initiated, BEA JRockit prints a message indicating that the recording has started. Another message will appear halfway through the recording and a final message when the recording is finished. After the final message appears, you can shut down your application.

Start a Recording from the JRockit Command Line

You can also start a JRA recording from the command line by using some additional options to the java command when you start up the application you want to record. Table 1-1 lists the different options depending on which version of JRockit you are running.

If you are running BEA JRockit version 1.4.2_04 or newer use the command -XXjra together with the parameters listed in the BEA JRockit 1.4.2_04 or newer.

If you are running BEA JRockit version 1.4.2_03 or older, you need to set each parameter with its own startup option (listed in BEA JRockit 1.4.2_03 or older in Table 1-1).

Table 1-1 Command Line Startup Parameters

BEA JRockit 1.4.2_04 or newer	BEA JRockit 1.4.2_03 or older	Description
`delay`	-XXjradelay	Amount of time, in seconds, to wait before recording starts.
`recordingtime`	-XXjrarecordingtime	Duration, in seconds, for the recording. This is an optional parameter. If you don't use it, the default is 60 seconds)
`filename`	-XXjrafilename	The name of recording file. This is an optional parameter. If you don't use it, the default is `jrarecording.xml`.
`sampletime`	-XXjrasampletime	The time, in milliseconds, between samples. Do not use this parameter unless you are familiar with how it works. This is an optional parameter.
`nativesamples`	-XXjranativesamples	Displays method samples in native code; that is, you will see the names of functions written in C-code. This is an optional parameter.

An example of using the -XXjra startup command:

-XXjra:delay=10,recordingtime=100,filename=jrarecording2.xml

would result in a recording that:

Commenced ten seconds after JRockit started (delay=10).
Lasted 100 seconds (recordingtime=100).
Was written to a file called jrarecording2.xml (filename=jrarecording2.xml).

To replicate this data with the JRA version released with BEA JRockit 1.4.2_03 or older, you would need to enter the following four separate commands:

-XXjradelay=10
-XXjrarecordingtime=100
-XXjrafilename=jrarecording2.xml

Starting the JRA Tool

Use the JRA tool to see the recording you just created. Start the tool with java -jar RuntimeAnalyzer.jar. This will open the JRA application (see Figure 1-3):

Figure 1-3 JRA Application with an Open Recording

JRA Application with an Open Recording

Opening a Recorded File

Click File > Open file.

Locate and select the recorded file and click Open.

The Improve JRockit window opens. In this window you find information on how you can help the JRockit engineering team improving JRockit and the JRA.

Click OK.

The JRA General window is now filled with data (see Figure 1-3).

Note: If you are running an older version of the JRA, some fields may not have any relevant data, since that data was impossible to obtain.