5.3

Profiles

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.

Profile State Machine

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.

Managing Profiles

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.

Profile

The profile details page contains a selected profile detailed information, such as its settings, instrumentation rules and JMX list of MBeans.

Profile Settings

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.

Overhead Control

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.

Instrumentation Rules

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

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.

Actions

Suppose you have a class defined below and the method someMethod is instrumented. You must select one action handler for your rule.

SampleClass.java
public class SampleClass {

    public int someField;    
    private long someField2;
    private Foo someField3;
    
    public void someMethod(String arg1, int arg2, Bar arg3) {
        /* method block */ 
    }
}

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:

// SomeClass instance
String.valueOf(this)
// someMethod arguments
arg1 
arg2 
String.valueOf(arg3)

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:

// SomeClass instance fields
someField
someField2
String.valueOf(someField3)
// someMethod arguments
arg1 
arg2 
String.valueOf(arg3)

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:

// SomeClass instance fields
someField
someField2
String.valueOf(someField3)
// methodSample arguments fields if any
arg1
arg2
// Bar instance fields
barField1
barField2
...

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.

Additional Features

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.

Exclusive Rules

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.

List of Rules

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.

JMX

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.

Deploying a Profile

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.

Last updated