What is sensor assignment

Sensor assignment specifies the process of mapping/assigning an already defined Sensor type to a concrete method of a certain class. The sensor type itself is the definition of what needs to be measured. Sensor assignment thus defines what should be monitored. Note that only Method-Based Sensor Types need a sensor assignment (Platform sensor types only need to be defined and are then automatically active).

Configuration

After defining the Sensor Type, these sensor types can be assigned with the methods to be monitored. The general syntax of the definition looks as follows

sensor [sensor-type-name] [class-to-monitor] [method-to-monitor]{(parameter,parameter)} [options]

Field	Desciption
sensor-type-name	the name of a sensor type that was previously defined (see previous chapter)
class-to-monitor	the class that should be monitored including the package name using the standard Java notation (e.g. info.novatec.inspectit.MyTestClass)
method-to-monitor	the name of the method to be monitored
parameters	restriction of the method. Only the method with this parameters is monitored. (optional parameter, but if defined must be directly attached to the method without whitespace)
options	additional options that a sensor type might provide (see the definition of the sensor types for more information)

inspectIT provides sophisticated pattern matching for defining sensor assignments. Apart from defining the concrete package, class, method and/or parameters inspectIT also allows to use wildcards and other mechanism to simplify the sensor assignment.

Wildcards

The wildcard * can be used to match any length of characters. An example for a package definition could be: *novatec* which will catch every package which contains the keyword novatec. Wildcards can be used for the fields class-to-monitor, method-to-monitor and parameters. When defining a sensor assignment using wildcards usually multiple assignments are created by the agent.

Superclasses and interfaces

Often the instrumentation should include classes that realize specific interfaces or extend certain superclasses. For most software projects a well-defined interface defines (for example) the basic structure of a service. All services within this project will have to realize this interface. In order to not having to include each and every service manually, the performance analyst can use the options interface and superclass to define that all classes should be instrumented that extend some superclass or realize an interface.

Consider this class hierarchy. All services within the application realize (directly or indirectly) the interface ServiceInterface. In order to monitor the execution times all possible services within the application, it is easier to specify the interface that all services realize.With inspectIT you can use the following instrumentation to instrument all classes that realize the interface (in this example we define a timer on all methods of the realizing classes. We assume that the ServiceInterface is defined in the package info.novatec.test):

sensor timer info.novatec.test.ServiceInterface * interface=true

Notice that the class definition is representing the interface, but the methods to be instrumented are referring the implementation class, not the interface. Thus using * here does not only instrument the methods the interface defines but all methods that a class realizing the interface has.

In the follwing example all subclasses of CustomerService are instrumented.

timer info.novatec.test.CustomerService * superclass=true

Constructor instrumentation

inspectIT also provides the means to instrument the constructor calls of classes. A constructor is specified by using the keywork <init> as method name.

sensor timer info.novatec.test.SomeClass <init>

Be careful when using constructor instrumentation

Constructor instrumentation is different than method instrumentation. Not only because of the implementation in the Agent itself, but of how the JVM is executing them. If a class contains one constructor (one is always there, no matter if the user implements it directly or not) which does not more than just initializing some variables or setting some fields, then the constructor instrumentation works as expected. But problems arise if a constructor calls another constructor (through this or super) which is instrumented.

The user would expect that the inspectIT Agent record constructors calling other constructors it like in methods: That is if constructor A executes constructor B, then the invocation tracer for example will visualize it that way. That is NOT true for constructors. The problem here is that the this or super calls must remain ALWAYS as the first call. This is a limitation of the JVM which cannot be avoided.

Real call tree

Method A (Class X)
-->Constructor A (Class Y)
----->Constructor B (Class Z)
-------->Constructor C (Class Z)

Shown in inspectIT

Method A (Class X)
-->Constructor C (Class Y)
-->Constructor B (Class Z)
-->Constructor A (Class Z)

The user thinks that Method A creates 2 new instances of Class Z and 1 new instance of Y, first calling constructor C, then B and last A. The worst part here is now that the Timer records the time for each constructor whereas each of them is correct, but in the context of an invocation tracer, the exclusive time could not be calculated correctly anymore. Because Constructor A is the only time that should be subtracted from method A, but instead, C, B and A are subtracted.

Instrumentation based on modifiers

^{(since version 1.2.1)}
The additional options of the sensor assignment can include the definition of the method/constructor visibility modifier(s) that should be instrumented. Thus, the methods can be additionally filtered by the visibility modifier that can be: public, protected, private or default. The usage of this option is:

sensor timer novatec.SubTest * modifiers=pub

