Creating a Program Trace

Jinsight Reference Manual

Creating a Program Trace

Object References· Partial Tracing· Applets· WebSphere· Servlets· Summary

Before you can visualize a program's execution, you must have a trace file. The trace file (or "trace" for short) records what goes on during a program's execution. Jinsight relies on this information to produce visualizations of the execution. Each execution may generate one trace; a trace does not record information for multiple executions.

Prior to producing a trace, have a look at the Tracing Tips section of the manual, since traces can grow very rapidly unless you focus your trace collection efforts. In particular, avoid using the -tracemethods option or the JINSIGHT_TRACE_METHODS environment variable for entire program runs, because the trace produced can be very large.

To create a trace, you can run your program using the command file jinsight_trace. This will invoke the Jinsight instrumented tracing VM (java_g for Windows, or java for AIX and OS/390) with appropriate settings. For example, on a short program, such as the sample Java program tinySamp provided, you could try

        set CLASSPATH=<path where your program is>
        jinsight_trace  -tracemethods   yourProgram   yourProgramArgs

jinsight_trace will invoke the instrumented java_g or java program, and produce a message like:

*******************************************************
Copyright (c) 1995-1996 Sun MicroSystems, Inc.
Improvements to this JVM are Licensed Materials - Property of IBM
Copyright (c) IBM Corp. 1998-2001
IBM is a Trademark of International Business Machines

Unsupported Jinsight 2001xxxx JVM with instrumented java, based on
IBM build a118-20000411; Use under terms of IBM alphaWorks agreement

env var JINSIGHT is set, enabling Jinsight options
use -tracemethods option to generate Jinsight trace
use CTRL-\ for tracing options
*******************************************************
tracefile: yourProgram.trc

A trace file yourprogram.trc will be created as yourprogram runs.

You can specify additional Java and Jinsight options as follows:

    set CLASSPATH=<path where your program is>
    jinsight_trace  <Java and Jinsight options>   yourProgram   yourProgramArgs

The command file jinsight_trace may have the -classpath option built in, so specify your class path as an environment variable, not as a command line option. You can edit the command file to adapt it for your environment. On Windows it looks like this (final 4 lines are one line):

    set JINSIGHT=YES
    set JINSIGHT_JDK=c:\jinsight2.0\n118p-2.0
    %JINSIGHT_JDK%\bin\java_g -Djava.compiler=off 
      -classpath %JINSIGHT_JDK%\lib\classes.zip;
      %JINSIGHT_JDK%\lib\jintrace.jar;.;%CLASSPATH% 
      %1 %2 %3 %4 %5 %6 %7 %8 %9

On AIX the command file looks like this (final 4 lines are one line):

    export JINSIGHT=YES
    export JINSIGHT_JDK=~/jinsight2.0/a118-2.0
    {JINSIGHT_JDK}/bin/java -Djava.compiler=off 
      -classpath {JINSIGHT_JDK}/lib/classes.zip:
      {JINSIGHT_JDK}/lib/jintrace.jar:.:$CLASSPATH 
      "$@"

The command file invokes java or java_g (the instrumented VM) with the -classpath option set for the Jinsight instrumented VM you installed. It sets the JINSIGHT environment variable to enable Jinsight instrumentation in the VM.

You can also invoke java or java_g directly, as long as the JINSIGHT environment variable is set (to any value), and your PATH and CLASSPATH settings specify the locations of the instrumentation and your program.

Taking a Snapshot of the Memory Heap

By default, a Jinsight trace stores control flow information — object creations, method and constructor calls and returns, in order, along with identifiers for their receivers. It does not store the content of objects. Tracing control flow information is costly enough as it is, especially for long-running programs, whose trace files can run into the hundreds of megabytes. Tracing the contents of all objects at all times would be prohibitive, since it would require recording every load into memory.

However, you can take a snapshot of the entire object population, or of the entire object population and the objects' mutual references at a point in the program's execution. The information in the snapshot will let you visualize the object population in the Histogram view (without tracing the full execution) or the object references in the Histogram view and the Reference Pattern view (the latter being useless without a snapshot). A snapshot will only report the objects that are not garbage collectible. Notice that the current version of Jinsight only reports arrays when taking a snapshot, it doesn't report arrays when tracing with -tracemethodsor -tracepopulation.

You may forgo tracing method calls entirely, thereby making the trace much more compact, and start your program without any tracing options:

set CLASSPATH=<path where your program is>
jinsight_trace yourProgram yourProgramArgs

To take a snapshot of all objects, or the objects and their references during an execution:

