14.7. Profiling
Prev | Chapter 14. Performance Pack | Next

## 14.7. Profiling

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 `PersistenceManager`s 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 `PersistenceManager`s 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.

Prev | Up | Next
14.6. Lock Groups | Home | Chapter 15. Third Party Integration