# 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](#profile-details). To refresh the profiles list, just select the `Refresh` item from the `Options` menu. {% hint style="info" %} A profile can be deleted only in the profile details page. {% endhint %} ## 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, * **`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`. * **`JMX Period`** this option sets the time interval at which JMX data is collected. ### 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](https://docs.flopsar.com/5.1/user-guide/instrumentation#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. {% hint style="info" %} 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. {% endhint %} 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. {% code title="SampleClass.java" overflow="wrap" lineNumbers="true" %} ```java public class SampleClass { public int someField; private long someField2; private Foo someField3; public void someMethod(String arg1, int arg2, Bar arg3) { /* method block */ } } ``` {% endcode %} {% hint style="info" %} Not all actions are available since their availability depends on the selected `Pattern type` in the previous step. {% endhint %} 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: ```java // 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: ```java // 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: ```java // 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](https://docs.flopsar.com/5.1/developer-guide/agent-extensions). {% hint style="warning" %} 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. {% endhint %} #### 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](#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 {% hint style="info" %} If you want to exclude all methods from a class, select the **`Method name`** pattern, put `.*` into the `Pattern` and select the `regex` option. {% endhint %} 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](https://docs.flopsar.com/5.1/user-guide/instrumentation#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. {% hint style="info" %} You must first assign an application to your profile to be able to retrieve MBeans from the connected agents. {% endhint %}

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.