Agents Profiles
Last updated
Last updated
Agents profiles are managed from Workstation and stored in Manager. The profiles view is divided into two parts
list of profiles
selected profile details
This is a view where you can see a list of all the available profiles. Here you can add, import, and delete profiles. Each list entry (representing a profile) has a label, number, and a trash icon. The label is a profile name, the banner shows how many agents are attached to the profile. The trash icon is used to remove the profile.
There is a toolbar at the top with a search text entry and two icons, which provide import and add profile features:
This action will create a new profile by importing it from a file. You can import profiles from 2.3, 2.4 and 3.0 Flopsar versions.
This action will create a new profile.
In order to display the profile details, you need to double click the desired profile in the list.
In general, there are two types of profiles: draft and active.
Draft profile is used for editing. Each profile is composed of rules and options. The following options are available:
cpu time : enables/disables a CPU time metric,
threshold : the lowest value of instrumented methods execution time (in milliseconds) above which the method calls will be reported,
jmx period : how frequently (in seconds) agents should collect JMX data.
The Instrumentation Rules tab contains a list of instrumentation rules. These rules can be enabled or disabled using a green switch by each rule. The MBeans tab contains a list of JMX MBeans entries.
There are four toolbar actions available in the draft mode:
This action will save the profile in Manager.
This action will activate the profile, which means it will save and deploy the profile to all the attached agents.
This action will create a new profile by cloning the current one.
This action will export the profile to an XML file, which can be later imported.
This view is basically read-only, i.e. you cannot edit any rules or change any settings. However, only in this view you can attach or detach agents. You can do it in the Attached Agents tab.
There are two toolbar actions available in the active mode:
This action will create a new profile by cloning the current one.
This action will export the profile to an XML file, which can be later imported.
The fundamental feature of Agent is instrumentation. This feature makes use of java.lang.instrument framework. A user profile describes what and where to instrument. However, there are some classes which are always excluded from instrumentation:
All exception classes are ignored and not instrumented.
When the agent receives a profile to load, it first parses it and then sorts its instrumentation rules. If there are any changes in the profile that requires configuration reloading, the agent reloads those classes that have been instrumented earlier and those which are required by this new profile. This classes flow is passed through the profile filters. There are a few filters operating on two levels: class and method ones. The first filter excludes all the classes from packages, which match the internal exclusion set. Next, it goes through the second, user-defined, exclusion class filter. At this point, we have all the classes we want to instrument. In the next step, all the methods from each, selected class are passed through the method filters. At this point, a class can also be excluded from the profile if any of its methods do not satisfy the filters conditions. In the end, we obtain a set of methods that are selected for instrumentation.
The methods instrumentation is performed in a specific order. First, rules with custom formatters are applied, then rules with standard formatters, and finally rules without formatters at the end. For example, if there are two method rules, one instrumenting with a custom formatter and the other one instrumenting only public methods and our method is both public and its signature matches the one specified in the first rule, then the rule with the formatter will be applied.
Each instrumentation rule is represented as a record in the rules list.
Each rule has a green or red banner. If the banner is green, the rule is inclusive. If it is red, the rule is exclusive. The text in the banner represents the type of the rule. The following types are available:
CLASS : the rule applies to classes.
INTERFACE : the rule applies to interfaces.
ANNOTATION : the rule applies to class annotations.
SUPER CLASS : the rule applies to super classes.
EXCEPTION : the rule applies to exception classes.
METHOD : the rule applies to method names.
STANDARD : the rule applies to methods with standard formatters.
FORMATTER : the rule applies to methods with custom formatters.
Each instrumentation rule is either enabled or disabled. When a rule is disabled, it is ignored by agents. In order to disable the rule, you just need to toggle the green switch, to remove the rule you must click the trash icon at the end of the record. In order to edit the rule, just double click the record. All these operations are available only in the draft profile mode.
There are several ways of creating new rules. You can either create a rule from scratch or clone a rule from another one. In order to clone a rule, right click the rule you want to clone and select Create Similar... item from the context menu. Note, you can clone only rules with formatters.
In order to create a rule from scratch, use + buttons. If you want to remove rules, you can either click the trash icon on the rule record or select some rules and select Remove Selected Rules... from the context menu.
Inclusive rules can be defined by clicking the green add button. There are several ways of specifying which class and method to instrument.
In order to add a class level rule, select Classes from the green button menu. You must specify which classes you want to instrument. If you want to match classes by their names, you should select the Class name radio button. If you want to instrument classes, which extend some super class, you should select Super class name. In this case, you need to specify the fully qualified super class name. If you want to instrument classes which implement some interface, you should select Interface name. You must then specify a fully qualified name of the interface. Finally, if you want to instrument classes, which are annotated by some annotation, you should select Annotation name. You must then specify a fully qualified name of the annotation.
If you want to instrument classes from particular packages, just select Classes from packages from the green button menu. This operation will retrieve available packages from all the attached agents. You can add rules by double-clicking selected packages.
In order to add a method level rule, select Method by access modifiers from the green button menu. You can specify methods for instrumentation by their access modifiers. Just select the modifier so that those methods are instrumented, whose modifiers match one of the selected.
You can also specify methods by exceptions they throw. Just select Method with exception from the green button menu and specify the exception class.
If you want to instrument methods with formatters, you should select Method with formatter from the green button menu.
There are some input fields that need to be filled. In the CLASS NAME field you can specify the exact class, your instrumented method should belong to. If you do not want to specify the class, then you should select Any class checkbox.
Please note that any method, which matches the specified pattern, in any class will be instrumented with the formatter if you select Any class checkbox.
In the second field (METHOD NAME AND SIGNATURE), you must specify the exact method signature you want to instrument. You should ignore argument names and specify fully qualified class names of all objects. In the OPTIONS section you have two additional options to select. If you want to ignore the configuration threshold, select Ignore threshold checkbox. If you want to instrument a method on exit, select Instrument on exit checkbox.
Now, if you want to report only parameter values without any preprocessing you can now click Save button and you have your rule defined.
However, if you want to add some custom processing you should fill out FORMATTER section. First of all, you must specify the formatter signature. There are two ways of specifying the formatter signature. The first one is to specify it manually by entering the class and the method name of your formatter. The second one is used when you already have some implemented formatters. You just need to click Browse button and select a jar file with your formatters. The application will scan the jar and populate IMPORTED FORMATTERS combo box with all the found and valid formatters. Select one of the formatters, click Save button and you have your formatter rule created.
Exclusive rules can be defined by clicking the red add button. There are several ways of specifying which class and method cannot be instrumented.
In order to exclude some classes, you must specify the pattern for fully qualified class names. If you specify an asterisk at the end, the rule will match every class, whose fully qualified name starts with the specified pattern. Otherwise, the exact match will be checked.
If you want to exclude methods, you must specify a pattern for the methods name. The pattern should be a valid regular expression.
Normally, if an exception is thrown in an instrumented method, it is reported along with its stack trace. If you do not want to report it, you must define a rule for it by specifying a fully qualified class name of the exception.
This feature allows you to record instrumented methods executions. The Hot Methods feature is very useful, when you tune your profile for minimal performance impact. In this way, you can easily detect the most frequently executed methods and exclude them from instrumentation, unless you really need to instrument them. You can also exclude classes using this feature.
You can use the feature only when you have some agents attached to your profile. In other words, agents are able to report their hot methods if and only if they instrumented these methods earlier. That means, you cannot use this feature when you create a new configuration and the profile has not been deployed yet. You must first deploy the profile, attach some agents to it, and then edit the profile again. Only then, this feature will be available to you.
In order to retrieve hot methods, click Collect button in the top-left corner. This will trigger an operation of retrieving hot methods from all the attached agents.
All the retrieved methods will populate the table. The results are always grouped by classes, methods, classes & methods or agents. You can exclude classes or methods only from views grouped by either classes or methods respectively. Views grouped by classes & methods and agents are only for information purposes.
The table column DROPPED shows how many of the calls were dropped due to the threshold value for methods duration. For agents view, the table has two additional columns:
CYCLES LEFT: how many more times the calls statistics will be collected. When this value is zero, no more calls statistics will be collected.
COLLECTION TIME: time when the statistics collection was initiated.
You can reset the results anytime and start to collect new results by clicking Reset button. This will clear all the previous results and re-enable the Hot Methods feature on all the attached agents.
Configuring JMX for agents relies on specifying ObjectName patterns and the data collecting frequency. In jmx period field you can specify how frequently agents must report data. In order to add some patterns, you must click the Manage MBeans menu.
In order to add new ObjectName patterns, you must have some profile deployed and some agents attached.
Adding new patterns requires you to deploy some profile and attach some agents in the first place. MBeans can be imported only from running agents, so there must be some agents attached to the profile.
If the list is empty, click COLLECT button in the top-right corner. This operation will collect all the available ObjectNames from all the attached agents. In order to add a selected record, either double-click the record or use the list context menu. When you are done with importing ObjectNames, click Close button. Now, you should have the selected records added to the MBeans list.
ObjectNameUsually, most of ObjectNames are specific to the servers they come from. Their names contain server-specific data such as IP addresses, ports, etc. That means there are ObjectNames that are available only on particular servers. In order to make them available on most of the servers and simplify the profile, we need to modify their ObjectNames. This can be achieved by clicking Transform to Pattern menu item in the list context menu.
In order to illustrate the transformation procedure see the picture below. There are multiple ObjectNames, which are very similar and the only key they differ is the name. By transforming the name value to * for just one of these similar records, we can easily simplify the entire set of similar records into a single ObjectName. That is exactly how the transformation procedure works.
When your profile is ready to be activated, you should first save it by clicking the Save button. This operation will only persist the profile in Manager.
During activation operation, all the attached agents are notified about it and the profile is uploaded to them. The agents will check whether there are any changes between their current profile and the new one. If agents detect instrumentation rules changes, they will reload their profile. The reloading operation duration can vary and it strongly depends on the profile and application itself. It can take from a few seconds to a minute.
Profile reloading is a heavy operation and will degrade your application performance temporarily. It can even halt the entire application for the time of reloading operation. Do not reload a profile when your application is under heavy load.
When your profile is activated, you can attach agents to it. You can do it by clicking the green plus button in the Attached Agents tab.
Menu Item
Description
Create Similar...
This action allows for creating a new rule as a clone of the selected rule. It is enabled only for rules with formatters.
Formatters
Remove Selected Rules...
This action allows to remove the selected rules.
Menu Item
Description
Transform to Pattern...
Transforms a selected MBean ObjectName by replacing it with a pattern specified in the pop-up form.
Clear Similar
Reduces the number of MBeans by transforming their ObjectName.
Remove Selected MBeans...
Removes selected MBeans from the list.
Remove All MBeans...
Removes all MBeans from the list.
