Instrumentation
Instrumentation is a JVM feature, which enables modification of the byte-codes 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
Rules
To instrument methods, you need to decide which methods should be instrumented. This is governed by a set of rules. There are two types of rules: inclusions and exclusions. You use inclusion rules to specify what should be instrumented and exclusion rules to specify what mustn't be instrumented.
Each rule has to define both a class and a method filter. The class part specifies which classes should be taken into account and the method filter specifies which methods, from these classes, should be instrumented and what data they should collect. This implies that multiple rules can instrument the same class.
Rules Evaluation Order
All the rules are evaluated in a very specific order. When a class is passed to the rules filter the exclusion rules are evaluated first. If the class part of the exclusion rule matches, the method part is checked next. If both class and method match the rule, the method will not be instrumented and other rules will not be evaluated for this method.
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.
