To execute a code on method entry, define callback method onEnter() in probe class.

Only one method named onEnter() can exist in a probe class. You can omit onEnter() method if it is not needed for your probe.

Parameters

The callback can have any number of parameters, including zero.

Each of the parameters must be annotated with one of the following annotations:

• @Param
• @Params
• @This

Return type

onEnter() can be void or return a value.

If onEnter() is not void, the returned value will be accessible in onReturn(), onUncaughtException() and onUncaughtExceptionExt() callbacks of the same probe class with the help of a parameter annotated with @OnEnterResult. This approach enables effective way of data transfer between method enter and exit callbacks (the value is passed via stack).

Example 1:

import com.yourkit.probes.*;

// Instrument calls of method 'findPerson' in class 'com.foo.Person', which has 2 parameters
@MethodPattern("com.foo.Person:findPerson(String, int)")
public class MyProbe {
  public static void onEnter(
    @Param(1) Object param1,
    @Param(2) int param2
  ){
    //...
  }
}

Example 2:

import com.yourkit.probes.*;

// Instrument calls of method(s) 'findPerson' in class 'com.foo.Person', with any signature,
// and print method execution times
@MethodPattern("com.foo.Person:findPerson(*)")
public class MyProbe {
  public static long onEnter() {
    return System.currentTimeMillis();
  }

  public static void onReturn(
    @OnEnterResult long enterTime
  ){
    long exitTime = System.currentTimeMillis();
    System.out.println("method execution time: " + (exitTime - enterTime));
  }
}

Special notes on instrumenting a constructor

If probe is applied to a constructor, onEnter() will be called right at the start of the constructor body, i.e. before super constructor invocation. This approach allows to take into account all activity in super constructors, which is essential to properly measure the constructor execution time or handle nested events should the constructor execution be considered a lasting event.

At such early stage, access to the object being constructed is forbidden by the bytecode verifier, and thus if you have a parameter annotated with @This it will be assigned with null. If you need to access this in constructor, you can do it in onReturn(), onUncaughtException() and onUncaughtExceptionExt().