Jinsight Frequently Asked Questions

Download one of the Jinsight2.1 packages from IBM alphaWorks. Make sure the environment variables in the command file jinsight reflect your installation. In particular, check variables JINSIGHT_HOME and JAVA2_HOME. Then go to directory jinsight2.1, and invoke the command file:     jinsight

This should bring up the Jinsight workspace window, where you choose File and Open Trace File, and then select the trace you want to visualize. For a sample trace, open the directory traces, pick the Hang.trc file, and click on Open. Then push the Load button on the workspace window.

Details:

 
• The installation provides a command file jinsight.bat, which may need to be tailored depending on your Java environment. (If for some reason the command file runs but fails, you might try inserting a pause statement at the end of the command file named jinsight, and run it again.)

 
• The visualizer is the file jinsight2.1\jinsight.jar; this file needs to be in your classpath.

 
• The main visualizer method to execute is jinsight.main.Jinsight, which takes one argument, the trace file name.

 
• The installation provides sample traces in directory jinsight2.1\traces.

 

The documentation is in HTML files in all of the download packages. It is in the directory jinsight2.1\docs. The documentation provides an executive summary, a quick start with installation details, a guided tour, a how-to guide, a reference manual, FAQs, and release notes.
 

Look at the Jinsight Release Notes. Additional details about recent visualizer features can be found in the guided tour, for example, under Table View, Call Tree View, and Navigation, and Slices and Workspaces. Further details are in the reference manual, for example, under Call Tree View, Table View, and Slices and Workspaces.
 

In the command file jinsight_trace, use the -Xmx Java option to set the maximum Java heap size, and use the JINSIGHT_MAXHEAP variable to continue (by not loading detailed trace information) when nearing the memory limit. For extremely large traces, you can also set trace filtering in the visualizer, which can filter out trace events by package name or by stack depth during trace loading.

Details:
 

1. Set the maximum Java heap size by using the -Xmx option. At the same time, set the JINSIGHT_MAXHEAP variable in the jinsight command file, to cause the visualizer to continue running by stopping loading detailed trace information after consuming more than 80% of the specified memory limit. For example:

java.exe  -Xmx230M  -DJINSIGHT_MAXHEAP=230M  jinsight.main.Jinsight  sample.trc

2. Use filtering to further reduce the amount of information stored in the visualizer. For example,
 
1. Choose Workspace Window => File => Set Trace Filter...
2. Check the entry on Do not save events of classes starting with:
3. Type
   java/  sun/     in the text area of the dialog
4. Press OK.

 
Jinsight will now ignore details of how java/ and sun/ methods execute, assuming that information is relatively uninteresting to you. That will reduce Jinsight's memory consumption considerably.
 

Use the command file jinsight_trace, to invoke your program and use Jinsight. For Jinsight2.1 (for Java 2), the instrumentation is a profiling agent using the JVMPI interface of Java 2. For Jinsight2.0 (for Java 1.1.8), the instrumentation is a replacement tracing VM that is installed in either directory n118p-2.0 (on Windows), or directory a118-2.0 (on AIX).

Details:

 
• Download the Jinsight appropriate to your platform, obtained fromIBM alphaWorks.
• Make sure the environment variables in the command file jinsight_trace reflect your installation. In particular, check variables JAVA2_HOME or JINSIGHT_JDK.
• Set the CLASSPATH environment variable to the location of your program.
• First try tracing everything in the sample program loopTest:

  for Jinsight2.1: set JINSIGHT_TRACE_METHODS=YES; then enter:  jinsight_trace  loopTest
  This will write a large trace file trace.trc. Note that setting env var JINSIGHT_TRACE_METHODS to any value will produce a very large trace for anything but a very short running program.

  for Jinsight2.0: enter:  jinsight_trace  -tracemethods  loopTest
  This will write a large trace file loopTest.trc. Note that using option -tracemethods will produce a very large trace for anything but a very short running program.

• End the tracing of your program cleanly, so that the entire trace will be written out. Either use a command from Jinsight Summary of Commands and Options such as 'q' to quit your program, or end your program normally. Otherwise, the trace file may not be completely written out.

 
• See the online documentation for additional details about tracing and tracing tips. Use either the Jinsight console commands or API calls to control tracing, rather than the JINSIGHT_TRACE_METHODS environment variable.

 

Read the section on creating traces. Control how much is traced by using one or more of the following:

 
• an invocation option to jinsight_trace (Jinsight2.0 only)
• a Jinsight tracing console command
• an environment variable
• a Java program method call
• For WebSphere, the TraceControlServlet named jintrace

Details:

 
• For Jinsight2.0 only, the jinsight_trace command file provides the following options at startup:

    -tracepopulation   trace object creation/collection
    -tracemethods      trace all method enters/leaves

You can begin without either option, and later issue a trace command at the console prompt.

