Jinsight Quick Guide

Executive Summary

Jinsight Quick Guide
very abbreviated essentials to get going

Guided Tour

Install Jinsight · Verify Install · Analyze Traces · Control Tracing · Use with WebSphere

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

To install Jinsight in your Java execution environment, get the applicable package(s):
(Omit the Swing 1.1.1 package if your Java execution environment is 1.2.2 or 1.3 or higher.)

AIX
- From IBM alphaWorks get the file jinsight2.0-aix-1.1.8.tar.Z. Uncompress and untar it. It will create a subdirectory jinsight2.0, with
  - Java instrumentation: shell script jinsight_trace, and subdirectory a118-2.0
  - Jinsight visualizer: shell script jinsight, and file jinsight.jar
- Get Swing 1.1.1, and install swingall.jar, by default into directory swing-1.1.1fcs. (only needed if you are using JDK1.1.8 to run the visualizer)
Windows
- From IBM alphaWorks get the file jinsight2.0-ibm-win-1.1.8-install.exe. Run it (an InstallShield program). It will create a subdirectory jinsight2.0, with
  - Java instrumentation: batch file jinsight_trace.bat, and subdirectory n118p-2.0
  - Jinsight visualizer: batch file jinsight.bat, and file jinsight.jar
- Get Swing 1.1.1, and install swingall.jar, by default into directory swing-1.1.1fcs. (only needed if you are using JDK1.1.8 to run the visualizer)
OS390
- From IBM Java for OS/390 get the product Java for OS/390 at the JDK1.1.8 Level. Install it as your OS/390 JDK, version PTF7; java -fullversion should show at least this level:
  "JDK 1.1.8 IBM build m118-20001122 R06 (JIT disabled)"
  Already incorporated in this JDK is the
  - Java instrumentation: for Jinsight
- From IBM alphaWorks get the OS/390 supplemental instrumentation file jinsight2.0-os390-info.tar.Z. Uncompress and untar it, and follow its directions for supplementing the OS/390 JDK
  - Java instrumentation: Jinsight supplemental information and files
- From IBM alphaWorks get the visualizer and documentation file jinsight2.0-vis.zip. Uncompress it. It will create a subdirectory jinsight2.0, with
  - Jinsight visualizer: shell script jinsight, and file jinsight.jar
- Get Swing 1.1.1, and install swingall.jar, by default into directory swing-1.1.1fcs. (only needed if you are using JDK1.1.8 to run the visualizer)

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.

Java instrumentation: Try to trace the sample Java program tinySamp
- cd to jinsight2.0, and enter:
  jinsight_trace -tracemethods tinySamp
- This should run the tinySamp program and produce a trace file named tinySamp.trc
Jinsight visualizer: Try to visualize a trace
- cd to jinsight2.0, and enter:
  jinsight traces/Hang.trc
- This should start the visualizer; select Load, and try
      Views->Table->Classes; or
      Views->Execution; or
      Views->Histogram->Objects

Analyze Traces

To get familiar using some views for trace analysis, use the sample Hang.trc trace provided. Run the 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 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 .

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.0, 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 AIX/OS390: Ctrl-\ (that is, control backslash)
- for Windows: Ctrl-Break
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 to exit from the Jinsight command console; then exit the test program.
Have a look at the trace with the Java visualizer.

Other ways to control Jinsight tracing include environment variables, a Java program interface, and a servlet html interface. See the Summary of Commands and Options in the Reference Manual section on Creating Traces.

Usage with WebSphere 3.0.2

To set up WebSphere 3.0.2 for use with Jinsight, after Jinsight is installed, see the Reference Manual sections on configuring WebSphere 3 with Jinsight and follow the steps in the appropriate section for your WebSphere platform.

To make a Jinsight trace with the chosen WebSphere 3.02 App Server, see the Reference Manual sections on Tracing Servlets. To control tracing, open jinsight2.0/jintrace.htm in a browser, fill in the server name, let your WebSphere application run to the point you want to trace, and then use the trace control Start and Stop buttons.

Executive Summary

Jinsight Home

Guided Tour