Jinsight Reference Manual

Tracing Tips

Running the visualizer  · The workspace window · Customizing jinsight.bat

Jinsight Views

Running the visualizer

You can run the Jinsight visualizer using jinsight.bat.  Here are three ways to do this:

• Run jinsight.bat, and specify a trace file as a parameter.  For example, try visualizing the sample trace GCExample1.trc:

jinsight GCExample1.trc

• Alternatively, you can first double-click on any icon of a .trc file and associate the .trc file extension with jinsight.bat.  Next time you double click on a .trc file, Jinsight will appear, ready to read this trace file.

• Run jinsight with no parameters, and specify the file later from the Jinsight workspace window.

In some cases you may need to modify jinsight.bat for your environment.  See Customizing jinsight.bat. 

The Jinsight workspace window

The Jinsight workspace window is the main window for Jinsight.  You may use it to specify a trace file, to control the loading of the trace, and to choose the views you want to see.

Use the Load and Stop buttons at the bottom of the panel to start and stop the loading of the trace. The workpace window displays the trace file name you have specified and the number of events and percentage of the trace that have been loaded so far. Note that as you are loading the trace, any views that are open will not be refreshed until after you have stopped loading.

Menus

File

Under this menu are the functions Open Trace File..., Close Workspace, and Exit Jinsight. Closing the workspace window will close all views open in the workspace.

The functions Create New Workspace and Rename Workspace are described in the section Workspace Operations, and Blend Colors When Slices Overlap is described in Using Slices in Views.

 

Filtering events that are loaded into Jinsight.

You may choose to exclude events, of specified classes or beyond a specified stack depth, to reduce the amount of data Jinsight loads. This will unclutter some views, and it will forestall memory problems when viewing large traces.

Choose Set Trace Filter... to open a dialog box in which to specify which events to filter out.  The default is to use all events in the trace.  The initial dialog box shows suggestions of criteria by which you could filter out events:

• events whose class name begins, e.g., either with the prefix java/ or sun/, or
• events that occur at a call stack depth greater than, e.g., 10.

To filter out events, check the relevant boxes and specify the desired criteria.

When you filter out events by class name, the execution views will still show calls to these classes from unfiltered classes.  If there is a call from any filtered class to an unfiltered class, the execution views will show the complete invocation sequence that gave rise to that call, independent of filtering.

Specify classes to exclude by typing one or more prefixes in the dialog box. Classes whose names begin with the prefix have their events excluded.  For example,

java/awt/  java/io/

will hide calls among classes in the awt and io packages.  However, call sequences between these classes and unfiltered classes will be shown.  You can use spaces, newlines, commas, or semicolons to separate the prefixes.  Use slashes to separate package names.

Note that all aggregate measures of time and number of calls will reflect this filtering.

 

Views

Choose from among six views of trace data:  

Histogram

Shows information about objects or methods of each class.

 

Execution

Shows the sequence of events in each thread over time.

Execution Pattern

Shows recurring execution patterns in summarized form.

 

Call Tree

Shows summary measures of each call path starting from or leading to a given set of method invocations.

 

Reference Pattern

Lets you explore patterns of references to or from a set of objects, in varying detail; this is useful for studying data structures and finding memory leaks.

 

Table

Shows summary measurements in spreadsheet form for threads, packages, classes, methods, objects, invocations, or user-defined slices.
 

Windows

Use these menus to manage the views opened by this workspace. The first three menu items, Hide All, Show All, Close All, will affect all views open in this workspace. Below these menu items is a list of all views currently open in the workspace. Selecting a view will cause that view to become the active window.

 

Help

Displays reference documentation for Jinsight.

Customizing jinsight.bat

for Windows:

  %JAVA_HOME%\bin\java.exe  -mx%JINSIGHT_HEAP%  
      -classpath %JAVA_HOME%\lib\classes.zip;%SWING_HOME%\swingall.jar;
          %JINSIGHT_HOME%\jinsight.jar;.  
      -DJINSIGHT_MAXHEAP=%JINSIGHT_HEAP%  
      -DJINSIGHT_BROWSER=%JINSIGHT_BROWSER%  
      -DJINSIGHT_DOC=.\%JINSIGHT_HOME%\docs\  
       jinsight.main.Jinsight  %1 

with typical Windows environment variables:

      JAVA_HOME=c:\jdk1.1.8
     SWING_HOME=C:\swing-1.1.1fcs
  JINSIGHT_HOME=C:\jinsight2.0
  JINSIGHT_HEAP=230M
  JINSIGHT_BROWSER=c:\progra~1\netscape\communicator\program\netscape.exe

for AIX:

  ${JAVA_HOME}/bin/java  -mx${JINSIGHT_HEAP}  
      -classpath ${JAVA_HOME}/lib/classes.zip:${SWING_HOME}/swingall.jar:
          ${JINSIGHT_HOME}/jinsight.jar:.  
      -DJINSIGHT_MAXHEAP=${JINSIGHT_HEAP}  
      -DJINSIGHT_BROWSER=${JINSIGHT_BROWSER}  
      -DJINSIGHT_DOC=${JINSIGHT_HOME}/docs/  
      jinsight.main.Jinsight  "$@"

with typical AIX environment variables:

      JAVA_HOME=/usr/jdk_base
     SWING_HOME=~/swing-1.1.1fcs
  JINSIGHT_HOME=~/jinsight2.0
  JINSIGHT_HEAP=96M
  JINSIGHT_BROWSER=/usr/local/bin/netscape

Notes on the above options and environment variables:

• Some options vary when moving from JDK1.1.8 to JDK1.2.2 and JDK1.3. For example, the option -mx should be changed to -Xmx. And users of JDK1.2.2. and JDK1.3 should omit the explicit -classpath references to classes.zip and swingall.jar.
• The final argument ( %1 or "$@" ) is the full trace file name.
• Setting JINSIGHT_BROWSER and JINSIGHT_DOC will enable the help menu connections to the Jinsight online documentation.
• Use option -mx or -Xmx, in conjunction with the JINSIGHT_MAXHEAP variable, to make full use of your available memory.  To visualize a large trace, you may need to raise these values so Jinsight doesn't run out of memory while loading the trace.
• The JINSIGHT_MAXHEAP variable can be used to help load traces that are otherwise too large for Jinsight to load.  If this variable is set, then when Jinsight has consumes more memory than 80% of JINSIGHT_MAXHEAP, it will print out a warning message, and then filter out detailed information about the execution sequence beyond that point, only loading information about objects.  It is equivalent to setting the Workspace Window => File => Set Trace Filter...  to a stack depth filtering  level of 0 at that time.  JINSIGHT_MAXHEAP should typically be set to a value equal to or somewhat lower than the value in the -mx option.  See also Creating smaller traces and Working with large traces.

If instead you want to run the visualizer from the command line without using this command file, update your classpath to make the visualizer accessible to your Java run-time environment:

  Windows: set CLASSPATH=%CLASSPATH%;%JINSIGHT_HOME%\jinsight.jar
  AIX:  export CLASSPATH=$CLASSPATH:${JINSIGHT_HOME}/jinsight.jar






Tracing
Tips


Jinsight Home



Jinsight Views