Context Capturing
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 (since inspectIT 1.4)
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 and fields 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.
Configuration
Context capturing is defined on a sensor basis within the advanced configurations within configuration file.
Capturing Fields
The field capturing configuration consists of two elements separated by colon: f=[Displayname];[fieldname+navigation]
Here are a few examples:
Configuration | Description |
|---|---|
f=LastOperator;lastOperator | Capture the field called "lastOperator" and provide this context as "LastOperator" |
f=UserId;user.id | Capture the field user and access the field id of this user object. Use this field as context "UserId" |
f=StaticTest;PI | inspectIT can capture static values automatically. So here we capture the value of the static field PI and call this contextual information "StaticTest" |
Fields are captured after the method call
Notice that the field capturing occurs after the method was invoked (since version 1.2). We are planning to change this behaviour in a future release
Capturing return values
Return value capturing is available with inspectIT 1.4.
Capturing the return value takes two parameters separated by colon in the format* r=[Displayname];[navigation]* .If no navigation of the return value is necessary (that is the return value directly provides the information you want to display) then leave navigation empty (the colon is required though)
Here are a few examples:
Configuration | Description |
|---|---|
r=return; | Capture the return value of a method call. Add this as parameter "return". If the return value is an Object toString() will be called. |
r=return;name | Capture the return value of a method call. Add this as parameter "return". On the returned object, find the field "name" and provide it as value of the parameter. If "name" is an object, then toString() will be called. |
r=rName;name r=rLastName;lastName | You can also capture the return value twice. In this example two parameters are defined "rName" and "rLastName" which are filled by navigating the returned value to the fields "name" and "lastName". |
Capturing parameters
The capturing of parameters takes three elements separated by colon. Capturing parameters is (unfortunately) different as the parameter name is not available in the bytecode, so parameters cannot be resolved by their name. Thus one must provide the position of the parameter instead of its name: p=[position_of_parameter];[Displayname];[Navigation]
Here are a few examples:
Configuration | Description |
|---|---|
p=0;parameter1; | Takes the first parameter of the method and provide its value as contextual name "parameter1" |
p=0;UserId;id | Takes the first parameter and take the id field's value as contextual name "UserId" |
Navigating parameters/fields
Navigating the parameters/fields 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
Complete examples
Here you can find complete examples
contextual configuration | meaning |
|---|---|
sensor timer info.novatec.inspectitsamples.calculator.Calculator actionPerformed test p=0;Source;actionCommand f=LastOutput;jlbOutput.text |
|
Current limitations
- Parameter values are only shown in the invocation sequence representation
- Currently categorization based on collected parameters is not yet possible. The goal is to create different metrics based on different parameter values.