Jinsight Reference Manual

Jinsight Views

Purpose · Elements · Interpretation · Tracing Considerations

Method Histogram View

Purpose

Elements

Main View

Class names appear in a scrollable pane along the left edge. Each rectangle denotes either an instance of that class or the amount of memory consumed by instances of the class, depending on the current choice in the Object Appearance menu (described below). A diamond shape is used to denote the class object for a given class. Class objects representing primitive types may also appear.

A rectangle's color will vary according to a black-to-blue-to-red color spectrum.  Along the top of the display appears an optional color legend, showing the range of color values and the meaning of the color. The meaning of the color depends on the current choice in the Object Appearance menu. Colors on the black end of the spectrum generally denote lower values, with black meaning zero, while colors on the red end denote higher values.  Objects that have been garbage collected appear as rectangular outlines, as opposed to filled rectangles.  Class names appear in color as well, their color reflecting the cumulative value of instances of a class.

To create greater differentiation among colors, use the color scale operations in the Options menu (see below).

Arrays, if present, are depicted as separate "classes" having names of the form [type.  Each rectangle for these pseudo-classes represents an array of type.  Note:  in the current version of  Jinsight, arrays are only reported by a snapshot of the memory heap.

Menus

• Popup menus. Right-clicking on a class name or object produces a popup menu that lets you choose among several relationships the view can show.  These include the creator of the object clicked on, the objects that invoke methods on it or refer to it, and the objects it creates, invokes methods on, and refers to.  These relationships are shown as colored lines connecting the objects in question.  Red lines indicate creation, green lines represent calls, and blue lines identify references.  Clicking on a class name lets you determine the same information for every instance of the class at once.

Calling relationship lines are labeled with the number of calls that the line represents.  An arrowhead shows the direction of the relationship.  Circular calling relationships and circular references are shown as small oval lines leaving and re-entering the same object  Flying over a line with the mouse pointer shows the relationship information in the status line at the bottom of the view. Finally, the calling relationship lines to/from a single object can be restricted to show just the "top 5" -- the 5 lines representing the highest frequency of calls.

To remove all relationship lines, select Clear Lines from the Options menu.

The remaining popup menu options are active only when current selections exist. Drill Down from Selected Items lets you open a view that is restricted to the current selections. Create a New Slice will create one or more new slices from the current selections. You can create either a single slice From Selected Items or one slice For Each Selected Item. Choosing Limit an Existing Slice presents the set of execution slices you can choose to limit to Selected Items.
 

• Options menu.  Pan to Selection centers the current selection (if any) in the view.  Show Legend is a toggle to show or hide the color legend at the top of the view.  Increase Color Scale and Decrease Color Scale let you vary the mapping of colors to values.  Increase Color Scale increases the range of values, while Decrease Color Scale decreases the range.  The current values appear in the window's title bar.  Recalibrate Colors remaps the colors so that red corresponds to the highest value encountered thus far in the execution.

  Sorting choices rearrange the rows in the histogram according to different sort criteria.  Sort Class Names Now sorts the rows alphabetically, while Sort Class Colors Now sorts them by color, from red to black. 

  Clear Lines removes from the view all lines showing calling, creation, or reference relationships among the objects. Clear Selection deselects the any classes, objects, or other entities previously selected here or elsewhere in the workspace.

  Short Names strips leading qualifiers from all class names to save space and reduce clutter, at the risk of name ambiguity. Font Scaling is a toggle that allows/disallows scaling of the character data font size as the view is zoomed in and out.



• Classes menu. This menu controls what classes (rows) appear in the Object Histogram. Display all classes causes all the classes in the workspace to appear in the view. Display all classes in slice presents the set of execution slices you can choose from to limit the view to only the classes in that slice. Display selected classes (now) limits the view to only classes currently selected; the menu variation Display selected classes (live) causes the view to be updated as the set of selected classes changes.

 
• Selected menu. These options are active only when current selection(s) exist. Drill Down from Selected Items lets you open a view that is restricted to the current selections. Create a New Slice will create one or more new slices from the current selections. You can create either a single slice From Selected Items or one slice For Each Selected Item. Choosing Limit an Existing Slice presents the set of execution slices you can choose to limit to Selected Items.

 
• Help menu. Selecting Help in a view attempts to use your browser to display the Reference Manual documentation for that view. The browser program location is specified in the environment variable JINSIGHT_BROWSER, in the shell script named jinsight that invokes the visualizer.

 
• Object Appearance menu For every object, Color by Base Time calculates the time spent in methods called on that object, and it colors the corresponding rectangle accordingly.  Color by Cumulative Time colors each rectangle according to the total elapsed time spent in each method call on this object, including time spent in methods these methods call.  See the section on Time measurements for a more detailed discussion of these computations.
 
Color by Number of Calls colors a rectangle to reflect the total number of method calls on an object.  Color by Number of Threads colors rectangles to indicate the number of threads an object participates in: black means the object has received method calls in one thread, and red means more than one.

Memory Size Active and Memory Size Total produce a single rectangle of varying width for each class.  In the case of Memory Size Active, the width reflects the total amount of storage occupied by all active instances of the class—that is, instances that have not been garbage collected.  When Memory Size Total is chosen, the rectangle's width reflects the total storage consumed at one time or another by every instance, including those that have been garbage collected.

Color by Slice differentiates the classes and objects according to the color assigned to each defined slice. Dark gray is the default color for classes and objects that are in the workspace but not in any other slice. Classes completely outside of the workspace base slice filtering are rendered in an almost invisible beige color.

 

Bottom Panel

The status line displays specific information about the class or object directly underneath the mouse pointer.  This information includes:
 
• for classes:  the class name, number of live instances not including the class object, total number of  instances including garbage-collected instances but not including the class object, base and cumulative times for all instances, total number of calls on all instances, and number of bytes for all instances.

 
• for objects:  the class name, instance identifier, base and cumulative times, total number of calls, and number of bytes. The label "class object" precedes the information for class objects, which are technically instances of java.lang.Class but are included here as regular instances.

See also Using Slices in the Histogram View for a more detailed discussion of how this view may be used with slices and workspaces..

Interpretation

Program Understanding

Studying who creates or references objects, and calls methods in objects can help you understand dependencies between objects and their methods.  When objects are colored by the number of threads in which they participate, you can get a feel for how concurrent the program is by noting the preponderance of red squares.

Debugging

Unexpectedly large numbers of unreclaimed instances may suggest a memory leak.  Finding the creators of these objects and/or the objects that refer to them can help you locate the leak in small histograms.  When the number of objects or references between them is large, the Reference Pattern view should prove more helpful.

Tuning

Objects appearing in red (following color recalibration in base and cumulative time modes) may be candidates for optimization, since they consume the most time.  Memory size views can help you optimize memory-intensive classes for space.

Tracing Considerations

The trace must contain object reference information to view blue reference lines from the pop-up menu. To record reference information in the trace, issue one of the object reference snapshot commands during trace creation.

Jinsight Views

Jinsight Home

Method Histogram View