Type (for Windows) Ctrl-Break or (for AIX) Ctrl-\ on the command line you started Jinsight from. You will see a prompt:

trace:yourprogram.trc, Tracing status: CORE
-----------------------------------------------
Jinsight Tracing Options:

[tm]          - start tracing methods
[sm]          - stop tracing methods
[tp]          - start tracing population events
[sp]          - stop tracing population events
[S]           - stop tracing
[g]           - force synchronous garbage collection
[dp]          - dump a generation's population
[dr]          - dump a generation's references
[ps]          - print system state 
[q]           - quit program

[u <string>]  - user event

[<Enter>]     - exit command handler
-----------------------------------------------
>

If you want just the current object population, type dp and hit the Enter key. If you want the objects and their mutual references, type dr and hit the Enter key.
Either hit the Enter key again (to exit the Command Handler) or type q to quit the program.

There is also a programmatic interface which allows you to take memory snapshots under the control of your Java program. To use this interface,
run your program using the Jinsight instrumented tracing VM as described above, with the additional file <instrumented VM path>/lib/jintrace.jar
added to the CLASSPATH. To take a snapshot of memory under the control of your program, use either of the following calls:

  import com.ibm.jinsight.tracing;
  JinsightCtrl.dumpPopulation(); // Dump object population
  JinsightCtrl.dumpReferences(); // Dump object pop & refs

Partial Tracing

It is possible to make a trace of only part of a program's execution. You can do that simply by turning tracing off when there's nothing of interest to record, and turning it back on when there is. You can turn tracing on or off automatically (under program control) or manually from the Jinsight command line window. Either way, you should start java or java_g without the -tracemethods flag if you don't want to trace from the beginning:

     set CLASSPATH=<path where your program is>

     jinsight_trace  yourProgram   yourProgramArgs

To turn tracing on or off from within your program, use the following code:

import java.lang.Runtime;

Runtime.getRuntime().traceMethodCalls(true);  // turns tracing on
Runtime.getRuntime().traceMethodCalls(false); // turns tracing off

To turn tracing on from the command line window:

Type (for Windows) Ctrl-Break or (for AIX) Ctrl-\ to get the > prompt:
Type tm (trace methods) or tp (trace population) and then Enter to start tracing immediately.

The tp command traces only the creation and garbage collection of objects.

To turn tracing off:

Type (for Windows) Ctrl-Break or (for AIX) Ctrl-\
Type sm (stop methods) or sp (stop population) and then Enter.

Tracing Applets

The Jinsight instrumented JDK VM can be used to trace Java applets as well as applications. The same command line options apply for applets, but each command line option must be preceded by a -J (with no intervening space). For example:

     set CLASSPATH=<path for your instrumented VM>;<path where your program is>

appletviewer_g -J-tracemethods -J-trace:yourtrace.trc yourapplet

(no space between -J and -tracemethods, -J and -trace).

Configuring WebSphere 3.0.2 with Jinsight on Windows

To trace servlets and other server-side activity using Jinsight on Windows, set up WebSphere 3.0.2 to use the Jinsight JDK instrumentation for the particular managed server(s) you wish to trace. The following guidelines apply to the IBM WebSphere 3.0.2 Application Server on Windows, installed, for example, in directory C:\WebSphere\AppServer. Similar techniques may apply to other servers.

The basic approach to configuring WebSphere will be to use the Jinsight instrumented JVM only for the managed server(s) to be traced.

  install Jinsight2.0
  make a copy of the WebSphere 3.0.2 standard JDK
  populate the copied JDK with Jinsight java_g instrumentation files
  set up WebSphere to control use of Jinsight instrumentation

In this section, these directory and server names are used:

   C:\WebSphere\AppServer -- the directory containing WebSphere 3.0.2
   C:\SQLLIB -- the directory containing DB2
   C:\jinsight2.0 -- the directory containing Jinsight 2.0
   C:\WebSphereJDK -- the directory containing the WebSphere 3.0.2 jdk
   C:\WebSphereJDKcopy -- the copied WebSphere 3.0.2 jdk to be instrumented
   Default Server -- a sample WebSphere managed server to be traced

Download Jinsight for Windows: You should start by downloading the file jinsight2.0-ibm-win-1.1.8-install.exe from the IBM alphaWorks Jinsight site. Installing this version creates a C:\jinsight2.0 directory, where 2.0 is the Jinsight version and release. Inside this directory, a subdirectory n118p-2.0 is created. This subdirectory contains the Jinsight JDK instrumentation files.
Prepare to use the Jinsight java_g Instrumentation
- For the WebSphere managed server that you want to trace, copy any native .dll files in that application to correspondingly named .dll files with suffix _g appended. For example, copy file xyz.dll to file xyz_g.dll.
- In the DB2 directory SQLLIB\bin, copy the file db2jdbc.dll to file db2jdbc_g.dll
  Make sure this copy is done AFTER installation of any DB2 fix packs.
