> For the complete documentation index, see [llms.txt](https://docs.flopsar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flopsar.com/7/user-guide/setting-up-monitoring/instrumentation.md).

# Instrumentation

Instrumentation is a JVM feature that lets the agent modify method bytecode.

## 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:

```java
com.flopsar.*
com.sun.*
javassist.*
java.*
javax.*
jdk.*
org.apache.bcel.*
org.objectweb.*
sun.*
```

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: Allow and Block.

1. **Allow rules** (inclusive):

   Allow rules define the conditions that a method must meet to be selected for instrumentation. These rules specify which methods should be included based on criteria such as method name patterns, return types, parameter types, or access modifiers.
2. **Block rules** (exclusive):

   Block rules specify conditions that, if met by a method, exclude it from instrumentation even if an Allow rule would otherwise include it. 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.

1. **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.
2. **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.

<figure><img src="https://content.gitbook.com/content/QzShZISPoFZ9zIHUdjNB/blobs/Jxb41dpELSm5P4c8NcXo/irules.svg" alt=""><figcaption><p>Multiple rules instrumenting the same class</p></figcaption></figure>

### Rule Application Order

All rules are applied in a strictly defined order to ensure consistent behavior.

1. **Block rules first**:
   * When a class is loaded, Block rules are applied first. If the class meets the criteria defined by any Block rule, it is then passed for further evaluation to that rule’s method component. The Block rule will evaluate each method in the class.
   * If a method in the class satisfies the conditions of at least one Block rule, it will be excluded from instrumentation. It will not be instrumented and will not undergo further evaluation by any other rules.
2. **Allow rules next**:
   * If the class does not meet any of the Block rule criteria, it is then evaluated by the Allow rules. The class must satisfy the class component of an Allow rule to proceed.
   * Each method within the class is then checked against the method component of the Allow rules. If a method meets the conditions specified in an Allow rule, it will be instrumented according to that rule’s definition.

This sequential application of rules ensures that any method excluded by a Block rule is not subject to further processing by Allow rules, providing a clear and predictable instrumentation process.

#### Example

Suppose we have a rule set consisting of four rules: two Block and two Allow. 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 a Block-rule flow, while the green ones represent the Allow-rule flow. First column represents the class part of a rule while the second column the method part of a rule.

<figure><img src="https://content.gitbook.com/content/QzShZISPoFZ9zIHUdjNB/blobs/HnhNHy8r40f4zWHvRvJ7/ruleseval.svg" alt=""><figcaption><p>Sample Rules Evaluation</p></figcaption></figure>

Suppose we have a class `A`, which is passed to the rules filter. The class has four methods. First, the Block rules are evaluated. The first Block 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 Block 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 Block rules, we get to the first Allow 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 Allow rule and it becomes invisible to the last rule. Finally, we get to the last Allow 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 Allow 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.

{% hint style="warning" %}
During the retransformation process you application performance will be degraded and your application can become unresponsive.
{% endhint %}

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.