Quick Guide

Jinsight Quick Guide Supplemental Info

Guided Tour

WebSphere 3.5 · WebSphere 3.5 on OS/390 · Functionality Differences · Troubleshooting

---

Configuration and Tracing with WebSphere 3.5 on AIX or Windows

• Copy the Jinsight Profiling Agent file into the appropriate WebSphere JVM directory.

     Windows: copy jinsightPA.dll    to  \WebSphere\AppServer\jdk\jre\bin 
     AIX:     copy libjinsightPA.so  to  /usr/IBMWebAS/java/jre/bin
  

• Note to former users of Jinsight2.1 betas: Undo any Jinsight modifications you made to the admin.config file for previous betas of Jinsight2.1. That is, remove (from the admin.config adminserver classpath line) the path reference to jintrace.jar.
• Activate WebSphere's Admin Server and Admin Client.
• Stop the WebSphere Application Server that you want to trace (let's assume it is the Default Server).
• Register the jintrace servlet with the Application Server you wish to trace (e.g. Default Server).
  • Expand the Application Server (for example: Default Server)
  • Expand the Servlet Engine (e.g. Default Servlet Engine)
  • Right click on a Web Application (e.g. default_app)
  • Click on Create...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, to make an entry in the Servlet Web Path List
  • Place the following values in the "Add Web Path to Servlet" window

    Servlet Path:  servlet/jintrace

  • Click on OK buttons
  • You should see the message: "Servlet.create" running ...

• Add the Jinsight Profiling Agent and the jintrace servlet to the Application Server's command line. Select the Application Server to be traced (e.g. Default Server), and add the following to its "Command line arguments" field:

     Windows:
       -XrunjinsightPA  -classpath  <JINSIGHT_HOME>\jintrace.jar
     AIX:
       -XrunjinsightPA  -Djava.compiler=NONE   
                        -classpath  <JINSIGHT_HOME>/jintrace.jar
  

  If the "Command line arguments" field already has a classpath, add the jintrace.jar entry to the front of the classpath. Make the classpath to jintrace.jar correspond to where you installed Jinsight. Note that it is necessary to reference jintrace.jar explicitly in the Application Server's classpath, because the jintrace servlet makes native calls. Click on the Apply button to run "ModifyAttributes".

  [Similarly, if you code Jinsight API calls into a servlet you want to trace, you must also add the complete path to that servlet to the Application Server's classpath.]

• Specify environment variables for this Application Server. For example, you may use the env var JINSIGHT_TRACEFILE_NAME to specify a specific directory and trace file name of your choosing. Otherwise, the default trace file name is "trace.trc" and it is written to the directory from which WebSphere runs, e.g. c:\winnt\system32 on Windows, or /usr/IBMWebAS/bin on AIX.

  To specify environment variables for an Application Server in WebSphere, click on the Application Server's Environment... button [general tab] to bring up the Environment Editor. Specify, for example,

     Windows:
       [optional]   JINSIGHT_TRACEFILE_NAME=c:\temp\mytrace.trc
     AIX:
       [optional]   JINSIGHT_TRACEFILE_NAME=/tmp/mytrace.trc
  

  Ensure that the trace file directory and path exist and are writeable by the WebSphere JVM that runs the Application Server that you want to trace. It's best to have this be a directory local to where WebSphere is running; if you are trying to write a trace to a remote directory, it may not be writeable.
  Click on OK in the Environment Editor.
  Click on the Apply button to run "ModifyAttributes".

Tracing with WebSphere 3.5 on AIX or Windows

• Start the Application Server. (e.g. Default Server).
• Start the HTML interface to the Trace Control Servlet.   That is, bring up a browser on the file <JINSIGHT_HOME>/jintrace.htm.
• Specify the Server Name field. If you are trying to trace the Default Server, and you installed the Trace Control Servlet in the Web Application named default_app, then just specify the name of the node.

  If you installed the Trace Control Servlet in another Web Application, or in another Application Server altogether, then specify the "server name" as follows:

      <node name>/<Web Application Web Path>
  

  You find the Web Application Web Path using the Admin Console, under the General Tab of the Web Application to be traced.

  For example, the case depicted below shows servlet jintrace installed in Web Application trade2_app under Application Server Trade 2 Server. If the node name is mynode, then enter mynode/trade for the Server name field.

  

• Control Application Server tracing.   The jintrace.htm Trace Control Servlet interface has six buttons.
  

  It is a good idea to select Stop tracing methods as your first command. This will cause the servlet to load before any tracing begins. After the "tracing command executed" message appears, use your browser Back function to return to the trace control screen shown above.

  By pressing the start tracing methods button you start tracing method enters/leaves. Note that trace data continues to accumulate until you press the stop tracing methods button. You can repeat start/stop as many times as you like. [You can separately monitor the trace file size as it grows.]

  Each of the buttons dump population and dump references writes a snapshot of all existing objects to the trace file. The latter also captures all references among the current object population, and writes that to the trace file. Garbage collection is automatically done as a part of these two operations, so separately specifying garbage collection is unnecessary. One use of this pair of controls is to help isolate memory leaks in Java code, by using the Reference pattern view in the Jinsight visualizer.

  The button force garbage collection is self-explanatory.

  The button end all tracing discontinues any further tracing activity, after writing out internal trace buffers and closing the trace file. You should press this button when you are completely done tracing.

• Stop the Application Server when you are finished tracing.

Visualizing the trace

When done tracing, you may wish to first copy the trace file to another location to preserve it. To visualize the trace, use the jinsight.bat file distributed with jinsight2.1, which will insure that it references the newer visualizer jinsight.jar (dated at least 07/13/2001).

Instructions for visualizing a trace are introduced in the earlier Quick Guide section on Verify Install or are covered in detail in the Reference Manual.

---

Configuration and Tracing with WebSphere 3.5 on OS/390

To prepare for collecting a Jinsight trace while running the WebSphere Application Server for OS/390 Version 3.5, you need to make the following changes to your HTTP Server and WAS configuration files:

• Prepare the HTTP server and WAS for Jinsight tracing:
1. Make the following change to your etc/httpd.envvars file:
• Set the environment variable:

JINSIGHT_TRACEFILE_NAME=/tmp/jinsight.trc

Note:  Choose any trace file name you like.  Be certain that WAS has write access to your choice of directory.  If unspecified, Jinsight will create the trace file in the webserver's current working directory, usually usr/lpp/internet/server_root, and call it trace.trc.
2. In your WebSphere/AppServer/properties/default_global.properties file, indicate that you do not want to use the JIT.

       appserver.product.java.jvmconfig.jit=off

• Configure WAS to run the Jinsight profiling agent and trace control servlet:

Modify your WebSphere was.conf file in order to enable WAS to find and execute the Jinsight2.1 profiling agent and the Jinsight2.1 TraceControlServlet.

• In order to enable WAS to find the Jinsight profiling agent, add the path to libjinsightPA.so to the appserver.libpath.

   appserver.libpath=<JINSIGHT_HOME>

• In order to enable WAS to execute the Jinsight profiling agent, add the following extra parameter referring to the libjinsightPA.so profiling agent.

   appserver.java.extraparm=-XrunjinsightPA

Note that this extra paramater specification will not work unless you have installed APAR UQ51564, which should now be a part of WebSphere 3.5 on OS/390.
• In order to enable WAS to locate the Jinsight TraceControlServlet, add jintrace.jar to the appserver.classpath.

   appserver.classpath=<JINSIGHT_HOME>/jintrace.jar

[Similarly, if you code Jinsight API calls into a servlet you want to trace, you must also add the path to that servlet to the managed server's classpath.]

• The HTML interface to the TraceControlServlet will construct a URL of the form:

   http://hostname/servlet/jintrace?command=xx

You must, therefore, add the TraceControlServlet to a web application that defines a servletmapping of  /servlet.  If, for example, you plan to include the Jinsight servlet in a web application called my_app, you should specify:

   webapp.my_app.servletmapping=/servlet

You then associate the name jintrace with the actual servlet by adding the following definition to the same web application:

   webapp.my_app.servlet.jintrace.code=com.ibm.jinsight.tracing.TraceControlServlet

• Recycle the webserver in order to enable the changes you have just made.

Tracing with WebSphere 3.5 on OS/390

• Start WebSphere 3.5
• Start the HTML interface to the Trace Control Servlet. That is, bring up a browser on the PC file jintrace.htm. Complete the Server name field by entering either the name or the IP address of your webserver. You may include a port number (separated by a colon) if your webserver uses a nonstandard port.
  

  The jintrace.htm Trace Control Servlet interface has six buttons. It is a good idea to select Stop tracing methods as your first command. This will cause the servlet to load before any tracing begins. After the "tracing command executed" message appears, use your browser Back function to return to the trace control screen shown above.

  By pressing the start tracing methods button you start tracing method enters/leaves. Note that trace data continues to accumulate until you press the stop tracing methods button. You can repeat start/stop as many times as you like. [You can separately monitor the trace file size as it grows.]

  Each of the buttons dump population and dump references writes a snapshot of all existing objects to the trace file. The latter also captures all references among the current object population, and writes that to the trace file. Garbage collection is automatically done as a part of these two operations, so separately specifying garbage collection is unnecessary. One use of this pair of controls is to help isolate memory leaks in Java code, by using the Reference pattern view in the Jinsight visualizer.

  The button force garbage collection is self-explanatory.

  The button end all tracing discontinues any further tracing activity, after writing out internal trace buffers and closing the trace file. You should press this button when you are completely done tracing.

Visualizing the trace

When done tracing, copy the trace file in binary mode to your PC. To visualize the trace, use the jinsight.bat file distributed with jinsight2.1, which will insure that it references the newer visualizer jinsight.jar (dated at least 07/13/2001).

Instructions for visualizing a trace are introduced in the earlier Quick Guide section on Verify Install or are covered in detail in the Reference Manual.

---

Some Functionality Differences from Jinsight2.0 to Jinsight2.1

API Calls:

The program calls to control tracing have changed in Jinsight 2.1. If you used this programming interface with previous versions of Jinsight, you need to revise the calls and recompile your program with the Jinsight 2.1 jintrace.jar file, and add the System.loadLibrary call before any of the tracing control program calls.

The old Jinsight 2.0 calls were:

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

The new 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

A non-zero return code from any of the calls indicates either that Jinsight tracing has already ended or that Jinsight tracing is not yet initialized. You must have the new jintrace.jar file in your classpath when executing a Java program with the new Jinsight2.1 API calls.

Partial Tracing:

If you turn method tracing off and then later turn it on again, you will see a difference in the visualizer in this version of Jinsight 2.1 compared with earlier versions of Jinsight (including the Jinsight 2.1 beta release).

In previous versions, when method tracing was turned off, we were still tracking enough information so that when method tracing resumes, we would know the time at which any methods already on the stack had been invoked.

In the current version, when tracing is turned off, it will appear as if all methods have returned at that time, and, similarly, when method tracing resumes, it will appear as if all methods active at that time had just been called. The advantage of the new approach is reduced perturbation of the application when tracing is turned off.

Additional Differences:

• The jintrace.jar and jintrace.htm files are different for Jinsight 2.1. Do not mix the Jinsight 2.0 version with the Jinsight 2.1 version of these files.
• The start and stop functions for trace object population are not implemented.
• The previous (Jinsight 2.0) environment variable JINSIGHT is no longer used.
• The trace control console function 'q' now ends tracing completely, but does not end the application itself.
• In AIX, the Ctrl-\ console interface for trace control commands does not work. Thus, to control tracing effectively on AIX, you must either use the program calls shown above, or the Trace Control Servlet in a WebSphere context.
• The trace file now is named trace.trc.

Here are tabular summaries of tracing commands and options for Jinsight 2.1, and where they differ from Jinsight 2.0:

  for Windows:  Tracing Commands and Options for Jinsight2.1 on Windows 
  for OS390:    Tracing Commands and Options for Jinsight2.1 on OS/390 
  for AIX:      Tracing Commands and Options for Jinsight2.1 on AIX 

---

Troubleshooting with Jinsight2.1

1. Problem: My Java program compiles with the following:

       import com.ibm.jinsight.tracing.*;
    and a call to
       JinsightCtrl.startTracingMethods();
   

   But when I run the program, I get:

       Exception in thread "main" 
         java.lang.UnsatisfiedLinkError: startTracingMethods
   

   Possible solution: Your program must also contain the line:

                System.loadLibrary("jinsightPA");
   

   before any calls to the trace control interface functions.

2. Problem: When I try to trace my Java program, I get a message such as:

       Can't load "jinsightPA.dll", because Can't find dependent libraries
       loadJVMHelperLib failed
       Could not create the Java virtual machine.
   

   Possible solution: Your PATH (or LIBPATH on AIX) must contain a reference to the environment variable JINSIGHT_HOME where you have installed Jinsight2.1.

3. Problem: When I load a trace in the visualizer, I get:

       java.lang.RuntimeException: invalid version in Header
   

   Possible solution: You must use the Jinsight 2.1 visualizer on Jinsight 2.1 traces.

4. Problem: The visualizer freezes for several minutes when I open a view.

   Possible solution: We have experienced this also with several of the Sun Java 2 JVMs. JVMs that avoid this problem are JDK1.1.8 (for which you also need Swing), or the IBM JRE1.3. The latter can be obtained by following a path starting from http://www.ibm.com/developerworks.java, selecting "Download Developer Kits", and working your way through "WebSphere preview technologies", "Runtime Environment Package", "Download", and a registration process.

5. Problem: The visualizer crashes with the following error:

       HotSpot Virtual Machine Error, EXCEPTION_ACCESS_VIOLATION
       Please report this error [to Sun] ...
   

   Possible solution:We have reported the error, but there is no resolution to this crash of the Sun JVM. JVMs that avoid this problem are JDK1.1.8 (for which you also need Swing), or the IBM JRE1.3. The latter can be obtained by following a path starting from http://www.ibm.com/developerworks.java, selecting "Download Developer Kits", and working your way through "WebSphere preview technologies", "Runtime Environment Package", "Download", and a registration process.

---

Quick Guide

Jinsight Home

Guided Tour