This section shows how to use the command line based client (royalty free). In the last step, we started Example01.bat. Example01.bat is in SUSPENDED mode now waiting for a client to connect and resume the application.

Run the start script profilerjCMD.bat (or profilerCMD.sh respectively). You should see the following output:

Terrasoft ProfilerJ, (C) 2006 Terrasoft Software GmbH
h[elp]
in[fo]
re[sume]
sam[pler] on|off
[bci] off | mi|me|ci|ce|Ci|Ce=pattern1;pattern2 ....
sn[apshot] [filename] [remote]
----------
sta[rt]
sto[p]
mem[ory] on|off
cpu on|off
cl[ear]
gc
----------
q[uit]

>

Sampling

If sampling is active, the agent interrupts every 10ms the currently running threads, gets the StackTraces and increments both the method-hit-count for the top level method (which is currently executed) and all cumulated-hit-counts for all Stack Trace elements. The higher the method-hit-count, the more time the respective method consumed relative to other methods.

To invoke the sampler, type 

sampler on

The client responds with "OK", sampling is activated now. Resume Example01:

resume

Example01 is running now, the console output of Example01 should show

Process is running now ...

After a few seconds Example01 should be suspended again. Example01 has done its job now, the agent prevents the application from exiting, since otherwise there would be no chance to take a snapshot showing profile data. 

In order to create a snapshot, type

snapshot

 The client responds with something alike

{remoteAbsoluteFile=null, transferred bytes=6703}
6703 bytes written to C:\profilerj\snapshot-20061020-091120.xml

The snapshots contains profile data gathered by sampling. As data is written in XML format, viewing it is rather simple - just open the file (here C:\profilerj\snapshot-20061020-091120.xml) in a browser. For detailed information about the file structure see Snapshot file format.

Resume Example01 once more. It should exit then.

Byte Code Instrumentation

As you might have already noticed, gathering profile information by sampling has some drawbacks. Despite of imposing a rather small footprint (i.e. performance penalty), it can only measure relative time consumption and doesn't tell us how often a method has been invoked. Byte Code Instrumentation addresses this issue.

In order to gather detailed profiling data, the agent injects byte code at the beginning and at the end of a method thus being able to trace method entry and exit and measure CPU and elapsed time consumption.

Start Example01 once more (the command line client should be still running) and activate BCI for all classes beginning with com.terrasoft.profilerj by entering

bci ci=com.terrasoft.profilerj.*

"ci" stands for "cpu include" and switches on method profiling. Note that  "com.terrasoft.profilerj.*" is a regular expression. The pattern ".*ClassLoader.*" for example enables method profiling for all classes containing "ClassLoader".

Resume the Example01 and wait until it is in suspended mode again:

resume

 Now take a snapshot and resume Example01to terminate it.

snapshot
resume

The snapshot produced by BCI differs significantly from that taken by sampling. Where the sampling-snapshot only shows hit-counts, the BCI-snapshot gives detailed information about invocation-counts, CPU and elapsed times. For detailed information about the file structure see Snapshot file format.

«previous   next »