14.7. Profiling

14.7.1. Profiling in an embedded GUI
14.7.2. Dumping profiling data to disk from a batch process
14.7.3. Controlling how the profiler obtains context information

The Kodo profiling capability allows for profiling of application code. It is designed to help optimize the use of Kodo, and is not intended to be a generic profiling tool. Only Kodo specific APIs are instrumented.

The profiling capability can either be used standalone using the Kodo Profiling Console, or inside the Kodo Management Console using the Profiling MBean. To use the profiling capability within the Kodo Management Console see Section 12.4.8, “Profiling MBean”.

14.7.1. Profiling in an embedded GUI

The profiling capability can be used standalone locally. To bring up the Kodo Profiling Console, set the following property (see Section 2.6.27, “kodo.ManagementConfiguration”):

  • kodo.ManagementConfiguration: profiling-gui

The left pane of the Profiling Console contains a tree. Each node in the tree represents a call in a call stack. The root of each call stack is a PersistenceManager. Note that you must use the default PersistenceManager (or an extension of it) in order to see profiling information. Each node may be composed of three items - the node name, the amount of time spent in each node, and the percentage of the total time spent in the parent node that this child node contributes. Details about a node can be seen in the right panes by selecting a node. The top right pane(s) yeild detailed information about the node (e.g. the location in code where a transaction was started, or the SQL generated for a query), and the bottom right pane contains statistics about the node.

The Profiling Console has a Profiling Toolbar. It has the following controls:

  • Refresh: Refreshes the statistics shown in the tree.

  • Refresh slider: Set the interval at which the tree will be refreshed.

  • Show descendents: Show the tree with PersistenceManagers as roots. This is the normal view. This option is available only when the Show ancestors view is in use. See the Show ancestors feature below.

  • Export...: Export the current profiling data to a file for later viewing. Exported profiling data is stored in files ending in .prx. The export can be viewed using the profilingviewer application. To do this run the profilingviewer application and pass in the name of the exported file.

  • Reset: Resets the statistics shown in the tree.

  • Show SQL: Show an inverted tree where the root nodes are SQL statements, and their ancestors are shown as children in the tree.

The profiling call tree has a context menu that is brought up in an operating system dependent manner (e.g. right click on Windows). The following options are available:

  • Refresh: Refreshes the statistics shown in the tree.

  • Show ancestors: Show an inverted tree where the nodes of the same name and description as the selected node are used as the roots, and their ancestors are shown as children in the tree.

  • Show descendents: Show the tree with PersistenceManagers as roots. This is the normal view. This option is available only when the Show ancestors view is in use.

  • Export...: Export the current profiling data to a file for later viewing. Exported profiling data is stored in files ending in .prx. The export can be viewed using the profilingviewer application. To do this run the profilingviewer application and pass in the name of the exported file.

  • Reset: Resets the statistics shown in the tree.

The detail information for a PersistenceManager contains information about objects that were fetched in the context of that PersistenceManager. The detail area consists of information about where in code the PersistenceManager was created, and a TreeTable with information on each field in each Persistence Capable class. The TreeTable has the following columns:

  • Field Name: The name of the persistent field.

  • Total: The total number of times the object containing that field was loaded in the context of the containing PersistenceManager.

  • Fetched / % Used: The first number represents the number of times the field was fetched during the initial load. The second number represents the percentage of initially fetched fields that are actually accessed. A low percentage indicates that perhaps that field should not be in the default fetch group or in a fetch group configured for initial load.

  • Unfetched / % Used: The first number represents the number of times the field was NOT fetched during the initial load. The second number represents the percentage of the time the initially unfetched field is actually accessed. A high percentage indicates that perhaps that field should be in the default fetch group or in a fetch group configured for initial load.

14.7.2. Dumping profiling data to disk from a batch process

The profiling capability can be used to create profiling exports. Exported profiling data is stored in files ending with the .prx suffix. To view exported profiling data, use the profilingviewer command, e.g. profilingviewer myexport.prx. To enable automatic export of profiling data, set the following properties (see Section 2.6.27, “kodo.ManagementConfiguration”):

  • kodo.ManagementConfiguration: profiling-export

When exporting, the ManagementConfiguration value takes the following optional parameters:

  • intervalMillis: The number of milliseconds between exports (defaults to -1, indicating that there will be a single export upon exit).

  • basename: The basename of the exported data file to create.

  • uniqueNames: A boolean that indicates whether or not the exported data file name should have the systems current time in milliseconds included as part of the name in order to make it unique.

For example, in order to export data every five minutes with a basename of MyExport include in your properties the following line:

  • kodo.ManagementConfiguration: profiling-export(intervalMillis=300000,basename="MyExport")

14.7.3. Controlling how the profiler obtains context information

The description of PersistenceManager and transaction nodes are dependent on the call stack when the PersistenceManager is created, or the transaction is started, and can be controlled by an optional parameter to the kodo.ManagementConfiguration property (see Section 2.6.27, “kodo.ManagementConfiguration”):

  • StackStyle: Indicates how much of the call stack where the PersistenceManager or transaction was created/started to include. "line" indicates a single line, "partial" indicates a partial stack starting at the user code, and "full" indicates a full call stack, including Kodo code. Defaults to "line". The full call stack is only interesting from a debugging standpoint.