Bytecode Instrumentation Profiling Toolkit for Java

Here are instructions for statically instrumenting your code using Eclipse TPTP Probekit:

1. Prepare your workstation as follows:
   1. Install Eclipse 3.1 with TPTP 4 run-time environment.
   2. Create a Java project and name it MyProbes.
   3. Configure its build path, including Biptk.jar, which is included in BIPTK.
2. In Eclipse, import into MyProbes the archive myprobes-all.zip (included in BIPTK).
3. There two .probe files (treeHandler.probe and thresholdHandler.probe). Right-click on them and select Probekit > Compile.
4. Now you must open them and edit target packages:
   1. Go to the outline.
   2. Select Targets.
   3. Include the Java packages that you want to monitor.
5. If you have the target project in the workspace, right-click one of the probes and select Probekit >Instrument.

   If you don't have the target project in the workspace, create a new Java project and add to its build path the JAR files containing the classes you want to monitor. Then proceed with instrumentation.

6. The original JAR files are backed up and you must deploy the new ones. Remember to update the class path of your JVM, adding Biptk.jar and the probe files of the MyProbes project.

On Linux:

1. Launch the agent controller.
2. Configure the boot class path of the server, adding the following entries:
   /opt/probekit/Biptk.jar
   /opt/probekit/probes2

   The second entry is the path where you extracted the contents of your probe files. The example library provided with the BIPTK is called MyProbes.jar.

3. Configure the Java arguments with this string:

   -XrunpiAgent:server=standalone,mode=none,extensionLibrary=ProbeAgentExtension.so,ext-pk- BCILibraryName=BCIEngProbe.so,ext-pk-probescript=/opt/probekit/probes2/ thresholdHandler.probescript,ext-pk-logFile=/tmp/myprobes.log,ext-pk-logLevel=finest

4. Configure the search path for shared libraries as follows:

   LD_LIBRARY_PATH=/opt/IBM/AgentController/lib:/opt/IBM/AgentController/plugins/ com.ibm.rational.pd.probekit/lib/:$LD_LIBRARY_PATH

5. In order to include your application packages, edit the thresholdHandler.probescript.
6. Configure the following Java properties:
   biptk.threshold.cpu=10000000
   biptk.threshold.elapsed=1000

   These are thresholds that you can vary according to your particular situation. They are "or-ed," so if one of the conditions is verified, a dump is written. With these settings, the filter is mostly based on elapsed times. The handler's messages are written to standard output.

On Windows:

1. Use the PATH instead of LD_LIBRARY_PATH.
2. Replace the path and the name of the shared libraries. The path for the libraries is as follows:

   %AGENT_ROOT%\plugins\com.ibm.rational.pd.probekit\lib

   AGENT_ROOT is the Rational agent controller installation directory. As this directory is not set by default, you must either expand it in the above line or set it in the environement. For instance, in my installation it is

   AGENT_ROOT=C:\Programmi\IBM\AgentController.

   The above becomes

   SET PATH= C:\Programmi\IBM\AgentController\plugins\com.ibm.rational.pd.probekit\lib;%PATH%

   In the Xrun string, we must adapt library names and path to Windows conventions. For instance:

   -XrunpiAgent:server=standalone,mode=none,extensionLibrary=ProbeAgentExtension.dll,ext-pk- BCILibraryName=BCIEngProbe.dll,ext-pk-probescript=c:\local\probes2\ thresholdHandler.probescript,ext-pk-logFile=c:\myprobes.log,ext-pk-logLevel=finest

There is a native library that collects timing statistics using POSIX calls (this works for most Linux systems on Intel, where a thread is a process from the "Os" point of view) or JVMPI (getCurrentThreadCPUTime()).

In the Biptk-cpulib.zip archive you find compiled libraries for Windows (JVMPI) and Linux Intel (JVMPI and Posix), in addition to source code for building the library on other platforms. Under Linux, the default is JVMPI, but it is possible to fall back on Posix automatically. In order to make it work, you must make the shared libraries (cputime.dll, libcputime.so, or libptime.so) visible in the library path of your JVM. Then, for JVMPI, you must start the JVM with the -Xruncputime option.

You can force which library you want to be loaded with the system property biptk.native.timer, which can have the values JVMPI or POSIX.

biptk.threshold.cpu=10000000
biptk.threshold.elapsed=1000

At this point you must launch Eclipse and import .xprof traces into a project. The .xprof extension is associated with the visualizer plug-in. You can right-click on trace files and choose Open with BIPTK Editor.

On the top, the editor shows the top method call and, further down, a table with the child calls. You move between method calls with double clicks. If you right-click on the current method call, the context menu provides three commands:

• largest elapsed path
• largest CPU path
• detect cycles

The first and second commands make the detail table show the heaviest method calls, traversing the whole tree. The third method call helps detect simple cycles and aggregate cycle data into a single call.

BaseTreeHandler provides the following features:

• creation of profiling traces
• obtaining of method signature
• auto flush
• collection of CPU timings if native libraries are available.

It is possible to build custom behaviors on top of these features.