PerformaSure of Quest Software is a J2EE performance diagnosis tool that provides an end-to-end transaction-centric view of performance as experienced by end users. To gather profile information PerformaSure uses one or several agents deployed on the monitored systems. Since gathering profile information depends on the monitored component, three different agents are available:

  • System agent gather performance figures about the operating system.
  • Web server agents gather performance figures about a web server.
  • Application server agents gather detailed performance figures about an application server.

Since the agents are specific to each component, Quest Software clearly states which components are officially supported. For example, the current release (4.4) supports the following application servers: BEA WebLogic Server, IBM WebSphere Application Server, Oracle Application Server, JBoss Application Server and Apache Tomcat Server. Even if those are among the most commonly used, other application servers exist… For this reason PerformaSure also supports a generic agent called X-Agent. Although the X-Agent does not provide as much information as the other agents do, it might be very useful in some situations. The problem is that the documentation does not provide instructions on how to configure the it. Instead, it provides the following information:

“The X-Agent needs to be configured by Quest Consulting. For more information about customizing the X-Agent and modifying the startup sequence of the application server or standalone Java application that you want to instrument, contact your Quest sales representative.”

Ups! Not very useful…

To show you how such a configuration is performed, let me describe what I did few days ago on my Windows XP laptop to configure the X-Agent for Sun Java System Application Server 9.1 Update 2.

  • First of all, I opened a command prompt and I defined two environment variables pointing to the installation directories of Java and PerformaSure
c:\tmp>set JAVA_HOME=C:\Java\jdk\1.5.0
c:\tmp>set PERFORMASURE_HOME=C:\Java\quest\PerformaSure4.4.0
  • Then, in the same command prompt, I called the script preinstrumentor.cmd to create a JAR file that will be used during the startup of the application server
c:\tmp>call "%PERFORMASURE_HOME%\scripts\preinstrumentor.cmd" "%JAVA_HOME%"
2008-12-26 23:09:00.703 INFO  Loading Agent startup configuration from C\:Java\
  quest\PerformaSure4.4.0\config\agent.config
2008-12-26 23:09:02.031 INFO  PerformaSure 4.4 (Build PAS_440-20061024-1025) on
  Windows XP x86 5.1 using Sun Microsystems Inc. Java HotSpot(TM) Client VM
  version 1.5.0_10-b03 (extra info: mixed mode, sharing); Agent Type:
  Preinstrumentor
2008-12-26 23:09:02.062 INFO  Configured to connect to Nexus at localhost:41705
2008-12-26 23:09:02.187 INFO  Connected to Nexus at localhost:41705
2008-12-26 23:09:03.203 INFO  Agent started
2008-12-26 23:09:03.203 INFO  Creating bootstrap classes in C:\Java\quest\Perfo
  rmaSure4.4.0\scripts..bootstrapC--Java-jdk-1.5.0.jar
2008-12-26 23:09:05.796 INFO  Preinstrumentation complete
2008-12-26 23:09:05.812 INFO  Preinstrumentor Agent shutdown completed
  • The last operation I performed through the command prompt was the “generation” of two Java options (-Xbootclasspath and -javaagent) to be used in the configuration of the application server (it is not necessary to do it in this way, but with that method it’s possible to avoid annoying typos…)
C:\Tmp>call "%PERFORMASURE_HOME%\scripts\makebootstrappath.cmd" "%JAVA_HOME%"
C:\Tmp>echo -Xbootclasspath/p:"%PS_BOOTSTRAP_PATH%"
-Xbootclasspath/p:"C:\Java\quest\PerformaSure4.4.0\bootstrapC--Java-jdk-1.5.0.jar"
C:\Tmp>echo -javaagent:"%PERFORMASURE_HOME%\lib\performasure-agent.jar"
-javaagent:"C:\Java\quest\PerformaSure4.4.0\lib\performasure-agent.jar"
  • To finish the configuration I added, through the administration console of the application server, the following JVM options (click here to see an image of the relevant part of the console)
-Dperformasure.agent.appserverinfo=kalgan:Generic:SunAS9
-Dperformasure.debug=0
-Xbootclasspath/p:"C:\Java\quest\PerformaSure4.4.0\bootstrapC--Java-jdk-1.5.0.jar"
-javaagent:"C:\Java\quest\PerformaSure4.4.0\lib\performasure-agent.jar"

Notice that the value of the variable performasure.agent.appserverinfo has the following format: <server>:Generic:<version>.

After these operations I restarted the application server and, as a result, I was able to use PerformaSure to profile the applications running into the JVM of the application server.