This instrumentation line will instrument all the public method of novatec.SubTest class. To specify the modifier, abbreviations pub, prot, priv and def have to be used. The modifiers can also be grouped, thus instrumentation line:

sensor timer novatec.SubTest do* modifiers=prot,priv

will instrument all the protected and private methods of class novatec.SubTest which name starts with the 'do'. The modifiers option can also be used with constructors. The example of instrumentation of all public constructors is:

sensor timer novatec.SubTest <init> modifiers=pub

Inner classes

Inner classes can be easily instrumented with inspectIT. Just use the standard naming schema [enclosingclass]$[Innerclass]

Annotation based instrumentation

^{(since version 1.2.1)}
Sensor assignment can include the special additional option, where an annotation can be specified and used as additional instrumentation filter. If the annotation is added to the additional options part, the agent will instrument the methods/constructors based on the annotation target:

If the annotation target is Class, then all methods from the classes that have the specified annotation will be instrumented.
If the annotation target is Method, then only methods that have the specified annotation will be instrumented.

The usage of the annotation option is:

sensor timer novatec.* * @javax.ejb.Stateless

This line will instrument all methods of all classes in novatec.* package that have been annotated with Stateless annotation.

Be Careful

Note that the full qualified name of the annotation has to be specified after the '@'. Wild-cards do not apply on annotations.

Annotation based instrumentation can be combined with all other instrumentation options.

Since the inspectIT version 1.3 the annotation instrumentation is improved in the way that all super-classes of instrumented class and its implemented interfaces will also be check for the annotations. For example, if class org.MyClass implements the interface org.MyInterface, and the org.MyInterface has been annotated with a @org.MyAnnotation, the instrumentation line:

sensor timer org.MyClass * @org.MyAnnotations

will instrument all the methods of the MyClass, although the class is not directly annotated, but one of its interfaces/super-classes is. Note that this improvement only applies to the annotations that have a class as a runtime target. The same will not be applied for the annotations that target methods.

Annotation class not needed on the class-path

From the version 1.3 annotation class that is used in the instrumentation does not need to be on the class-path.

Examples

This chapter provides examples of how instrumentation can be done. Please also visit the documentation about the concrete sensor realizations for advanced configuration possibilities (like additional sensor-type specific options)

Instrumentation	Description
sensor timer novatec.SubTest msg(java.lang.String)	A sensor of the type timer is defined on the method msg with the parameter java.lang.String of the class novatec.SubTest.
sensor timer novatec.Sub* msg(int)	An timer is added to the method msg with the parameter type int for all classes that match the class expression novatec.Sub* which will hold true for novatec.Sub and novatec.Sub2 but also for novatec.Sub.some.other.package.SomeClass.
sensor timer novatec.SubTest msg(*String)	An timer is added to the method msg with a parameter type matching the expression String of the class novatec.SubTest. So the method msg(java.lang.String)* and the method msg(my.own.String) and msg(my.own.SuperString) will be instrumented.
sensor timer novatec.Sub* m(java.lang.String,String)	This example shows different usages of wild-card.
sensor timer novatec.ITest * interface=true	This example shows how to instrument classes based on their status that they implement some interface. So this test will instrument all methods of all classes that implement the interface novatec.ITest.
sensor timer nova.Te m(String) superclass=true	A sensor is defined on methods that start with the character m and have exactly one parameter whose type match the expression String of all classes that extend a class matching the classpattern nova.Te*. (quite powerful isn't it :))
sensor isequence novatec.SubTest msg(int) minduration=10.0	Invocation sensor defined on novatec.SubTest class on msg(int) method. The interesting part here is the minduration definition, which is specified so that all invocations taking less than 10 ms will be discarded. See the Invocation Sequence documentation on additional options.
sensor timer novatec.ITest do* interface=true modifiers=pub	Instruments all public methods which name starts with 'do' in classes that implement the novatec.ITest interface
sensor timer novatec.* * @novatec.annotation.ClassAnnotation modifiers=pub	Instruments all public methods in classes that have been annotated with novatec.annotation.ClassAnnotation and are in package novatec.*
sensor timer novatec.SubTest <init>	This sensor instruments all constructors of the class novatec.SubTest
sensor timer novatec.SubTest <init> (java.lang.String)	A specific constructor is instrumented here: The method signature has to contain one single parameter of type java.lang.String.
sensor timer novatec.SubTest <init> @novatec.annotation.DefaultConstructor	Instruments all constructors in novatec.SubTest class that have been annotated with novatec.annotation.DefaultConstructor