Exception Sensor

Overview

The Exception Sensor is used to gather information about caused exceptions in an application. The Exception Sensor is able to trace created, thrown, and handled exceptions within a target application. It is possible to gather information about methods and constructors that can cause an exception. You have to specify in the configuration file which classes should be instrumented. There can be as many exception-sensor configurations defined as you like.

Configuration

Exception Type Definition

^{from version 1.3}

An exception-sensor-type has to be specified explicitly from the version 1.3. Furthermore, only one exception-sensor-type is available and allowed to be specified. Thus, the exception-sensor-type definition does not include the name of the sensor:

exception-sensor-type [fqn] [options]

exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor

Simple or enhanced exception sensor

^{from version 1.3}

When in doubt use the simple exception sensor! The exception sensor mode can be defined as simple and enhanced, by using the option "mode" in the sensor definition:

exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor mode=simple|enhanced

1. Simple mode will only provide the information where have the exceptions been created. All other informations like passed and handled will not be available. But, there will be no performance overhead for using the exception sensor (overhead is described below)
2. Enhanced mode will provide all Exception event types, but will also bring the performance overhead for the monitored application.

Note that simple mode is default mode and will be used if "mode" option specification is omitted.

String length

^{from version 1.3}

This sensor enables the limitations of the string values collected. The exception sensor concretely can limit the maximum size of the strings collected as exception messages and stack traces. The following definition will, for example, limit all the strings collected by the sensor to 500 characters:

exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor stringLength=500

You can read more about string length limitations on Sensor type definition page.

Sensor assigment

To assign the Exception Sensor, the name together with the fully-qualified-name of the class to instrument must be defined. As an optional parameter it is possible to enable superclass or interface matching support. The Exception Sensor name must always be defined as exception-sensor in the configuration file. There is no limit in the number of exception-sensor configurations to be defined. The example below shown how the Exception Sensor can be used in the configuration file.

exception-sensor [Exception Class] [options]

The Exception Sensor is able to use Wildcards (see Agent configuration) for the definition of the class name. The options can be used to define that the provided Exception Class should be treated as interface or superclass (see the superclasses and interfaces chapter in Agent configuration).

Examples

The next table provides samples of how the Exception Sensor can be used. Bear in mind, that you can define multiple exception-sensor configurations.

exception-sensor java.lang.Throwable superclass=true

exception-sensor my.package.exception.MyException

exception-sensor my.package.ex*.*Exception

exception-sensor my.package.exception.IException interface=true

exception-sensor my.package.exception.My*Exception

exception-sensor *

exception-sensor my.pack*.ex*.* superclass=true

Event Types of Exceptions

The JVM traverses different points in the lifecycle of an exception, therefore you will see different event types within the UI. Each event type gives you information about what exactly happened at which point in the JVM.

new Exception();

catch(Exception e){ // gets a HANDLED
   throw e; // gets a RETHROWN
}

See the below example to get a better understanding of how the event types are assigned to the actions done by the JVM. The number in each method is an ID that represents that method. In this example an exception is created and thrown in the method read(), afterwards handled and explicitly rethrown (by reusing the object) in action(). The JVM traverses the call tree back to the root and passes the method create(), where no exception handler is found, so the exception is going further up. Eventually the exception is handled in method do().

The corresponding event types are shown in the picture below. The ID 37 is not important in this context (it stands only for the constructor that created the exception object).

Performance impact on the target application

For testing the performance impact of the Exception Sensor on the target application an instrumented method hierarchy was created. This can be seen in the picture below.

The method start() is the entry point. From here the calls are done of the methods first() to fifth(). The whole method tree is called 1000 times having different sensor type combinations. The methods first() to fourth() contain a try-catch statement. Method fifth() can throw an exception. The different colors represent different testcases. In order to show the impact on other sensor types, the Exception Sensor is tested with different sensor types that work on a method-basis. The following sensor type combinations are tested:

• Timer: only a Timer sensor is defined
• Timer + Exception Sensor: additionally to the Timer the Exception sensor is activated
• Timer + InvocationSequence: The Timer together with the InvocationSequence is defined
• Timer + InvocationSequence + Exception Sensor: additionally the Exception sensor is defined

Testcase 1 - blue-colored

The method hierarchy is called 1000 times without causing any exceptions. This is done in order to test the runtime behavior with an activated Exception Sensor where no exceptions are recorded during runtime. If no exceptions are caused during runtime within the target application, the runtime behavior of the different sensor type combinations must be the same. The result of this testcase can be seen in the below picture.

There is no significant difference in the runtimes of the different sensor types. The difference between Timer and Timer + ExSensor is -3%. Also the case having Timer + InvocSeq and Timer + InvocSeq + ExSensor leads to a difference of 2%. 

Testcase 2 - orange-colored

The method hierarchy is called 1000 times, where only one exception is created, thrown and then reused. In this testcase an exception is created and thrown in the method fifth(). The methods first() to fourth() all contain a try-catch statement, where the exception object is catched and rethrown by reusing the object. The result can be seen in the following picture.

In an exceptional case there is a runtime difference of 233% between Timer and Timer + ExSensor. Also the case having Timer + InvocSeq and Timer + InvocSeq + ExSensor leads to a difference of 117%. This is due to the fact that the stack trace is always saved with the exception object (gathering and saving the stack trace takes some time). The test was repeated with a deactivated stack trace. The outcome is that the deactivation lead to a reduced overhead. Now the difference in the runtime between Timer and Timer + ExSensor is only 19%. Also the difference between Timer + InvocSeq and Timer + InvocSeq + ExSensor is now only 26%.

Testcase 3 - red-colored

The method hierarchy is called 1000 times, where in each method a new exception object is created and thrown. In this testcase an exception is created and thrown in the method fifth(). The methods first() to fourth() all contain a try-catch statement, where the thrown exception object is catched. After that a new exception object is created and thrown. The stack trace is retrieved from each exception object, which of course has an impact on the runtime behavior. The result of this testcase is shown in the below picture.

The runtime difference between Timer and Timer + ExSensor amounts to 617%, which is huge. If the stack trace gathering is deactivated, the runtime difference amounts to 76%. Also the combination having Timer + InvocSeq and Timer + InvocSeq + ExSensor leads to a runtime difference of 315%. A deactivation of the stack trace reduces this overhead to 43%.

Open Issues