MonkeyWrench (available at http://www.gorillalogic.com/monkeywrench) is an open-source Java profiler based on the runtime's built-in management interface and instrumentation hooks. MonkeyWrench enables you to:
- Collect CPU and wall‐clock statistics at the class constructor and method level, for the classes you select, with detailed information on the stack trace signatures and threads involved with each constructor or method;
- Monitor object creation, also with associated stack trace signatures and associated threads;
- Monitor all threads in the target application, focusing on those with the most CPU time (either in a window or cumulative); also monitor thread contention and deadlocks, all sampled at the time interval of your choice;
- Graphically monitor the real‐time behavior of the JVM garbage collectors, viewing both the number of collections, and the total time consumed collecting, also sampling at the time interval of your choice.
MonkeyWrench uses well‐defined Java APIs, and its Swing interface makes it easy to begin profiling an application. It can be launched at target launch time, or, for HotSpot JVMs, a MonkeyWrench launcher application can be used to locate and attach to already‐running JVMs. MonkeyWrench provides in one place information you'd normally need to collect from multiple applications (e.g., method CPU times, hprof‐style site summaries, and thread‐contention monitoring). Finally, since the source is available, you can customize it to provide just what you want, and only what you want, for your needs.
MonkeyWrench is available both in source and binary (.jar) form. Installation instructions will start with build instructions, and then proceed to the different ways to launch MonkeyWrench. Even if you are not building MonkeyWrench, it is recommended you read the (relatively‐short) section on building, as it will help you to better understand some of the launch dependencies you will encounter later.
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 while profiling it with MonkeyWrench. It is possible for some pre‐Java‐6 applications to not be able to 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.
One act that will make deployment simpler is to, before you build, download Javassist (see http://sourceforge.net/projects/jboss/files/Javassist and download the latest version) and edit the following file in the MonkeyWrench source tree:
The Boot‐Class‐Path attribute in the manifest 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 a Maven‐2 project. The easiest path to building it is to simply unzip it, ensure Maven is in your path, set the M2 and M2_HOME environment variables, and enter
mvn clean install
The Maven pom file has dependencies on the JDK’s tools.jar 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 version 3.11. To process the dependency on the tools.jar file, the Maven pom file needs the environment variable java.home. Note that this needs to be the JDK home (JRE is not sufficient). You can ensure that it is set to a JDK home or hard‐code the location in the pom file. If you have any problems with the build, you may need to manually download and install some resource, most 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 messages are fairly informative.
Per the usual Maven setup, the MonkeyWrench jar file will be placed in the target directory. Note that the name of the jar file is determined by properties in the pom file and can be changed.