Instrumentation
Instrumentation is a JVM feature, which enables modification of the bytecodes of methods.
Limitations
There are some limitations imposed on the instrumentation, i.e. not every entity can be instrumented. These limitations are hard-coded in agents and you cannot change them. There are both class and method limitations.
Classes
Classes from the following packages are always excluded from instrumentation:
Additionally, the following class entities are also excluded from instrumentation:
interfaces
enum classes
annotation classes
modules
synthetic classes
primitives
arrays
Methods
The following methods are always excluded from instrumentation:
abstract methods
synthetic methods
native methods
constructors
class initializers
getters and setters
Rules
Instrumentation Method Selection
Before proceeding, you need to determine which method you want to instrument. This is done using specialized instrumentation rules. There are two types of such rules: inclusive and exclusive.
Inclusive Rules:
Inclusive rules define the conditions that a method must meet to be selected for instrumentation. These rules are used to specify which methods should be included based on certain criteria, such as method name patterns, return types, parameter types, or access modifiers.
Exclusive Rules:
Exclusive rules specify conditions that, if met by a method, will exclude it from instrumentation. These rules serve as a filter to prevent certain methods from being instrumented, even if they meet the criteria set by the inclusive rules. For example, you might want to exclude methods with a specific name or methods from certain packages.
This dual-rule system provides flexibility and precision in selecting exactly which methods will be instrumented.
Rule Structure
Each rule consists of two parts: a class component and a method component.
Class Component:
The class component defines the conditions that a class must meet to be considered for instrumentation. This may include criteria such as the class name pattern, package name or implemented interfaces. Only classes that meet these criteria will be eligible for further evaluation by the method component of the rule.
Method Component:
The method component specifies the conditions that a method within the eligible class must satisfy to be instrumented. This can include conditions such as the method name, return type, or parameter list. This allows for precise control over which methods in the selected classes will be instrumented.
This structure implies that a single class can be instrumented by multiple rules. For instance, different rules can target different sets of methods within the same class based on varying criteria in the method component. This layered approach enables complex and flexible instrumentation scenarios, where diverse rules can be applied to instrument different aspects of a class independently.
Rule Application Order
All rules are applied in a strictly defined order to ensure consistent behavior.
Exclusive Rules Application:
When a class is loaded, exclusive rules are applied first. If the class meets the criteria defined by any exclusive rule, it is then passed for further evaluation to that rule’s method component. The exclusive rule will evaluate each method in the class.
If a method in the class satisfies the conditions of at least one exclusive rule, it will be excluded from instrumentation. This means that it will not be instrumented and will not undergo further evaluation by any other rules.
Inclusive Rules Application:
If the class does not meet any of the exclusive rule criteria, it is then evaluated by the inclusive rules. The class must satisfy the class component of an inclusive rule to proceed.
Each method within the class is then checked against the method component of the inclusive rules. If a method meets the conditions specified in an inclusive rule, it will be instrumented according to that rule’s definition.
This sequential application of rules ensures that any method excluded by an exclusive rule is not subject to further processing by inclusive rules, providing a clear and predictable instrumentation process.
Example
Suppose we have a rule set consisting of four rules: two exclusive and two inclusive. Let's analyze how a class is evaluated against the rules. The pictures below will help us to visualize the flow. Each row in the picture represents a single rule evaluation flow. Red arrows represent an exclusive rules flow, while the green ones represent the inclusive rules flow. First column represents the class part of a rule while the second column the method part of a rule.
Suppose we have a class A, which is passed to the rules filter. The class has four methods. First, the exclusion rules are evaluated. The first exclusion rule matches the class, so the method part of the rule is evaluated next. As we can see, the method_4 matches the method part of the rule. That means, this method is excluded from instrumentation and it becomes invisible to the rest of the rules. Next, the second exclusion rule is evaluated. Again, we have a match for the class part but this time we do not have a match in the method part of the rule. That means, the class with the remaining methods is passed further. Since, there are no more exclusive rules, we get to the first inclusive rule (the third row). Here we have a match in the class part of the rule, so we move to the method part where we have a match for the method_2. This means, that method will be instrumented by the first inclusive rule and it becomes invisible to the last rule. Finally, we get to the last inclusive rule. Again, we have a match in both the class and method part. This time method_3 is matched. This method will be instrumented by the last inclusive rule. There left only one method method_1, which did not match any of the rules. This method will not be instrumented.
The final result of the evaluation is that two methods will be instrumented by different rules and the rest of the methods will be left unchanged.
Retransformation
Retransformation is a feature which enables to reload a collection of classes. This operation is preformed when you deploy a profile. Unfortunately, this operation is expensive and even though the instrumentation itself is blazingly fast, the internal JVM mechanics involved into the retransformation process takes much more time.
During the retransformation process you application performance will be degraded and your application can become unresponsive.
That is something you should always take into account when deploying profiles, e.g. try not to deploy profiles when your application is under heavy load.
Last updated
