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.
...
Exception Type Definition
from version 1.3
Configuration
...
basics
Using the UI configuration interface no configuration is required at all as method sensor types are activated automatically if a profile defines such sensor assignment.
Configuration using configuration file(s)
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:
| Code Block | ||
|---|---|---|
| ||
exception-sensor-type [fqn] [options]
|
...
...
exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor
Simple or enhanced exception sensor
...
- 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)
- Enhanced mode will provide all Exception event types, but will also bring the performance overhead for the monitored application.
Configuration
...
basics
The exception sensor mode setting is available under Sensor options part in the Environment configuration.
...
The exception sensor mode can be defined as simple and enhanced, by using the option "mode" in the sensor definition:
| Code Block | ||
|---|---|---|
| ||
exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor mode=simple|enhanced |
Note that simple mode is default mode and will be used if "mode" option specification is omitted.
String length
from version 1.3
Configuration
...
basics
The string length configuration for all sensors is available in the Environment configuration.
Configuration using configuration file(s)
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:
| Code Block | ||
|---|---|---|
| ||
exception-sensor-type info.novatec.inspectit.agent.sensor.exception.ExceptionSensor stringLength=500
|
You can You can read more about string length limitations on Sensor type definition page Environment configuration page.
Sensor assigment
Configuration
...
basics
The exception sensor assignment is explained in the Sensor assignments configuration. You can find examples on the Examples page.
...
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.
| Code Block |
|---|
exception-sensor [Exception Class] [options]
|
| Tip |
|---|
In contrast to method sensor types where the definition will provide the name of the class/method on which the sensor is to be applied, the Exception Sensor needs only the name of the Exception class that should be traced. |
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 super-class (see the superclasses super-classes 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.
...
Configuration
...
Description
...
| Code Block |
|---|
exception-sensor java.lang.Throwable superclass=true |
...
Classes are instrumented that directly or indirectly extend java.lang.Throwable. The class java.lang.Throwable itself is not instrumented
...
| Code Block |
|---|
exception-sensor my.package.exception.MyException |
...
Only the class my.package.exception.MyException is instrumented
...
| Code Block |
|---|
exception-sensor my.package.ex*.*Exception |
...
)
...
.
...
...
All classes are instrumented that are implementing the interface my.package.exception.IException
...
| Code Block |
|---|
exception-sensor my.package.exception.My*Exception |
...
Classes like my.package.exception.MyException and my.package.exception.MyTestException are instrumented
...
| Code Block |
|---|
exception-sensor * |
...
Every class of type Throwable is instrumented
...
| Code Block |
|---|
exception-sensor my.pack*.ex*.* superclass=true |
...
Classes are instrumented which are extending the class that matches the pattern my.pack*.ex*.*
Event Types of Exceptions
| Anchor | ||||
|---|---|---|---|---|
|
The JVM traverses different points in the lifecycle life-cycle 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.
...
| Info |
|---|
If the stack trace is not important for analysis, the deactivation of it can improve the performance of the Exception Sensor. Please notice that this functionality is currently not yet implemented. |
Open Issues
...
Ticket number
...
Description
...
...
Testcase for try-finally statements
...
...