Jinsight Quick Guide

Executive Summary

Jinsight Quick Guide
Jinsight for Java 2
abbreviated essentials to get going

Supplemental Info

Install Jinsight · Verify Install · Analyze Traces · Control Tracing · WebSphere 3.5 and additional topics

Jinsight is a tool for analyzing and visualizing how Java programs execute. Jinsight has two parts:

Java instrumentation, which generates trace data as your Java program runs.
Jinsight visualizer, which reads the trace data and presents views for analysis.

Install Jinsight for Java 2

To install Jinsight for Java 2 in your IBM Java 2 execution environment, get the applicable package(s):

AIX
- From IBM alphaWorks download to AIX the latest file jinsight2.1-aix-java2.tar.Z. Untar it, creating AIX subdirectory jinsight2.1, with
  - Java instrumentation: shell script jinsight_trace, and file libjinsightPA.so
  - Jinsight visualizer: shell script jinsight, and file jinsight.jar
Windows
- From IBM alphaWorks download to your PC the latest file jinsight2.1-ibm-win-java2.zip. Unzip it, creating PC subdirectory jinsight2.1, with
  - Java instrumentation: batch file jinsight_trace.bat, and file jinsightPA.dll
  - Jinsight visualizer: batch file jinsight.bat, and file jinsight.jar
OS390
- From IBM alphaWorks download to your PC the latest file jinsight2.1-os390-java2.zip. Unzip it, creating PC subdirectory jinsight2.1, with
  - Java instrumentation: tar file jinsight2.1-os390-java2.tar to FTP to your OS/390 system
  - Jinsight visualizer: batch file jinsight.bat, and file jinsight.jar for your PC.
- On your OS/390 system, untar the instrumentation tar file, creating OS/390 subdirectory jinsight2.1.

Verify Install

To verify the Jinsight installation, try tracing and visualizing. First make sure the environment variables in the command files jinsight_trace and jinsight reflect your installation. In particular, check variables JINSIGHT_HOME and JAVA2_HOME.

Java instrumentation: Try to trace the sample Java program apiSample21.
- cd to jinsight2.1, and enter:
  jinsight_trace apiSample21
- This should run the apiSample21 program and produce a trace file named trace.trc
Jinsight visualizer: Try to visualize that trace (or the sample traces/Hang.trc).
- (If necessary, FTP in binary to your PC the trace.trc file you just created.
- cd to jinsight2.1, and enter:
  jinsight trace.trc or jinsight traces/Hang.trc
- This should start the visualizer; select Load, and try
      Views->Table->Classes; or
      Views->Execution; or
      Views->Histogram->Objects

The visualizer section of the Reference Manual contains further details about visualizing traces.

Analyze Traces

To get familiar using some views for trace analysis, use the sample Hang.trc trace provided. Run the Jinsight2.1 visualizer on that trace, load the trace, and consider the following sample of questions:

Which methods run the longest?
Select Views->Table->Methods, and click on the column heading cumulative time to sort it.
Which methods take the most CPU time? Which are called the most?
In the method table, select Columns->Choose Attributes, and select base time and number of calls. Then sort the method table by these data.
What does the overall execution look like?
Select Views->Execution to see an overview of method execution. Time is depicted vertically, the columns are threads of execution, and the method execution stack grows to the right within each execution thread. Zoom in by dragging the mouse over a rectangular area. Fly over the method call labels, which are calls to methods in objects colored by class; method call details are displayed below on the status line.
Which classes have used the most memory?
Select Views->Histogram->Objects; select ObjectAppearance->MemorySizeTotal; select Options->SortClassColorsNow, which sorts the class names in the histogram by memory usage. Fly over class names to see memory usage as numeric data.
Can I restrict a view to show just the things I'm interested in?
Select Views->Table->Methods, and sort it by cumulative time. Select the println(String) by right clicking on it and selecting Drill Down From Selected Items->Call Tree. The resulting Call Tree view shows (to an initial depth of 3) only the calls from the println(String) method.
Which objects may be causing memory leaks?
Rerun the Jinsight2.1 visualizer on trace RPExample1.trc, load it, and select Views->Reference Pattern. Select Start with => Non-JDK and Non-Array Objects in New Generation. The grey area shows potential leaks -- i.e. selected objects that cannot be garbage-collected; references retained to them from red-colored objects may be possible causes of memory leaks.

Additional ways to filter information and to group together information you are interested in for analysis are shown in the Slices and Workspaces section of the Jinsight Guided Tour of the documentation for Jinsight2.0.

Control Tracing

Traces can grow very quickly, so it's important to trace selectively. To get familiar with controlling Jinsight tracing, try tracing the sample loopTest program.

cd to jinsight2.1, and enter: jinsight_trace loopTest
The loopTest program should start and remain running for several seconds.

While the program is running, access the Jinsight command console by entering,

  for Windows:  Ctrl-Break
  for OS390:    Ctrl-V     (wait for dump to complete)
  for AIX:      Ctrl-\     (currently not operational)

Enter some 2-character commands from the set of choices presented; for example:
- tm -- start tracing methods
- sm -- stop tracing methods
- dp -- dump (into the trace) the current population of objects
- dr -- dump (into the trace) the current object population and references
Press the Enter key (on OS/390 press 'x') to exit from the Jinsight command console; then exit the test program.
Have a look at the trace with the Jinsight2.1 visualizer.

Other options to control Jinsight tracing are through environment variables, a Java program interface, and a servlet html interface. These Jinsight2.1 options differ in some ways from the options in Jinsight2.0, and they vary somewhat by tracing platform.

  for Windows:  Tracing Commands and Options for Jinsight2.1 on Windows 
  for OS390:    Tracing Commands and Options for Jinsight2.1 on OS/390 
  for AIX:      Tracing Commands and Options for Jinsight2.1 on AIX

WebSphere 3.5 and additional topics

To set up WebSphere 3.5 for use with Jinsight2.1, after Jinsight2.1 is installed, see the following sections appropriate to your WebSphere platform.

  Configuration and Tracing with WebSphere 3.5 on AIX or Windows 
  Configuration and Tracing with WebSphere 3.5 on OS/390

There are some very important differences in the Jinsight API calls, plus other functionality changes for those who previously used Jinsight2.0. See the following descriptions:

  Some Functionality Differences from Jinsight2.0 to Jinsight2.1

A few of the common problems encountered using Jinsight2.1 are listed in this section, with possible remedies:

  TroubleShooting

Executive Summary

Jinsight Home

Supplemental Info