ProfilerJ in a nutshell

Content of distribution

The distribution of profilerJ (i.e. profilerJ...zip,profilerJ...gz or profilerJ-1.4.0.msi ) consists of the following files:

com.terrasoft.jrc.agent.jar	Java agent gathering profile data either by sampling or by byte-code-instrumentation (BCI)
com.terrasoft.jrc.client.jar	Command line client, profilerJ GUI
com.terrasoft.tools.jar	Terrasoft tools library
profilerjCmd.cmd profilerjCmd.sh	Starts ProfilerJ-Console (a command line client, it is recommended to use the "ProfilerJ GUI" instead)
profilerjGUI.cmd profilerjGUI.sh	Starts ProfilerJ-Viewer (the graphical user interface)
profilerj.xml	ProfilerJ GUI options
licenseCMD.txt	The license file for profilerjCmd (royalty free)
readme.txt
profilerj.exe	Only present if installation is done by profilerJ-1.4.0.msi

Installation

Windows

Start profilerJ-1.4.1.msi and follow instructions.

Other platforms

Expand the archive profilerJ-1.4.1.zip (.gz, .tar respectively) to a directory of your choice (e.g. /var/opt/profilerj).

Deployment

Add the following statements to the startup-script of the java application you want to profile:

for Unix:

-Xbootclasspath/a:"<Installation-Path>/com.terrasoft.jrc.agent.jar" -javaagent:"<Installation-Path>/com.terrasoft.jrc.agent.jar=suspend=y"

for Windows:

-Xbootclasspath/a:"<Installation-Path>\com.terrasoft.jrc.agent.jar" -javaagent:"<Installation-Path>\com.terrasoft.jrc.agent.jar=suspend=y"

Example:

java -Xbootclasspath/a:"C:\Program Files\Terrasoft\ProfilerJ\com.terrasoft.jrc.agent.jar" -javaagent:"C:\Program Files\Terrasoft\ProfilerJ\com.terrasoft.jrc.agent.jar=suspend=n" -cp foo.jar com.terrasoft.foo

When you start your application it will pause execution until you resume it (see ProfilerJ GUI). Set "...suspend=n" if the application shouldn't stop but continue execution. To prevent the application from exiting, set waitonexit=y.

Alternatively, you can store your command-line arguments into a property file. This is extremely useful, when the command-line gets bloated:

java -Xbootclasspath/a:"...\com.terrasoft.jrc.agent.jar" -javaagent:"... \com.terrasoft.jrc.agent.jar=properties=profilerj.cfg" -cp foo.jar com.terrasoft.foo

where profilerj.cfg is a file containing command line arguments. To automatically write code coverage metrics when the application exits, the file profilerj.cfg would contain something like shown below:

agent.suspend=n
agent.snapshot=snapshot.pjs
coverage.instrument.include=com.terrasoft.*,org.*
profilerMgr.coverage=on

Take a look at agent.suspend. You probably have noticed, that this option - when defined in the command line - doesn't have the prefix "agent.". To keep the command line small, ProfilerJ adds a "agent." to every option which doesn't contain a dot (".").

To activate JMX support, you will have to add -Dcom.sun.management.jmxremote to the command line.

ProfilerJ-Console

How to create snapshots

Run profilerjCMD.cmd or (profilerjCMD.sh respectively). To gather profiling information by sampling, switch on the sampler:

> sampler on
OK

To resume a suspended application, type "resume" (or any valid abbreviation i.e. re[sume]):

> resume
OK

Create a snapshot by typing sna[pshot]:

> sna
{remoteAbsoluteFile=null, transferred bytes=82}
82 bytes written to C:\projects\devsuite\jrc\dist\snapshot-20061005-081929.xml

ProfilerJ-Viewer

See tutorial to find out how to use ProfilerJ-viewer.