Probekit overview

Probekit is a scriptable, byte-code instrumentation (BCI) framework that you can use to write Java code fragments that can be inserted into a program to provide information about the program as it runs.

A Probekit file can contain one probe or multiple probes, each probe can contain one or more probe fragments. You can specify which probes you want to use on a given program, and when you want the probe fragments to be executed. You can also specify filter or target wildcard patterns for the classes and methods you want each probe applied to.

Probe fragments are assembled into a set of Java methods which are then compiled. When a probe is compiled, the probe code fragments are combined with standard boilerplate, and Java source code for a new class is generated. The functions generated from the probe fragments appear as static methods of the generated class.

When probes are applied, the BCI engine refers to the list of probes and their target patterns and inserts calls to probe fragment methods into the target programs. The data items requested by a probe fragment (like the method name and arguments) are passed as arguments. One benefit of this system is that a probe can be inserted into a large number of target methods with small overhead.

A probe fragment has access to some information about the location being probed. A fragment can see the class name and method name of the method it is inserted into, the method signature, the this object, and the argument list. In addition, a catch fragment can see the exception object, and can distinguish a catch clause from a finally clause. An exit fragment can also see the return value from the method being probed, or the exception object for an exception exit.

Probe fragments can be executed:

at method entry time
at method exit time (either a normal return or as the result of an exception)
at exception handler time; that is, at the top of a catch clause, or the top of a finally clause that is executed as the result of an exception
when specific methods are called; where instrumentation is done at the at the call site, not inside the called method

Probe fragments can access the following types of information about the methods they are inserted into:

package, class, and method name
method signature
this object
arguments
return value
the exception object that caused an exception handler exit, or an exception exit from the method