Using the Profiler

This section describes the features of the Profiler graphical user interface, and how to use these features. The information is organized as follows:

• Specifying the Profiler Options

• Working with the IDM Profiler View

• Working with the Snapshot View

• Using the Pop-Up Menu Options

• Searching a Snapshot

• Saving a Snapshot

Specifying the Profiler Options

The Profiler Options dialog consists of the following tabs:

• Mode

  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.

    ---

    Note –

    • The Java and IDM Objects option is not available if you are using a regular Waveset project with an external Identity Manager instance or using a remote Waveset project.

    • You cannot change the Mode option while the Profiler is running. You must stop the Profiler to change the option.

    ---

• IDM Object Filters:

  The IDM Object Filters tab provides the following options:

  • Show IDM Object details

    • Select this box to include every executed form, workflow, and XPRESS element in the snapshot.

    • Clear this box to include only the following elements in the snapshot:

      • <invoke>

      • <new>

      • <Rule>

      • <Form>

      • <WFProcess>

      • <ExScript>

      • <ExDefun>

      • <FieldRef>

      • <Action> (for workflow application callouts)

  • Include Anonymous Sources

    ---

    Note –

    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 Waveset repository.

    ---

    • Select this box to include Anonymous sources in the snapshot.

    • Clear this box to exclude Anonymous sources from the snapshot.

• Java Filters

  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, ...)

  ---

  Note –

  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.*"

  ---

  Note –

  The last two examples are currently equivalent because the filters are applied only to your custom classes and Waveset 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 Waveset classes. A number of Waveset 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 Waveset 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 Waveset 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.

  ---

  Note –

  You cannot modify Java filters while the Profiler is running. You must stop the Profiler before changing Java filters.

  ---

• Miscellaneous

  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 Waveset and have the complete Waveset source available.

      In this situation, you do not want to include the Waveset source because it can create extremely large snapshots. (See How the Profiler Locates and Manages Source for more information.)

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 Waveset 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 Waveset project with an External Identity Manager Instance or the remote Waveset 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.

Working with the IDM Profiler View

The IDM Profiler view consists of the following areas:

• 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.

• Controls Area: Contains four icons, as described in the following table:

  Icon	Name	Purpose
  	Start Waveset Profiler	Starts the Profiler and opens the Profiler Options dialog.
  	Stop Waveset 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.

• Status Area: Reports whether you are connected to the Host and provides Status information as the Profiler is starting up, running, and stopping.

• Profiling Results Area: Contains two icons, which are described in the following table:

  Icon	Name	Purpose
  	Start Waveset Profiler	Starts the Profiler and opens the Profiler Options dialog.
  	Reset Collected Results	Resets all of the profile results you collected to this point.

• Saved Snapshots Area: Provides a list of all saved snapshots.

  ---

  Note –

  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.

    ---

    Tip –

    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.

Working with the Snapshot View

When you open a snapshot, the results display in the Snapshot View window, located on the upper right side of Waveset IDE.

A snapshot provides the following views of your data:

• 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.

    ---

    Note –

    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.

  ---

  Note –

  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.

  ---

  Note –

  The Time and Invocations data values used in Callees view have the same meaning as those used in Call Tree view.

  ---

Using the Pop-Up Menu Options

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:

Searching a Snapshot

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.

Saving a Snapshot

The Profiler provides several options for saving a snapshot. See the following table for a description of these options: