How do I use PerformanceMonster?

When started, PerformanceMonster starts to listen for messages from PerformanceMonster-enabled applications. By default, PerformanceMonster listens on port 4446, but you can change that by editing "performancemonster.sh" (Unix/Linux) or "performancemonster.bat" (Windows).

So, how do you PerformanceMonster-enable your application? In fact, there are currently 3 ways to do that, which are all listed below. Whichever way you choose, the end result is that performance-critical parts of your code can send log messages to PerformanceMonster, which can then analyze the log messages and give you visual feedback for further analysys.

Instrument your code

Instrument your code using MonsterLogger

One way to instrument your code is to use the class "performancemonster.MonsterLogger" which comes with PerformanceMonster. It is part of the "performancemonster-log4j.jar" file, so remember to put it in the class path when running your application. Simply surround performance-critical code like this:

MonsterLogger.begin("Category1", "myMethod");
try {
   // ...do something expensive...
} finally {
   MonsterLogger.end("Category1", "myMethod");
}

When you then run your program, give it the argument "-DPerformanceMonster.LogEnabled=true". Your program will then send messages to PerformanceMonster through the begin and end methods shown above. You can control the logging by giving these parameters to your application:

• -DPerformanceMonster.LogEnabled: "true" or "false", enabling or disabling logging. Default: false.
• -DPerformanceMonster.HostName: Machine to which the log messages will be sent. Default: localhost.
• -DPerformanceMonster.Port: The port on "RemoteHost" to which the log messages will be sent. Default: 4446.

Instrument your code using Log4J

PerformanceMonster includes a Log4J appender called "performancemonster.loghandler.MonsterAppender". It is part of the "performancemonster-log4j.jar" file, so remember to put it in the class path when running your application. Its default behaviour can be changed by altering attributes of the appender:

• RemoteHost: Machine to which the log messages will be sent. Default: localhost.
• Port: The port on "RemoteHost" to which the log messages will be sent. Default: 4446.

When using the appender, you should set up separate log categories for your performance monitoring. Then you can run your program without the performance monitoring active, so that your program will not try to send log messages to a PerformanceMonster instance. When you run a performance monitoring session, simply alter your Log4J setup.

Surround performance-critical parts of your code (such as server calls, runs through huge arrays, etc.) with Log4J logging, a message starting with "BEGIN" before the code and "END" after:

logger.debug("BEGIN myMethod");
try {
   // ...do something expensive...
} finally {
   logger.debug("END myMethod");
}

Automatically instrumenting your code

You can also use the instrumentation GUI in PerformanceMonster to instrument your code on-the-fly. This requires that your program uses Java 5. For this to work, you need to specify these extra arguments when starting your program:

-javaagent:(perfmonsterhome)/performancemonster.jar=port:4000

Furthermore, when starting PerformanceMonster, you have to supply the .jar files of your application using the "-instrumentpath" argument. Add the following to the last line of "performancemonster.sh" (Unix/Linux) or "performancemonster.bat" (Windows):

-instrumentpath my-jar-file.jar

Using the instrumentation GUI in PerformanceMonster, you can then connect to your program and simply specify in PerformanceMonster what to instrument.

Run your program

PerformanceMonster will now visualise how the performance-critical parts of the application are called. With no doubt, you will get shocked and ask yourself why your application behaves that way.

Simply by clicking on the bars shown by PerformanceMonster, you will be shown the complete stack trace from the associated call. Now just look up that dubious line of code, fix it.