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 remotely see Section 12.4.8, “Profiling MBean”.
The profiling capability can be used standalone locally. To bring up the Kodo Profiling Console, set the following properties (see Section 2.6.32, “kodo.ProfilingAgent” and Section 2.6.34, “kodo.ProfilingInterface”):
kodo.ProfilingAgent: local
kodo.ProfilingInterface: 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.
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.32, “kodo.ProfilingAgent” and Section 2.6.34, “kodo.ProfilingInterface”):
kodo.ProfilingAgent: local
kodo.ProfilingInterface: export
The export 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.ProfilingInterface: export(intervalMillis=300000,basename="MyExport")
The description of PersistenceManager and transaction nodes can be controlled by the kodo.ProfilingHelper property (see Section 2.6.33, “kodo.ProfilingHelper”). Standard options for this property are:
stack: Include information about where the PersistenceManager or transaction was created/started.
none: Do not include any information about where the PersistenceManager or transaction was created/started.
The stack value takes the following optional parameters:
stackStyle: Indicates how much of the call stack where the PersistenceManager or transaction was created/started to include. 0 indicates a single line, 1 indicates a partial stack starting at the user code, and 2 indicates a full call stack, including Kodo code. Defaults to 0. The full call stack is only interesting from a debugging standpoint.