MonkeyWrench 
4 December 2009
Gorilla Logic, Inc.

MonkeyWrench is a Java 6 application.  While your target application may need to run in an older JVM, that's fine, but you will need to run it in Java 6 to profile it with MonkeyWrench.  It is possible for some pre-Java-6 applications to not run under Java 6, of course, based on choices made during their development.  In those cases, it may make sense to choose a different profiler.

Build instructions are included here first.  If you just want to use the MonkeyWrench binaries, skip to "Running MonkeyWrench".

1) Building MonkeyWrench

One thing that will make deployment simpler is, before you build, to download Javassist (see http://sourceforge.net/projects/jboss/files/Javassist/ and download the latest version) and edit the following file:

$MonkeyWrenchHome/src/main/resources/META-INF/MANIFEST.MF

The Boot-Class-Path attribute in the manifest is what tells target applications where to find the JDK's "tools.jar" and Javassist's "javassist.jar" files when you attach to a running application.  Edit this entry to reflect the locations of these two jar files in your project.

MonkeyWrench is supplied as a Maven-2 project.  The smartest thing to do first is simply unzip it, ensure Maven is in your path (you'll need to set the M2 and M2_HOME environment variables, too), and enter "mvn clean install."  The Maven pom file has dependencies on the JDK's "tools.jar" file and the Javassist "javassist.jar" file.  MonkeyWrench's use of the Javassist package is simple enough that you should be ok with any version of Javassist; the Maven pom file references 3.11.

In order for Maven to handle the dependency on the JDK's "tools.jar" file, it needs the environment variable "java.home".  You can ensure that is set to a JDK home or hard-code it into the pom file.

If you have problems with the build, you may need to manually download and install some resource, likely Javassist.  If you have any experience with Maven, you won't have any trouble with this; if you are new to Maven, the error message is fairly informative.

2) Running MonkeyWrench

MonkeyWrench can be run in two modes:
  (a) Set up to launch at the same time the target application launches;
  (b) Launched by attaching to a running target (Java HotSpot JVMs only).

Instructions are fairly different for the two approaches, so they each get a dedicated section.

  (a) Launching MonkeyWrench at target application launch time

      This is the simplest way to launch the MonkeyWrench profiler.  In the launch script of your target application, supply the following argument:

        -javaagent:$MonkeyWrenchHome/target/GorillaProfiler-1.0-SNAPSHOT.jar

      if you built MonkeyWrench from source, or

        -javaagent:$MonkeyWrenchHome/monkeywrench.jar

      if you downloaded the binaries.  Note that the full path to the MonkeyWrench jar file is required.

  (b) Attaching a MonkeyWrench to an already-running target application:

      There are a couple of ways to do this.  Before you proceed, you must first correctly set the "Boot-Class-Path" attribute in the manifest file of the MonkeyWrench jar file.  The reason for this is that when you attach to a running JVM, the JVM needs to know where to find the JDK tools.jar and Javassist javassist.jar files are located.  You can open the MonkeyWrench jar file and edit this directly, replacing the manifest file, or you can use the enclosed script named (grandiosely) "installer.bat".  Edit this file and put in the paths to your JDK and Javassist deployment, and it will update the MonkeyWrench jar file for you.
      
      See the enclosed "run.bat" script for a command-line approach to starting the agent.  You'll need the JVM ID of your target.  Luckily, this is just the OS's process ID.  Don't forget you can use "jps" to list all Java processes.

      In the enclosed example script, note the following:
        1) The class path must include the MonkeyWrench jar file, tools.jar and the Javassist javassist.jar file.
        2) The first argument to the "main" method is the path to the MonkeyWrench jar file.  The classpath finds the .jar file to launch the agent, while the first command-line argument supplies the agent path to the Sun attach API.  This must be a full path.
        3) The second command-line argument to the MonkeyWrench "main" method, and the only argument to the example script, is the process ID of the target application.

      When you attach to a running application, the MonkeyWrench Swing GUI will launch and you are ready to begin profiling.

      The second way to attach to a running target is with the MonkeyWrench launcher application.  There is a sample Windows script in the distribution top-level directory called "runLauncher.bat".  Edit it as necessary to point to "tools.jar" and the MonkeyWrench jar file on your system.  Once you have started the launcher, it will maintain an up-to-date list of all running Java applications on the machine; double-click on an entry for a JVM and the MonkeyWrench GUI will launch.