Running Jinsight 2.1 with WebSphere 4.0

Jinsight is a JVM (Java Virtual Machine) profiler that's been available for some time from IBM's alphaWorks site. An important use of JVM profilers is with application servers. Jinsight 2.1 provides usage instructions for profiling WebSphere Application Server (WAS) 3.5. These instructions are updated for use with WAS 4.0.

These instructions are specific to WAS 4.0 on WinNT/2K. They have not been tested on AIX yet. This will happen soon. In what follows <was> refers to the WAS install directory while <jinsight> refers to the Jinsight install directory.

Please send any corrections, omissions or other recommendations to pglezen@us.ibm.com. The present set of gaps I am looking to fill is:

  1. profiling WAS 4.0 on AIX
  2. WAS single server instructions - installing Jinsight EAR will be different.
The instructions are divided into three groups:

  1. Installing Jinsight
  2. Creating a Jinsight EAR with AAT
  3. Installing the Jinsight EAR

Installing Jinsight

Installing Jinsight is simply a matter of unzipping it where ever you wish to install it. The unzip process should create a directory called jinsight2.1. This subdirectory will be henceforth refered to as <jinsight>

Copy jinsightPA.dll from <jinsight> to <was>/java/jre/bin.

Creating a Jinsight EAR

With WebSphere 4.0, one cannot just casually drop a servlet into an application server. It must be packaged as either a WAR or an EAR file. Even if you choose to package it as a WAR file, you must choose an application name anyway. So these steps create a Jinsight EAR file right from the beginning with the WebSphere Application Assembly Tool (AAT).

  1. Start up the AAT

  2. Create a new application by selecting File -> New -> Application

  3. Make sure the General tab of the EAR file is displayed. Change the Display name: to jinsight.ear. Give it any description you like.

  4. Right click on Web Modules and select New.

  5. Make sure the General tab of the web module is selected. Fill in the following fields:

    1. File name: jinsight.war
    2. Context root: jinsight
    3. Classpath: <jinsight>/jintrace.jar

    This last field is important. Do not import the jintrace.jar file into the AAT. It needs to be referenced inside its installation directory because classes in jintrace.jar contain native methods.

  6. Expand the Web Module. Right click WebComponents and select New.

  7. In the General tab fill in the following fields:

    1. Component Name: jintrace
    2. Display Name: Trace Control Servlet
    3. Select Servlet for component type
    4. Class name: com.ibm.jinsight.tracing.TraceControlServlet

  8. Right click on Servlet Mapping and select New.

    1. The Servlet entry field should already say jintrace.
    2. In the URL pattern entry field, enter servlet/jintrace. Click ok.

  9. Save the EAR file to <was>/installableApps

Installing the Jinsight EAR

The following instructions will install the Jinsight trace control servlet into the default application server.

  1. Right click on the Enterprise Applications folder of the WebSphere admin GUI and select Install Enterprise Application.

  2. Select the Install Application radial button and enter path name of the Jinsight EAR file you just created in the <was>/installableApps directory. Enter jinsight for the application name.

  3. Click Next until you reach the end of the wizard and then click Finish.

  4. Select the Default Server node in the righthand panel.

  5. In the General tab click the Environment... button. Add a property named JINSIGHT_TRACEFILE_NAME with value set to the file name of the trace file that Jinsight will generate. If this is not specified, Jinsight will place the trace in a file called jinsight.trc in the application server's working directory.

  6. Go to the JVM Settings tab.

  7. Click the Advanced JVM Settings button and add the following to the Command line arguments: field: 
    -XrunjinsightPA
    If there are already command line arguments, make sure a space separates this addition from the other contents.

    Note: Do not attempt to add a classpath entry here or anywhere else in the JVM Settings tab as you might have with WebSphere 3.5. In 4.0, this will cause the Jinsight servlet to be loaded by a classloader that does not have access to other J2EE classes (such as HTTPServlet). The proper classloader is the application classloader. That is why jintrace.jar is specified in the deployment descriptor of the Jinsight EAR file.

  8. Stop and re-start the Default Server.

  9. Regenerate the web server plugin. Right click on the node and select Regen Webserver Plugin.

Obtaining the trace

This completes the setup. Remember that Jinsight trace data accumulates very rapidly. You don't want to narrow the tracing window as much as possible. The trace control servlet is accessed by loading <jinsight>/jintrace.htm into a browser. Enter 
hostname/jinsight
in the Server name: field replacing hostname with the name of the WebSphere host. Jinsight trace commands are issued by clicking the appropriate button and pressing the browsers back-button in order to issue another command.
Version: $Revision: 1.1 $