Tracing commands and options for Jinsight2.1 on Windows

Summary of Jinsight2.1 tracing commands and options for Windows

	Ctrl-Brk   prompt	environment  variable	java  argument	Java  program	servlet HTML  interface button
enable Jinsight		(no longer used)	-XrunjinsightPA   (arg is required)
trace file name		JINSIGHT_TRACEFILE_NAME=    <filename>	(no longer used)
trace methods	tm	JINSIGHT_TRACE_METHODS=   anyvalue	(no longer used)	com.ibm.jinsight.tracing. JinsightCtrl.startTracingMethods();	Start tracing methods
stop tracing methods	sm			com.ibm.jinsight.tracing. JinsightCtrl.stopTracingMethods();	Stop tracing methods
trace population	tp   (not operational)	JINSIGHT_TRACE_POPULATION=   anyvalue   (not operational)	(no longer used)
stop tracing population	sp   (not operational)
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>
end all tracing and   close trace file	q   (new meaning)			com.ibm.jinsight.tracing. JinsightCtrl.quit();	End all tracing
force garbage collection	g			com.ibm.jinsight.tracing. JinsightCtrl.forceGc();	Force garbage collection
user event	u <string>
buffer size		JINSIGHT_SEGMENT=    <decimal_number> JINSIGHT_SEGMENT_SIZE=    <hex_number>	(no longer used)
print system state   (no longer used)	(no longer used)

First you must specify    -XrunjinsightPA   as an argument to the java command, to activate the Jinsight2.1 profiling agent itself and enable Jinsight functions. Then there are four ways on Windows to specify the tracing controls:

1. At the > prompt, obtained by typing Ctrl-Break in the window where you ran jinsight_trace.bat.  That lets you issue tracing commands and change tracing options during execution.

 
2. In an environment variable.

 
3. In the program itself, as one of six API calls. For compilations, you must have the file jintrace.jar in the CLASSPATH. Also, the program must execute the line    System.loadLibrary("jinsightPA");    before making Jinsight API calls. Program execution must set PATH and CLASSPATH to include the file jintrace.jar. See the sample command file jinsight_trace.bat

 
4. In the  jintrace.htm HTML interface to the Jinsight trace control servlet under an application server such as WebSphere.

Here's what is meant by each of these tracing controls:

• enable Jinsight tracing must be defined to generate traces; in Jinsight2.1, this capability is embodied in a JVMPI profiling agent that you specify be loaded by Java 2.

 
• 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.  Tracing of methods continues until stop tracing methods is issued.

 
• trace population turns on tracing only of the creation and garbage collection of objects. .

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

 
• end all tracing and close trace file exits the Command Handler, ends all tracing (no more tracing can be restarted), and closes the trace file.

 
• force garbage collection induces a garbage collection.

 
• user event inserts user-specified text into the trace.  The visualizer 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 in bytes of the internal buffer of trace events.  The internal buffer is divided into segments. The number of segments is a decimal value between 4 and 256. The segment size is a hex value between 10000 (which is 64K) and 160000 (which is 1408K) in increments of hex 10000. The default values are 32 segments of size hex 80000 bytes each. Hence the default buffer size for trace events is 16M 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.