Make a copy of WebSphere Standard JDK
Copy the WebSphere standard JDK into another directory, say WebSphereJDKcopy. Into this copy we will replace some files with Jinsight JDK instrumentation.
Populate the WebSphere JDK copy with Jinsight java_g Instrumentation
Copy from jinsight2.0\n118p-2.0 to the WebSphere JDK copy WebSphereJDKcopy directory the following:
- everything in bin
- everything in lib except classes.zip
Modify the WebSphere admin.config file: Edit the file
```
   C:\WebSphere\AppServer\bin\admin.config
```
Edit the classpath line that starts with com.ibm.ejs.sm.adminserver.classpath as follows: To the end of the classpath, add
```
   ;C:/jinsight2.0/n118p-2.0/lib/jintrace.jar
```
Furthermore, if your WebSphere 3.0.2 version is prior to 3.0.2.3, then make the following additional change: To the beginning of the classpath, add
```
   C:/jinsight2.0/was3.0.2-select-jvm.jar;
```
Alternatively, if you start up the WebSphere 3 admin server from a batch file, add

;C:/jinsight2.0/n118p-2.0/lib/jintrace.jar
to the end of the classpath in that batch file; for example, in file

C:\WebSphere\AppServer\bin\debug\adminserver.bat,
and if your WebSphere 3.0.2 is prior to 3.0.2.3, add to the beginning of that classpath

C:/jinsight2.0/was3.0.2-select-jvm.jar;

The reason for adding the reference to the jintrace.jar library here instead of adding the library itself to the servlets directory is that the Jinsight TraceControlservlet makes native calls for some of its functions.
Activate WebSphere's Admin Server and Admin Client: Start the WebSphere Admin Server; then start the WebSphere admin client console program.
Stop the WebSphere managed server that you want to trace (for example: Default Server). It may already be stopped.
Modify the environment variables of that managed server
- Click on the managed server name (for example: Default Server)
- Click on "Environment.." which should cause the "Property Editor Environment" window to appear.
- Add the following variable names and values:
```
JINSIGHT=YES
JINSIGHT_TRACEFILE_NAME=\jinsight2.0\jinsight.trc
EXECUTE=YES
EXECUTABLE=C:\WebSphereJDK\bin\java_g.exe
```
- Click on the Apply button.
  Note: The trace information will be written into the C:\jinsight2.0 directory in the above example; you may instead substitute another location where you want the trace file to be written. The directory you specify for the trace must exist and have write access permission.
Register the Jinsight servlet with the managed server (for example: Default Server):
From the admin client:
- select Topology
- open (under your node) DefaultServer, servletEngine
- right-click on default_app, and select create->servlet
- fill in:
  - Servlet name: jintrace
  - Servlet Class Name: com.ibm.jinsight.tracing.TraceControlServlet
  - add to the web path list: servlet/jintrace
- Click on the Create button
Start the managed server (for example: Default Server).
Jinsight tracing is active if after starting the managed server, a new jinsight.trc file is being written in the C:\jinsight2.0 directory.

To make a trace while WebSphere is running under Jinsight instrumentation, open the trace control interface file jintrace.htm in a browser. This file is distributed in directory jinsight2.0. The browser can be on a different machine. Fill in the WAS server name (possibly qualified by the application name). Let your application run to the point you want to trace, and then press the trace control buttons Start, Stop, DumpPopulation, etc. Detailed directions are in the section Tracing Servlets.

If you didn't specify a location for the trace file, the trace will be inC:\winnt\system32\com_ibm_ejs_sm_server_ManagedServer.trc by default. After tracing, copy it somewhere else so it doesn't get overwritten the next time you run. You can also specify a trace filename using -trace:filename on the VM command line for the default server.

Configuring WebSphere 3.0.2 with Jinsight on AIX

To trace servlets and other server-side activity using Jinsight on AIX, set up WebSphere 3.0.2 to use the Jinsight JDK instrumentation for the particular managed server(s) you wish to trace. The following guidelines apply to the IBM WebSphere 3.0.2 Application Server on AIX, installed, for example, in directory /usr/IBMWebAS. Similar techniques may apply to other servers.

