Monitoring method invocation events

Probe class for monitoring method invocation events is a Java class which meets the following requirements:

• It must be a public class. If it is an inner class, it also must be static.

• It must be annotated with @MethodPattern annotation in order to specify which methods the probe will be applied to.

• It must define at least one of the following callback methods (must be public static too):

  • onEnter - callback to be invoked on method enter
  • onReturn - callback to be invoked on normal method exit (i.e. via return or when a void method body execution completes)
  • onUncaughtException or onUncaughtExceptionExt - callback to be invoked when the method execution is terminated because of an uncaught exception

Bytecode instrumentation engine will inject calls to your probes to the methods which you specified on probe registration.

You can access method parameters, method return value, the object for which the method is called, as well as intercept uncaught exceptions thrown in the method. This provides virtually unlimited capabilities to monitor applications.

Probe life cycle

• Write the probe classes.

  How to write the probe class and how many probe classes you need, depends on your task.

  You may intend one probe class to handle one method call only, or you can write a probe with a pattern which corresponds to several methods which you want to handle uniformly. Also, you may need several probes to solve one complex task.

  Take a look at the built-in probes to get some ideas on how to write your own ones.

• Compile the probe classes.

• Register the probe classes to make them work.

  Upon successful registration of the probe, methods matching the probe pattern will be instrumented according to the following rules.

• (Optional) If needed to return all instrumented methods to their original state, unregister the probe.