Context capturing in sensor assignment

^{Applies to the Timer sensor only}

Context capturing allows to define certain parameters and even fields to be captured by the inspectIT agent during monitoring. This data is invalueable for monitoring and analysis as it can provide additional information about the metric. Parameter capturing is also very powerful for invocation sequences to build up a context of the invocation.

What can be captured

• Method parameters often contain important information about the metric. Often the response times of services are dependent on the data it gets - a user service that creates statistical information on employees is most likely to be faster for an employee who has less data. 
• By capturing the fields of the object that invokes a method inspectIT allows to get contextual information even in situations in which the state is not provided by parameters but is integrated in the object itself. 
• Return values

Navigating to the contextual information

Often the desired contextual information is not directly provided by the parameter or field, but contained within. So in order to get the contextual information one must navigate the parameter/field by accessing methods. inspectIT comes with the powerful feature of navigating parameters, fields and return values to get to the desired contextual information. One example is the User object is passed in the (made up) employee statistical service used above. Imagine that we want to know the userId which is contained in the User object that the service gets as a parameter. The agent should thus navigate the User parameter and just use the information that is contained within the userId field of the parameter.

Navigating the parameters/fields/return value is done based on the common Java bean syntax. userObject.user.name translates to: take the field called "userObject" and find the field user within it and afterwards find the field name. Note that you can only navigate fields and cannot execute any method on the object. Technically the execution of methods on the objects is easily possible, but by doing so the monitoring system might change the internal state (which should not happen). 

Currently inspectIT only allows to execute two special methods on objects:

• size
• length

Configuration

Context capturing is defined on a sensor assignment and it's only available on the Timer sensor. In the Sensor specific options the option Capture context must be activated. Then you can add unlimited number of captured data via the Add Context Capture button.

Capturing Fields

To capture a field you need to select  Field option in the Add Context Capture dialog and add the field name. Note that field should exists on the class specified in the sensor assignment class definition. Set the display name to be how you would like the captured value to be visible in inspectIT.

Here are a few examples:

Capturing return values

Capturing the Return value is similar to the field, expect that here there is no need to specify anything else except the display name and optionally navigation path.

Here are a few examples:

Capturing parameters

Capturing parameters is (unfortunately) different as the parameter name is not available in the byte-code, so parameters cannot be resolved by their name. Thus one must provide the index of the parameter in the method. Make sure that the method you are trying to instrument has the parameter on the specified index. Note that this is zero-based index.

Here are a few examples:

Current limitations

• Captured values are only shown in the invocation sequence representation and details dialog
• Currently categorization based on collected parameters is not yet possible. The goal is to create different metrics based on different parameter values.