Profiles
Last updated
Last updated
A profile is a set of rules, which govern agents. It tells agents what data should be collected and how. 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. In other words, the agents are not assigned to profiles directly.
In this view, you can see all your profiles.
Each profile can be either active or inactive. When the profile is active, there is a green icon next to the profile name indicating this fact. The APPLICATION column indicates which application is assigned to the profile. The number, next to the application name, denotes how many agents have the profile currently loaded. Each profile record has an actions menu, which is used to perform profile-related actions.
To perform an action for the selected profile, click the actions menu and select the corresponding menu item.
To change the profile name, click the actions menu of the profile record and select the Change Name menu item.
If a profile is about to be used, it requires an application to be assigned to it.
You can only assign applications to active profiles. The same application cannot be assigned to two different active profiles.
There are two ways of adding profiles to the list: creating a new profile or importing the profile from a file.
To create a new profile, click the main options menu and select the New Profile menu item. Next, specify a name for the profile, optionally select the application you want to assign to the new profile, and click the Save button. This will create an empty profile and add it to the list.
You can also add profiles by importing them from files. To import the profile, you can either drag the profile file and drop it on the list or click the main options menu and select the Import Profile from File menu item.
Please note, a newly created profiles are not persisted in the server by default. You will need to save it manually in the profile editor otherwise when you restart the workstation, the profile will be gone.
A profile editor is a place where you can edit your profiles. You can access the editor by clicking the profile actions menu and selecting the Edit menu item. When you access the editor of an empty profile, you will get the view below.
Each profile is composed of rules and options. A profile consists of two parts: instrumentation and JMX. In the instrumentation part, you define your instrumentation rules, and in the JMX part, you define MBeans you want the data to be collected from.
To instrument methods, you need to decide which methods should be instrumented. This is governed by a set of rules. There are two types of rules: inclusions and exclusions. You use inclusion rules to specify what should be instrumented and exclusion rules to specify what mustn't be instrumented. There are two levels of rules: class and method rules. If you want to define a rule, that defines which classes should be instrumented, then you must use a class level rule. If you want to define a rule, that defines which methods should be instrumented, then you must use a method level rule.
To create a new class rule, you must click the Include button and select the Classes menu item. Next, the corresponding form will pop up.
The form contains a text field, in which you must specify a pattern. The pattern value depends on the rule type you select in the form. There are four types at your disposal.
If you want to define a rule, which selects classes by their name, select the Class name button and specify a fully qualified name of the class. You can also specify a package along with the asterisk at the package name, instead. In this case, all classes from this packaged will be selected for instrumentation.
If you want to define a rule, which selects classes by the superclass they extend, select the Super class name button and specify a fully qualified name of the superclass, you want the classes to extend from.
If you want to define a rule, which selects classes by the interface they implement, select the Interface name button and specify a fully qualified name of the interface.
If you want to define a rule, which selects classes by their annotations, select the Annotation name button and specify a fully qualified name of the annotation the classes must be annotated with.
To create a new method rule, which selects methods by their access modifiers, click the Include button and select the Method by Access Modifiers menu item.
If you want to select methods that have package-level access, you need to select the default option.
To create a new method level rule, which selects methods by exceptions they declare to throw, click the Include button and select the Methods with Exceptions menu item.
If you want to select methods, that throw a specific exception, you need to enter a fully qualified class name of the exception.
If you want to instrument a specific method and inject some code to format the method data, click the Include button and select the Methods with Formatters menu item.
First of all, you need to specify, in the CLASS field, a fully qualified name of the class the method, you want to instrument, belongs to.
Next, you must specify the name and signature of the method in the METHOD NAME AND SIGNATURE field. Each class name used in the method signature must be entered as a fully qualified name. The return type of the method must be specified at the beginning of the method name. The method arguments must be specified without labels.
Next, if you want every invocation of the method to ignore the threshold, select the Ignore threshold option. This option will make your method always report, regardless of its duration.
By default, methods are instrumented at the beginning of their body. If you want to instrument the method at the end of its body, select the Instrument on exit option.
There are two types of formatters you can use. If you select the Standard formatter, then you do not need to specify any formatter, since the so-called standard formatter will be used. If you want to use your own formatter, click the Custom option. If you have a jar file with your formatters, you can click the Browse button and select the jar file. This operation will scan the jar file, extract any available formatters, and populate the IMPORTED FORMATTERS combo box with the formatters signatures. Next, you can simply click the combo box, select the formatter, and both the CLASS and METHOD NAME fields will be filled out automatically. You can also specify the formatter class and method names manually.
To create a class exclusion rule, you must click the Exclude button and select the Classes menu item. Next, the corresponding form will pop up.
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 method's name. The pattern should be a 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 method 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 profile and it has not been deployed yet. You must first deploy the profile and then edit the profile again. Only then, this feature will be available to you.
To exclude some methods, using this feature, click the Exclude button and select the Hot Methods menu item.
If the Hot Methods table is empty, click the Collect button in the top-left corner. This will trigger an operation of retrieving hot methods from all the attached agents.
The collected hot methods are presented in a table. The table contents depend on the selected Group By item. When the class item is selected, the table presents a list of classes, when the method is selected, the table presents a list of methods, and when the class & method is selected, the table presents a list of methods along with their classes. The CALLS COUNT column contains the number of invocations of the corresponding record. The DROPPED column denotes how many percent of invocations have been dropped due to the duration threshold. If this value is high, then it is advised to exclude the corresponding method or class from your profile to reduce the performance impact of the instrumentation.
The hot methods feature is always reset every time a new profile is loaded. The statistics are collected for about 5 minutes and then the feature is disabled. If you want to reenable it, just click the Reset button.
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 clicking the Collect MBeans button. This will open a popup window with a list of available MBeans. If the list is empty, click the Collect button. This will query all the agents, that have the profile deployed.
Please note, MBeans can be queried not earlier than two minutes after the agent start.
When the profile is saved, it can be activated. Profile activation is a procedure, which enables deploying the profile to agents. An application must be assigned to the profile prior to the activation. When a profile is activated, it is deployed to agents that belong to the applications assigned to the profile and have the license. When the agent receives the profile, it checks whether there are any changes in the profile which require reloading. When the profile is reloaded, the hot methods feature is reset also.
An active profile's view can be accessed by clicking their names in the profiles list. In this view, you can see the profile details.
The fundamental feature of the 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 that are always excluded from instrumentation:
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. When the profile is being loaded the stream of classes passes through the profile filters. The filters operate 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.
