The IBM Lock Analyzer for Java

Overview

The IBM Lock Analyzer for Java (from hereon in known as JLA) is a tool designed to help developers understand their Java™ applications use of internal Java locks. It gathers and displays lock statistics on running Java applications. This information is then used to provide analysis on the Java locks with a view to helping programmers find areas of lock contention.

The JLA application consists of 2 parts. The first of these is a platform specific package that gets loaded with the application you wish to monitor, whilst the second part is not platform specific and provides the graphical user interface. Both parts are required for the JLA to work.

The platform specific package (JLAagent)

The platform specific package is designed around a native executable agent file and a jar file. These are all packaged together and given a name based on the architecture of the Java VM that is to be used to run the application to monitor.

The platform files are named as follows

Agent Package	JVM Architecture
ap32.jar	AIX ppc 32
ap64.jar	AIX ppc 64
mz31.jar	zOS 31
mz64.jar	zOS 64
wa64.jar	Windows AMD 64
wi32.jar	Windows x86 32
xa64.jar	Linux AMD 64
xi32.jar	Linux x86 32
xp32.jar	Linux ppc 32
xp64.jar	Linux ppc 64
xz31.jar	Linux s390 31
xz64.jar	Linux s390 64

It is important to use the correct package as otherwise you will experience crashes when running the program.

The agent package needs to be unpacked to a directory on the machine that contains the application to analyze. Once unpacked, the files need to have the permissions set so that they can be executed. On unix based platforms, the command

chmod 777 *JLA*
 

will do this. Finally, for unix based platforms, there is a script file called setrunenv that needs to be run by typing

 
. ./setrunenv

to add the current directory to the classpath and system path variables. Alternatively, the classpath and system path can be manually set by typing the commands from this setrunenv file.

It is advisable (although not necessary) to unpack the agent package into the same directory as the application you wish to monitor resides. This removes any problems with the classpath and system path being set incorrectly.

The Graphical User Interface package (JLAGui)

The gui package is simply called JLAGui.jar and can be run on any machine capable of displaying graphics. This file does not need to be unpacked and can be left as is. It also does not have to be run on the same machine as the JLAagent package as it is capable of connecting to the JLAagent across a network.

Starting the agent

The startup command line for the application to gather lock information on will need to be modified to load the JLAtiagent. Several changes need to be made and these are as follows

• The native agent code needs to be loaded at runtime and this is done by adding the -agentlib:JLAtiagent parameter.
• The JLAtiagent.jar file needs to be added to the classpath and this is done with the –cp parameters
• The location of the JLAtiagent.properties needs to be specified. This file contains the options for the JMX server. It requires the -Dcom.sun.management.config.file=JLAtiagent.properties to be included.

An example of these options being used is as follows and is used to load the dummy.class application;

 
java -Dcom.sun.management.config.file=JLAtiagent.properties 
 -agentlib:JLAtiagent -cp .;JLAagent.jar dummy.class

If the application you wish to test is launched from within a jar file with a command similar to

java –jar dummy.jar

you will need to copy the JLAagent.jar file to the jre/lib/ext directory of the java environment that you are using. If this step is not done, the application will crash

upon startup. This is because the –jar command when included on the command line overrides any user classpath settings and prevents the JLAagent code locating

the JLAagent.jar file.

JLAtiagent.properties

This file contains the connection information required to create the JMX server that is used for by the GUI to connect to the agent.

option	Description
com.sun.management.jmxremote.port	default 1972 - This is the port number that the GUI will look for to see if a JMX server is running
com.sun.management.jmxremote.authenticate	default false – If this property is false then JMX does not use passwords or access files: all users are allowed all access
com.sun.management.jmxremote.ssl	default false - Enables secure monitoring via SSL. If false, then SSL is not used.

For further info on JMX. see here http://java.sun.com/j2se/1.5.0/docs/guide/management/agent.html#properties

