This section describes the features of the Profiler graphical user interface, and how to use these features. The information is organized as follows:
The Profiler Options dialog consists of the following tabs:
Use the options on these tabs to indicate which objects to profile and which elements to display in the profile.
After specifying the Profiler options, click OK to start the Profiler. Depending on your project configuration, the Profiler does one of two things:
If you are using a regular Identity Manager project with an Embedded Identity Manager Instance, the Profiler performs a full build, deploys into the NetBean’s application server, and starts the Profiler.
If you are using a regular Identity Manager project with an External Identity Manager Instance or the remote Identity Manager project, the Profiler attaches to the Identity Manager instance configured for the project.
You can select IdM -> Set Identity Manager Instance to control the Identity Manager Instance action for the project.
The Mode tab provides the following options:
IDM Objects Only: Select to profile form, rule, workflow, and XPRESS objects. Excludes Java objects from the profile.
Java and IDM Objects: Select to profile form, Java, rule, workflow, and XPRESS objects.
The Java and IDM Objects option is not available if you are using a regular Identity Manager project with an external Identity Manager instance or using a remote Identity Manager project.
You cannot change the Mode option while the Profiler is running. You must stop the Profiler to change the option.
The IDM Object Filters tab provides the following options:
Show IDM Object details
Include Anonymous Sources
Anonymous sources are forms (or portions of a form) that are generated on the fly (such as Login forms and MissingFields forms) and do not correspond to a persistent form that resides in the Identity Manager repository.
Select this box to include Anonymous sources in the snapshot.
Clear this box to exclude Anonymous sources from the snapshot.
Select the Java Filters tab to
Include or exclude Java filters
Create new filters
Delete existing filters
Restore the default filters
Java filters are given in terms of method patterns, and they are expressed in patterns that include or exclude based on canonical method name. Where a canonical method name is:
fully-qualified-class-name.method-name(parameter-type-1, parameter-type-2, ...)
For constructors, method-name is <init>.
Here are a few examples:
To exclude all constructors, enable the Exclude box and add the following filter:
*.<init>(*)
To exclude all constructors with a single org.w3c.dom.Element parameter, enable the Exclude box and add the following filter:
*.<init>(org.w3c.dom.Element)
To exclude all Identity Manager classes, enable the Exclude box and add the following filters:
"com.waveset.*" "com.sun.idm.*"
To instrument your custom code only, disable the Exclude box, remove the initial * include filter, and then add the following filter:
"com.yourcompany.*"
The last two examples are currently equivalent because the filters are applied only to your custom classes and Identity Manager classes.
If necessary, you can instrument other jars by modifying the following lines in build.xml as appropriate. For example,
<instrument todir="${lighthouse-dir-profiler}/WEB-INF" verbose="${instrumentor.verbose}" includeMethods="${profiler.includes}" excludeMethods="${profiler.excludes}"> <fileset dir="${lighthouse-dir}/WEB-INF"> <include name="lib/idm*.jar"/> <include name="classes/**/*.class"/> </fileset> </instrument> |
By default, the configuration includes all your custom classes and most Identity Manager classes. A number of Identity Manager classes are forcibly excluded— because enabling them would break the Profiler.
For example, classes from the workflow, forms, and XPRESS engines are excluded or the Profiler would produce an unintelligible snapshot when profiling Java and Identity Manager objects.
Note that Java filters provide much more filtering granularity than IDM Object Filters. Java instrumentation adds significant overhead to the execution time, which can drastically skew the profiling results. Because Identity Manager objects are interpreted rather than compiled, the instrumentation overhead is negligible. So for example, there is basically no reason to exclude workflow A and include workflow B, and so forth.
You cannot modify Java filters while the Profiler is running. You must stop the Profiler before changing Java filters.
The Miscellaneous tab provides the following options:
Prune snapshot nodes where execution time is 0:
Disable this option (default) if you want the snapshot to include invocation information for all executed entities— even those whose execution time is zero.
It might be useful to have the number of invocations, even for nodes where there is no execution time.
Enable this option to remove these nodes, which allows you to focus on the most relevant profiling data. In addition, enabling this option can provide a large savings in Profiler snapshot size.
Automatically Open Browser Upon Profiler Start:
Enable this option (default) when you launch the Profiler to automatically open a browser that points to the Identity Manager instance being profiled.
Disable this option if you do not want to open a browser.
Include Java Sources in Snapshot:
Enable this option (default) to include Java sources for any Java methods referenced by the profiling data in the Snapshot. You should always use this setting for snapshots in the field. Custom Java is relatively small and it is very valuable to have for support.
Disable this option only if you are profiling Identity Manager and have the complete Identity Manager source available.
In this situation, you do not want to include the Identity Manager source because it can create extremely large snapshots. (See How the Profiler Locates and Manages Source for more information.)
The IDM Profiler view consists of the following areas:
The Current Project area consists of a drop-down menu that lists all of your current projects. Use this menu to select the project you want to profile.
The Controls area contains four icons, as described in the following table:
Icon |
Name |
Purpose |
---|---|---|
|
Start Identity Manager Profiler |
Starts the Profiler and opens the Profiler Options dialog. |
|
Stop Identity Manager Profiler |
Stops the Profiler. |
|
Reset Collected Results |
Resets all of the profile results you collected to this point. |
|
Modify Profiling |
Reopens the Profiler Options dialog so you can change any of the settings to modify your current profile results. |
The Status area reports whether you are connected to the Host and provides Status information as the Profiler is starting up, running, and stopping.
The Profiling Results area contains two icons, which are described in the following table:
Icon |
Name |
Purpose |
---|---|---|
|
Start Identity Manager Profiler |
Starts the Profiler and opens the Profiler Options dialog. |
|
Reset Collected Results |
Resets all of the profile results you collected to this point. |
The Saved Snapshots area provides a list of all saved snapshots.
Instructions for saving snapshots are provided in Saving a Snapshot.
In addition, you can use the following buttons to manage these snapshots:
Open: Click to open saved snapshots in the Snapshot View window.
You can also double-click a snapshot in the Saved Snapshots list to open that snapshot.
Delete: Select a snapshot in the Saved Snapshots list, and then click this button to delete the selected snapshot.
Save As: Select a snapshot in the list and then click this button to save that snapshot externally to an arbitrary location.
Load: Click to open a snapshot from an arbitrary location into the Snapshot View window.
When you open a snapshot, the results display in the Snapshot View window, located on the upper right side of Identity Manager IDE.
A snapshot provides several views of your data, which are described in the following sections:
Call Tree view consists of a tree table showing the call timing and invocation counts throughout your system.
This tree table contains three columns:
Call Tree column: Lists all nodes.
Top-level nodes are one of the following:
Thread.run() methods for various background threads in the system
For example, if you enabled Java profiling, you will see the ReconTask.WorkerThread.run() method.
Request timings
For example, if you viewed the idm/login.jsp URL, you will see a top-level entry for idm/login.jsp. The data displayed in the Time column for this entry represents the total time for that request (or requests). The data displayed in the Invocations column represents the total number of invocations to that page. You can then explore further into that data to see what calls contributed to its time.
The Call Tree also contains Self Time nodes. Self Time values represent how much time was spent in the node itself. (For more information, see Statistics Caveats.)
Time column: Lists the time spent in each node when that node was called from its parent. The percentages are given relative to parent time.
Invocations column: Lists how many times each node was invoked from its parent.
Hotspots view provides a flattened list of nodes that shows aggregate call timings regardless of parent.
This view contains the following columns:
Self Time: Lists the total amount of time spent in each node.
Invocations: Lists the total number of times each node was invoked from its parent.
Time: Lists the total amount of time spent in each node and in all of its children.
Back Traces view provides an inverted call stack showing all the call chains from where each node was called.
You can use these statistics to answer the question— How much time would I save if I eliminated this particular call chain from this node?
You can access the Back Traces view from any of the other snapshot views by right-clicking a node (known as the root node) and selecting Show Back Traces from the pop-up menu.
The Time and Invocations data values mean something different in Back Traces view:
Time: The values in this column represent the time spent in the root node when it is called from a given call chain.
Invocations: The values in this column represent how many times the root node was invoked from a given call chain.
Callees view provides an aggregate call tree for a node (known as the root node), regardless of its parent chain.
These statistics are helpful if you have a problem area that is called from many places throughout the master call tree and you want to see the overall profile for that node.
You can access the Callees view from any of the other snapshot views by right-clicking a node (known as the root node) and selecting Show Callees from the pop-up menu.
The Time and Invocations data values used in Callees view have the same meaning as those used in Call Tree view.
Right-click any node in Call Tree view or in Hotspots view and a pop-up menu displays with the options described the following table:
Menu Options |
Description |
---|---|
GoTo Source |
Select this option to view the XML source for a node that corresponds to a Java method, workflow, form, rule, or XPRESS. For detailed information about this view, see How the Profiler Locates and Manages Source. |
Show Back Traces |
Select this option to access the Back Traces view. For detailed information about this view, see Back Traces View. |
Show Callees |
Select this option to access the Callees view. For detailed information about this view, see Callees View. |
Find In Hotspots |
Select this option to find a node in the Hotspots view. For detailed information about this view, see Hotspots View. |
List Options -> Sort -> |
Select this option to
|
List Options -> Change Visible Columns |
Select this option to change the columns displayed in the Call Tree or Hotspots list. When the Change Visible Columns dialog displays, you can select one or more of the following options:
|
Use the Search icon , located at the top of the Snapshot View window to search for nodes by name the Call Tree view or Hotspots tree.
Alternatively, right-click any node in Call Tree view or Hotspots view and select Find in Call Tree or Find in Hotspots (respectively) from the pop-up menu to search for a node.
The Profiler provides several options for saving a snapshot. See the following table for a description of these options:
Icon |
Name |
Purpose |
---|---|---|
|
Save the Snapshot in the Project icon (located at the top of the Snapshot View window) |
Saves the snapshot in the nbproject/private/idm-profiler directory of your project. Snapshots saved in your project are listed in the Saved Snapshots section of the Profiler view. |
|
Save the Snapshot Externally icon (located at the top of the Snapshot View window) |
Saves a snapshot to an external, arbitrary location. |
|
Save As button (located in the Saved Snapshots area) |
Saves a snapshot to an external, arbitrary location. |