The basic approach to configuring WebSphere will be to use the Jinsight instrumented JVM only for the managed server(s) to be traced.

     Install Jinsight2.0
     Set up WebSphere to control use of Jinsight instrumentation

In this section, these directory and server names are used:

   /usr/IBMWebAS -- the directory containing WebSphere 3.0.2
   /usr/jinsight2.0 -- the directory containing Jinsight 2.0
   /usr/jdk_base -- the directory containing the standard JDK
   Default Server -- a sample WebSphere managed server to be traced

Download Jinsight for AIX: You should start by downloading the file jinsight2.0-aix-1.1.8.tar.Z from the IBM alphaWorks Jinsight site. Uncompress the tar.Z file, move it to where you want to expand it (e.g. the usr directory), and expand the .tar file:
```
uncompress  jinsight2.0-aix-1.1.8.tar.Z
mv          jinsight2.0-aix-1.1.8.tar   /usr
cd   /usr
tar   xvf   jinsight2.0-aix-1.1.8.tar
```
This will create a /usr/jinsight2.0 directory, where 2.0 is the Jinsight version and release. Inside this directory, a subdirectory a118-2.0 is created. This subdirectory contains the instrumented JDK.
Modify the WebSphere admin.config file: Find the admin.config file in /usr/IBMWebAS/bin. Edit the classpath line that starts with com.ibm.ejs.sm.adminserver.classpath as follows: To the end of the classpath, add
```
   :/usr/jinsight2.0/a118-2.0/lib/jintrace.jar
```
Furthermore, if your WebSphere 3.0.2 version is prior to 3.0.2.3, then make the following additional change: To the beginning of the classpath, add
```
   /usr/jinsight2.0/was3.0.2-select-jvm.jar:
```

Activate WebSphere's Admin Server and Admin Client:

cd /usr/IBMWebAS/bin
./startupServer.sh  &
   (wait until the admin server is ready)
./adminclient.sh  &

Stop the WebSphere managed server that you want to trace (for example: DefaultServer). It may already be stopped.
Modify the environment variables of that managed server
- Click on the managed server name (for example: Default Server)
- Click on "Environment.." which should cause the "Property Editor Environment" window to appear.
- Add the following variable names and values:
```
JINSIGHT=YES
JINSIGHT_TRACEFILE_NAME=/usr/jinsight2.0/jinsight.trc
EXECUTE=YES
EXECUTABLE=/usr/jinsight2.0/a118-2.0/bin/java
```
- Click on the Apply button.
  Note: The trace information will be written into the /usr/jinsight2.0 directory in the above example; you can specify a different location for the trace. The directory you specify for the trace must exist and have write access permission.
Register the Jinsight servlet with the managed server:
- Expand the managed server (for example: Default Server)
- Expand servletEngine
- Right click on default_app
- Click on Create
- Click on Servlet
- Place the following values in the "Create Servlet" window:
  
  Servlet Name: jintrace
  Description: Trace Control Servlet
  Servlet Class Name: com.ibm.jinsight.tracing.TraceControlServlet
- Click on Add button
- Place the following values in the "Add Web Path to Servlet" window
  
  Servlet Path: servlet/jintrace
- Click on Create button
Start the managed server (for example: Default Server).
Jinsight tracing is active if after starting the AppServer, a new jinsight.trc file is being written in the /usr/jinsight2.0 directory.

To control tracing while a WebSphere managed server is running under Jinsight instrumentation, open the trace control interface file jintrace.htm in a browser. This file is distributed in directory jinsight2.0. The browser can be on a different machine. Fill in the WAS server name (possibly qualified by the managed server name). Let your managed server application run to the point you want to trace, and then press the trace control buttons Start, Stop, DumpPopulation, etc. Detailed directions are in the section Tracing Servlets.

The trace file you create should be in file /usr/jinsight2.0/jinsight.trc if that is what you specified above with the JINSIGHT_TRACEFILE_NAME environment variable. After tracing, copy it somewhere else so it doesn't get overwritten the next time you run.

Tracing Servlets

Tracing parts of your application:
Jinsight comes with an HTML user interface jintrace.htm which you can use to control the trace control servlet remotely.   You can find this file in the root directory of the Jinsight installation. With WebSphere Application Server running under the instrumented Jinsight Java VM, open file jintrace.htm in any browser that supports JavaScript (e.g. Netscape 3.0 or later), and enter the server name.
Try clicking first on the button Stop tracing methods, to insure that the Jinsight tracing control servlet is loaded and is operating. You should see a confirmation that the request was executed. Use the "Back" key on the browser to return, to issue another trace control request. Let your WebSphere application run to the spot that you want to trace. Use the HTML form to start and stop tracing of methods. Make sure you trace only the sections you need, since the trace files grow very quickly.

