I'm a software architect/consultant in Boulder, Colorado. I started blogging at: http://wayne-adams.blogspot.com/, but have since started the new blog, Data Sceintist in Training which will cover the areas I am learning as part of my own "big data" training, including the Hadoop family, frameworks like OpenStack, the R programming language, column-oriented databases and the art of examining data sets for useful patterns. The original blog will be kept alive with Java-specific posts. Wayne is a DZone MVB and is not an employee of DZone and has posted 35 posts at DZone. You can read more from them at their website. View Full User Profile

Java Profiling with MonkeyWrench

  • submit to reddit

Launching MonkeyWrench

The MonkeyWrench can be run in two modes:

  1. Set up to launch at the same time that the target application launches;
  2. Launched by attaching to a running target (Java HotSpot JVMs only)
The instructions are fairly different for the two approaches, so they each get a dedicated section.

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


if you downloaded the binaries. Note that the full path to the MonkeyWrench jar file is required. The MonkeyWrench GUI will launch when you launch your target application. Figure 1 shows the MonkeyWrench GUI at launch time.

Figure 1 -- The MonkeyWrench GUI

Attaching MonkeyWrench to an already‐running target application:

There are a couple of ways provided to attach to a running target. 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 step 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. You can open the MonkeyWrench jar file and edit this entry directly, then replace the manifest file, or you can use the included script named (somewhat grandiosely) installer.bat. Edit the file and put in the paths to your JDK and Javassist deployment, and it will update the MonkeyWrench jar file for you.

The two ways to attach to a running target are to 1) launch the MonkeyWrench’s main() method, which will attach to a running JVM, or 2) use the MonkeyWrench launcher GUI, which makes things a little easier.

See the included 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 that you can use jps to list all Java processes. In the script, note the following:

  • The classpath must include the MonkeyWrench jar file, tools.jar and javassist.jar.
  • 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 path must be a full path.
  • The second command‐line argument to the MonkeyWrench main() method, and the one and only command‐line argument passed to the example script, is the process ID of the target application.

When you attach to the 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 (see Figure 2). 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 (note: the launcher does not need to know about Javassist, but MonkeyWrench still does; MonkeyWrench will find Javassist by looking at the Boot-Class-Path entry in its manifest). Once you have started the launch, it will maintain an up‐to‐date list of all running Java applications on the system; double‐click on an entry for a JVM and the MonkeyWrench GUI will launch.

Figure 2 -- The MonkeyWrench Launcher

Published at DZone with permission of Wayne Adams, author and DZone MVB.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)



Bhabho Sharma replied on Thu, 2010/02/11 - 1:43am

Felt motivated reading this. I am a Java developer and i am very eager to create some new, innovative application some day. That is why i am going to attend Sun Tech Days 2010 conference in Hyderabad. Experts are going to share ideas on new technologies there. lets see what happens.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.