Sensor assignment

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]

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.

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

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:

1. If the annotation target is Class, then all methods from the classes that have the specified annotation will be instrumented.
2. 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.

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.

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)

JMX Sensor Assignment

^{(since version 1.6.6)}
To monitor a JMX MBean attribute it is necessary to define a JMX sensor-type (see Sensor type definition for more information). After defining this sensor-type, these sensor-types can be assigned with the MBean attributes to be monitored. The general syntax of the definition looks as follows

jmx-sensor [sensor-type-name] mbeanname=[MBean-object-name] attributename=[attribute-name]

The configuration defines which attribute of whose MBean should be monitored. In order to select the desired MBean it is specified by its object name that consists of its domain and a key property list (see Oracle - Java Management Extensions (JMX) / Best Practices / ObjectName for more information).

Example

The following table contains examples of how sensors can be assigned to MBean attributes.

jmx-sensor jmx mbeanname=java.lang:type=Threading attributename=ThreadCount

jmx-sensor jmx mbeanname=java.lang:type=GarbageCollector,name=PS MarkSweep attributename=Valid