If you need to call the trace control servlet directly without using the HTML interface, the usage is as follows, where server is the server name running WebSphere Application Server:
   http://server/servlet/jintrace?command=tm    - start/resume tracing methods
   http://server/servlet/jintrace?command=sm    - stop tracing methods
   http://server/servlet/jintrace?command=dp    - dump object population
   http://server/servlet/jintrace?command=dr    - dump object population and references
Each command returns an HTML document with a status confirmation.
As an alternative to using the HTML user interface, your server-side Java program can instead use the programmatic interface functions
   Runtime.getRuntime().traceMethodCalls(true)
   Runtime.getRuntime().traceMethodCalls(false)
   com.ibm.jinsight.tracing.JinsightCtrl.dumpPopulation()
   com.ibm.jinsight.tracing.JinsightCtrl.dumpReferences()
to start and stop Jinsight method tracing and to dump objects and references.
When you have finished tracing, although it's not absolutely essential, it's a good idea to stop the managed server(s) you were tracing, so that the trace file(s) get completely written out. You can do this from the WebSphere Adminstrator's Console.
- For Windows, the trace files, one for each managed server you were tracing, will be found in the directory where WebSphere executes, unless you explicitly specified a location for them. The default is C:\winnt\system32. The trace file names end with .trc and typically begin with com_ibm_.
- For AIX, the trace files, one for each managed server you were tracing, will be found in the directory you specified. The trace file names end with .trc and typically begin with com_ibm_.

Summary of Commands and Options

At the > prompt, obtained by typing Ctrl-Break wherever you started java (AIX, 390), java_g (NT), appletviewer_g or jinsight_trace. That lets you issue tracing commands and change tracing options during execution.

In an environment variable.

As an argument to jinsight_trace, java (AIX, 390) or java_g (NT).

In the program itself.

In the HTML interface to a trace control servlet under an application server such as WebSphere.

Tracing options
	Ctrl-Brk prompt	environment variable	java_g argument	Java program	servlet HTML interface button
enable Jinsight		JINSIGHT=anyvalue (e.g. YES)
trace file name		JINSIGHT_TRACEFILE_NAME= <filename>	-trace:<filename>
trace methods	tm	JINSIGHT_TRACE_METHODS=anyvalue	-tracemethods	Runtime.getRuntime(). traceMethodCalls(true)	Start tracing methods
stop tracing methods	sm			Runtime.getRuntime(). traceMethodCalls(false)	Stop tracing methods
trace population	tp	JINSIGHT_TRACE_POPULATION=anyvalue	-tracepopulation
stop tracing population	sp
stop (all) tracing	S
dump population	dp			com.ibm.jinsight.tracing. JinsightCtrl.dumpPopulation()	Dump objects
dump population+refs	dr			com.ibm.jinsight.tracing. JinsightCtrl.dumpReferences()	Dump objects & references
exit ctrlbrk handler	<RET>
quit program	q
force garbage collection	g
user event	u <string>
buffer size		JINSIGHT_BUFFERSIZE=size
print system state	ps

enable Jinsight tracing must be defined to generate traces; otherwise java_g behaves as though it were uninstrumented.

trace file name specifies the file name for the trace. If a path name is specified along with the trace filename, that path must already exist.

trace methods turns on tracing of methods, as well as of the creation and garbage collection of objects. When used as an argument to java_g, tracing of methods begins immediately.

trace population turns on tracing only of the creation and garbage collection of objects. When used as an argument to java_g, tracing of object population begins immediately.

stop tracing methods turns off method tracing.

stop tracing population turns off object population tracing.

stop (all) tracing turns off any tracing that was in effect.

dump population writes a snapshot of all non-garbage-collectible objects into the trace file.

dump population and refs writes a snapshot of all non-garbage-collectible objects into the trace file, along with all the references among them.

exit ctrlbrk handler exits the Command Handler.

quit program exits the Command Handler and ends the application program.

force garbage collection induces a garbage collection.

user event inserts user-specified text into the trace. The Execution view and other time-based views will display this text at the corresponding time position in the view. Use it to call out significant events or stages in the program's execution. For example, you might enter "about to open dialog box" just before you open a dialog box.
buffer size specifies the size of the internal buffer of events in bytes. The default is 64K bytes.

print system state prints the current system state (thread dump and monitor state) of the instrumented tracing VM, to assist us in debugging anomalous tracing behavior.

Jinsight Reference Manual

Jinsight Home

Tracing Tips