As soon as the application is launched, the agent starts collecting thread statistics. These can be reset if required within the GUI.

If everything has been set correctly, your application will launch and you will see the following message on the command prompt

JLA Client registering MBeanServer.

Errors when starting agent

If any exception, errors or General Protection Faults occur when starting the agent, it is normally due to the path not being set correctly. Please check the setrunenv script has been run correctly and all permissions are set on the JLA files.

Starting the GUI

The GUI is launched by with the following command

java -jar JLAGui.jar
 

By default, the JLAGui will look for a JMX server running on the localhost on port 1972 and as such these values do not need to be specified. Either of these can be overridden on the command line as follows

Option	default	Description
-Dcom.ibm.jla.port	1972	needs to match the com.sun.management.jmxremote.port value used by the JLAtiagent
-Dcom.ibm.jla.hostname	localhost	This can be set to an ip address or valid hostname if you wish to monitor an application running on a remote machine

How to use the GUI

Initial startup

When the GUI initially starts it will attempt to make connection to the agent via the mbean server that is running on the machine and port number specified in the GUI startup options (see Starting the GUI). If the connection is successful then following screen will appear;

Connection problems

Should the connection be unsuccessful, an error message will appear with details of the connection it tried to make. These should be checked to make sure they are correct.

If necessary, close the GUI and re start with amended command line options. Alternatively, check to make sure the application to analyze has been started with the native agent attached.

Should connection ever fail during the running of the GUI, the above error message will appear with options to reconnect to the native agent.

It is also possible to attempt reconnection under the Options tab of the toolbar

Status bar

At the bottom of the JLAGui is a status bar that displays information such as whether a connection has been made and any problems that occur during execution.

Creating a report

Clicking on the Create Report button will create a snapshot report of the current thread statistics of application that is being monitored. Three panels are produced showing

1. Java monitors (these are the ones created by the application)

2. System monitors (these are created by the VM)

3. Summary report page.

The Java report will look something like this;

The height of each column is calculated on the value of the slow lock count and is relative to all the columns in the graph. A slow count is when the requested monitor is already owned by another thread and the requesting thread is blocked. The colour of each bar is based on the %MISS value with a gradient going from red (100%), through yellow(50%) and finally onto green (0%). A red bar indicates that the thread blocks every time the monitor is requested whereas a green bar indicated the thread never blocks. Based on this, a quick scan of the graph should show those monitors that are not performing very well as these would be coloured as red, or near to red, in colour.

The table that is produced details the following values

Column name	Description
%MISS	Pecentage of the total Gets (acquires) where the requesting thread was blocked waiting on this monitor
GETS	Total number of successful acquires
NONREC	Total number of non recursive aquires. This number includes SLOW gets
SLOW	Total number of non recursive acquires which caused the requesting thread to block waiting for the monitor to become unowned. This number is included in NONREC
REC	Total number of recursive aquires. A recursive acquire is one where the requesting thread already owns the monitor
TIER2	Total number of Tier 2 (inner spin loop) iterations on platforms that support 3-Tier spin locking
TIER3	Total number of Tier 3(outer thread yield loop) iterations on platforms that support 3-Tier spin locking
%UTIL	Monitor hold time divided by Interval Time. Hold time accounting must be switched on
AVER-HTM	Average amount of time the monitor was held. Recursive acquires are not included because the monitor is already owned when acquired recursively
MONITOR NAME	Monitor name or NULL (blank) if name is not known

Loading and Saving of reports

Under the File menu, there are options for loading and saving of reports. Saving a report will save the currently viewed report. Loading a report will allow a previously saved report to be viewed in the GUI.

What happens when the monitored application ends?

When the application ends you will be prompted to take one final report through the GUI or to exit. This enables statistics to be collected for the entire run of an application. You will see a prompt similar to the following

Clicking on the Create Report button from within the JLAGui will take a final report of the application at this point. If you do not wish to take a final report, just press the enter key to terminate the application.