A profile is a collection of settings and rules, which govern agents. It tells agents what data and metrics should be collected. Each profile needs to be activated to be eligible for deployment to agents. Which profile goes to which agent is determined by assigning applications to the profiles. There is a one-to-one correspondence between profiles and applications. In other words, the agents are not assigned to profiles directly.
Every profile can be in one of three states: draft, ready or deployed.
State-to-state connections refer to operations that are allowed on the states they originate from.
Profiles are managed on the Profiles page.
To add a new profile, you must select the New item from the Options menu, specify a name for the profile and press the Save button. Next, you can click the profile name in the list to view its details. To refresh the profiles list, just select the Refresh item from the Options menu.
A profile can be deleted only in the profile details page.
The profile details page contains a selected profile detailed information, such as its settings, instrumentation rules and JMX list of MBeans.
Each profile has some settings, which are either instrumentation or JMX related. The instrumentation settings are:
CPU Time this option enables/disables CPU time metric.
JMX Period this option sets the time interval at which JMX data is collected.
Automatic Tuning this option sets one of the three available automatic tuning modes: light, moderate or aggressive. Automatic tuning is a feature which drops irrelevant method invocation reports automatically. If you want the automatic tuning algorithm to pass more methods invocation data from agents, just select the light mode. If you want to have less data, select higher modes like moderate or aggressive.
Overhead Control this option toggles the automatic overhead control feature.
The Overhead Control feature is designed to provide automatic management of additional overhead imposed on the instrumented application as a result of the Flopsar tool's operation. Monitoring applications and gathering performance data is a critical aspect of maintaining software quality. However, the act of monitoring itself can introduce overhead, potentially impacting the accuracy of collected data and the performance of the monitored application. The Overhead Control feature aims to address this issue by automating the control of overhead caused by the Flopsar tool. The feature monitors the performance metrics of the application in real-time. It uses predefined performance criteria to dynamically adjust the monitoring overhead. When the application's performance is within acceptable limits, the overhead is minimized to reduce interference. When the algorithm detects a method, whose invocations are not reported most of the time, it removes the instrumentation from this method.
This functionality in Flopsar addresses the challenge of balancing the need for accurate performance monitoring data with the potential overhead introduced by monitoring tools. By automating the control of overhead, it ensures that performance insights are collected without compromising the performance of the monitored application. This feature empowers users to maintain software quality while keeping the impact of monitoring to a minimum.
In order to make a profile deployable, you must define some instrumentation rules. You can do this in the Instrumentation rules tab.
Here, you can define your rules which can be either inclusive or exclusive (see Rules for details).
Inclusive rules are the ones that precisely define what classes and methods should be instrumented. To add such a rule, just press the Inclusive Rule button. A dialog window, with the rules wizard, should open then.
The wizard is composed of three steps. In the first step, you need to specify what classes should be taken. The following options are available for the Class level pattern:
Package the pattern is a name of a package that classes should belong to, e.g. com.foo.bar
Classname the pattern is a fully qualified class name. Only those classes will be taken into account whose name matches the specified pattern, e.g. com.foo.bar.MyClass
Superclass the pattern is a fully qualified name of a class that classes should inherit from. Only those classes will be taken into account which inherit from the specified class directly, e.g. com.foo.bar.MyClass
Interface the pattern is a fully qualified name of an interface that classes should implement directly. Only those classes will be taken into account which implement the specified interface, e.g. com.foo.bar.MyInterface
In the second step, you need to specify which methods should be instrumented.
There are three ways you can choose from to specify the filter for methods for the Pattern type:
Access Modifiers use this pattern to select only those methods whose access modifier is at least one of the chosen modifiers
Name use this pattern to select only those methods whose name matches the specified value in the Pattern field
Name & Signature use this pattern to select only those methods whose name and signature matches the specified value exactly in the Name and Signature field.
For Name & Signature option you must specify the value in the same way you would do it in your source code, except you must specify fully qualified names for classes here.
In the last step, you need to specify what kind of action should be performed when the instrumented method is to be executed.
Suppose you have a class defined below and the method someMethod is instrumented. You must select one action handler for your rule.
Not all actions are available since their availability depends on the selected Pattern type in the previous step.
What you get depends on the selected action handler. You have five choices at your disposal for the Action handler:
Basic
This action will report only the fact that a method has been called along with some basic information like duration, timestamp etc.
Standard
This action will report the same data as the above action and method arguments additionally. The method arguments will be presented as a result of executing String.valueOf function on each one of them. In the case of the sample class you will get:
Finer Standard
This action is an extended version of the action above. Additionally, if the method is an instance method it will report values of the instance object fields. Static fields will not be reported. In the case of the sample class you will get:
Finest Standard
This action is similar to the action above but in this case, if an argument is an object, its instance fields will be reported instead of its value. Static fields will not be reported. In the case of the sample class you will get:
Custom
This action will execute a user defined custom code that is provided by the agent extensions and report its output along with the basic information. In this case, you decide what you get by defining your own agent extension.
Please note, Finer Standard and Finest Standard can degrade your code execution performance so use it carefully. Custom handler can do this also if your implementation is poor.
Depending on the selected Action handler, there are some additional features you can select in the Features section:
Always report this feature makes all the instrumented methods ignore the automatic tuning in the profile settings
Instrument on exit this feature injects the instrumentation code at the end of the method body
Additionally, if you selected the Execute custom code option, you will need to specify both a class name and a method name of your custom extension code, the agent is about to inject, in the User-defined extension section. A fully qualified name for the Class name field is required and a method name for the Method name field.
If you are done with the rule, press the Save button to add the rule to the instrumentation rules list.
By default, those methods are instrumented which fulfill the conditions defined by the inclusive rules. However, sometimes these rules are too wide, i.e. they let too many methods or classes in. In order to exclude some classes and methods from instrumentation, you need to define exclusive rules. You can do it by pressing the Exclusive Rule button. A new popup window will appear then.
To add a new rule, you need to specify both class and method patterns. The following options are available for the Class level pattern:
Package the pattern is a name of a package that classes should belong to. Only those classes will be excluded from instrumentation which belong to the specified package.
Classname the pattern is a fully qualified class name. Only those classes will be excluded from instrumentation whose name matches the specified pattern, e.g. com.foo.bar.MyClass
Superclass the pattern is a fully qualified name of a class that classes should inherit from. Only those classes will be excluded from instrumentation which inherit from the specified class directly, e.g. com.foo.bar.MyClass
Interface the pattern is a fully qualified name of an interface that classes should implement directly. Only those classes will be excluded from instrumentation which implement the specified interface, e.g. com.foo.bar.MyInterface
For the Method level pattern you need to specify one of the following options:
Method name those methods will be excluded from instrumentation whose name matches the specified value in the Pattern field
Method signature those methods will be excluded from instrumentation whose signature matches exactly the one specified in the Pattern field
If you want to exclude all methods from a class, select the Method name pattern, put .* into the Pattern and select the regex option.
If you are done with the rule, press the Save button to add the rule to the instrumentation rules list.
When you add new rules, they are presented in a list. The rules are evaluated in the order of their appearance in the list (see Rules Evaluation Order for more details).
You can click each rule to see its details. Exclusive rules are denoted by red squares, while inclusive ones are denoted by green squares. If you want to edit a rule, just click the pencil icon in the right down corner of the selected rule. If you want to delete a rule, click the trash icon in the right down corner of the selected rule. To clone a rule, click the copy icon in the right down corner of the selected rule. A rule can be in one of the two states: enabled or disabled. You can switch the rule state by clicking the Enable rule switch. When a rule is disabled, it will not be deployed to agents. Each rule has also a description, which is self-explanatory.
This view enables specifying which MBeans values you want to collect. To add MBeans, you need to retrieve them from agents first. You can do this by pressing the Add ObjectNames button.
This operation will open a new popup window.
Next, press the Refresh button to retrieve the MBeans.
You must first assign an application to your profile to be able to retrieve MBeans from the connected agents.
Now, you can press the Add button for any MBean you want to select. When you are done with adding the MBeans either click outside the popup window or press the Escape button to close the popup window.
To deploy a profile, a few conditions must be fulfilled. The profile must have instrumentation rules defined, must be assigned to an application and be in the ready state.
