Jinsight Frequently Asked Questions

Once you've installed Jinsight, by running the installation program you download from IBM alphaWorks, click on the entry Jinsight Visualizer in the Jinsight2.0 Program Folder. 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.0\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.0\traces.

 

The documentation is in HTML files in the download package.

The installation provides a program folder for the directory jinsight2.0 and also HTML documentation in the directory jinsight2.0\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 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 -mx or -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 -mx or -Xmx option. At the same time, set the JINSIGHT_MAXHEAP variable in the jinsight_trace 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  -mx230M  -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, which invokes the self-contained Jinsight instrumented tracing VM for JDK 1.1.8. The instrumented tracing VM is installed in either directory n118p-2.0 (on Windows), or directory a118-2.0 (on AIX).

Details:

 
• Install Jinsight for your platform, by running the installation program you download from IBM alphaWorks.
• Enter jinsight_trace to see the available Java options for Jinsight.
• Set the CLASSPATH environment variable to the location of your program.

set CLASSPATH=<path where your program is>

• Invoke your program as follows:

jinsight_trace  -tracemethods  yourProgram  yourProgramArgs

This will begin writing the trace file yourprogram.trc. Note that using option -tracemethods can produce a very large trace if your program is long-running. (Try this first with the sample programs provided.)
• End the tracing of your program cleanly, so that the entire trace will be written out. Either use a Jinsight instrumentation option 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.

 

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

 
• an invocation option to jinsight_trace
• a Jinsight tracing console command
• an environment variable
• a Java program method call
• For WebSphere, the TraceControlServlet

Details:

 
• 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
    ps                print system state
    q                 quit program

• 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 Java Runtime methods provide these options:

Runtime.getRuntime().traceMethodCalls(false)   turn off tracing of methods 
Runtime.getRuntime().traceMethodCalls(true)    turn on tracing of methods

• For WebSphere, read about the TraceControlServlet installation and usage.

 
• 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.

 

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.

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.

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 solution is to use the latest version of the 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).