• The Jinsight console prompt provides similar options:

    tm                start tracing methods
    tp                start tracing population events
    sm                stop tracing methods
    sp                stop tracing population events
    S                 stop tracing
    g                 force synchronous garbage collection
    dp                dump object population
    dr                dump object population and references
    q                 end all tracing

• Jinsight environment variables let you control the tracing mode at startup:

   (default)                  turn off tracing 
   JINSIGHT_TRACE_METHODS     turn on tracing methods 
   JINSIGHT_TRACE_POPULATION  turn on tracing object creation/collection

• The Jinsight API calls provide options to control tracing:

The Jinsight 2.0 calls are:

   Runtime.getRuntime().traceMethodCalls(true);
   Runtime.getRuntime().traceMethodCalls(false);
   import com.ibm.jinsight.tracing.*;
   JinsightCtrl.dumpPopulation();
   JinsightCtrl.dumpReferences();

The Jinsight 2.1 calls are:

 (you must explicitly use the import and the load statement before the calls)
   import com.ibm.jinsight.tracing.*;       // in file jintrace.jar, 06/19/2001 or later
   System.loadLibrary("jinsightPA");        // required
   int JinsightCtrl.startTracingMethods();  // tracing continues until you stop it
   int JinsightCtrl.stopTracingMethods();
   int JinsightCtrl.dumpPopulation();
   int JinsightCtrl.dumpReferences();
   int JinsightCtrl.forceGc();
   int JinsightCtrl.quit();                 // ends all tracing; closes trace file

• For WebSphere 3.5 and Jinsight2.1, use the TraceControlServlet named jintrace, and see the appropriate section of the Quick Guide for:

      Configuration and Tracing on AIX or Windows  
      Configuration and Tracing on OS/390  
  

  
  For WebSphere 3.0.2 and Jinsight2.0, see the corresponding sections in the Jinsight2.0 documentation.

 
• See "Creating a Program Trace" and "Tracing Tips" in the Jinsight Reference Manual for more details.

 
• Also see Creating smaller traces and Working with large traces in the Jinsight How-To Guide.

 

The remarks here pertain to Jinsight 2.0, with its instrumented JVM.

First try your program with the original uninstrumented JVM. Often renaming your DLLs may work if it is a load that is failing.

Details:
 

• On Windows, if the Jinsight instrumented VM (java_g.exe) is unable to load a particular DLL, say foo.dll, try copying that dll to foo_g.dll. When an application is started with java_g.exe (rather than the usual java.exe), sometimes the _g suffix is needed in a DLL name.

 
• Occasionally the java_g instrumented JVM program on Windows can fail with an error such as

   Fatal error: 0
   Assertion failed: !exceptionOccurred(EE()),
      file ..\..\..\..\src\win32\sun\windows\awt_Frame.cpp, line 155
   abnormal program termination

• When Jinsight's java_g fails, the vanilla java_g (uninstrumented JDK 1.1.8) may also fail.  The user should first try re-running this program with the vanilla java_g.
• Note that the trace collected up to the point of failure can still be visualized.
• Please alert the Jinsight developers (at jinsight@us.ibm.com) if you are unable to get past such an "assertion" failure; we may be able to help by bypassing it.

for Jinsight2.1: The default trace file name is trace.trc. You should ensure that you used the option -XrunjinsightPA on the Java 2 invocation (for example in the command file jinsight_trace, and that you employed one of the tracing controls (console command, env variable, API call) that would result in a trace being written.

for Jinsight2.0: The command file jinsight_trace should run the instrumented java_g.exe program (for Windows) or the instrumented java program (for AIX or OS/390), and should set the environment variable JINSIGHT to YES.

for Jinsight2.0, to turn tracing on, you can use one of several methods:

• set the JINSIGHT_TRACE_METHODS environment variable to YES
• supply the -tracemethods option to jinsight_trace
• call the following method in your program:

  Runtime.getRuntime().traceMethodCalls(true)

Any of the above methods should produce a trace file in the directory where jinsight_trace was run.
 

This probably means you are trying to read a newer trace format but are using an older version of the Jinsight visualizer. For example, the instrumented JVMs in Jinsight version 2.0 write traces with a header that indicates trace format version 2. The profiling agent in Jinsight version 2.1 writes a trace with a header that indicates trace format version 4. The solution is to use the latest version of the visualizer (the Jinsight2.1 visualizer) to read traces.
 

This will likely be accompanied by the Workspace Window failing to show the total number of events. A properly completed trace normally records the total number of events. The Workspace Window uses this information to show progress as it loads the trace:

27% of 10855 events read

2000 events read

To ensure a complete trace, terminate your program as follows: type Ctrl-Break, type q and press Enter.
 

No views are visible initially. You must open each view by choosing it in the Workspace Window's Views menu (for example, choose Histogram=>Objects for the Object Histogram view).