Callbacks onUncaughtException() and onUncaughtExceptionExt()

To execute a code when method terminates because of an uncaught exception (a throwable), define callback method onUncaughtException() or onUncaughtExceptionExt() in probe class.

Only one method named onUncaughtException() or onUncaughtExceptionExt() can exist in a probe class. You can omit these callback methods if uncaught exception handling is not needed for your probe.

Difference between onUncaughtException() and onUncaughtExceptionExt()

onUncaughtException() is intended to monitor possible uncaught exceptions without changing the logic of instrumented code. After the callback returns, the exception will be automatically re-thrown.

onUncaughtExceptionExt() does not automatically re-throw the original exception. This provides an opportunity to alter instrumented code behavior by suppressing the exception and, for a non-void method, returning a value instead.

The capabilities provided with onUncaughtExceptionExt() have more to do with debugging than with monitoring or profiling, as they affect application logic. Be very careful: inappropriate use can break the application.

Parameters

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

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

Return type of onUncaughtException

onUncaughtException() must be void.

Technically, onUncaughtException() is called inside try/finally block surrounding instrumented method body:

After onUncaughtException() returns, the exception will be automatically re-thrown
If an uncaught exception happens inside onUncaughtException() body, it will be thrown instead of the original exception

The following pseudocode demonstrates how the callback works:

Before instrumentation:

ReturnType foo() {
  bar(); // do something
  return result;
}

After instrumentation with onUncaughtException():

ReturnType foo() {
  try {
    bar(); // do something
    return result;
  }
  catch (Throwable e) {
    SomeProbeClass.onUncaughtException(...);
    throw e; // automatically re-throw original exception
  }
}

Return type of onUncaughtExceptionExt

onUncaughtExceptionExt() return type must be the same as the return type of method to be instrumented. If the types mismatch, the probe will not be applied to the method.

The following pseudocode demonstrates how the callback works:

Before instrumentation:

ReturnType foo() {
  bar(); // do something
  return result;
}

After instrumentation with onUncaughtExceptionExt():

ReturnType foo() {
  try {
    bar(); // do something
    return result;
  }
  catch (Throwable e) {
    // may throw exception or return a value
    return SomeProbeClass.onUncaughtExceptionExt(...); // return value must be ReturnType
  }
}