NAME
analyzer - GUI for analyzing a program performance experi-
ment
SYNOPSIS
analyzer [-j|--jdkhome jvm-path][-J jvm-options]
[-f|--fontsize size][-v|--verbose][experiment-list]
analyzer -V|--version
analyzer -?|-h|--help
analyzer [-f|--fontsize size][-v|--verbose] target [target-
arguments]
When the Analyzer is invoked on more than one experiment or
experiment group, it will aggregate data from the experi-
ments. You may change the mode to compare experiments. See
"COMPARISON MODE", below, for more information.
OPTIONS
Option Meaning
-j|--jdkhome jvmpath
Specify the path to the Java[TM] virtual machine
(JVM) software for running the Analyzer. The
default path is taken first by examining environ-
ment variables for a path to the JVM, in the order
JDK_HOME, and then JAVA_PATH. If neither environ-
ment variable is set, the version found on your
PATH is used. If none is found,
/usr/java/bin/java is tried. (The terms "Java
virtual machine" and "JVM" mean a virtual machine
for the Java(TM) platform.)
-Jjvm-option
Specify JVM software options. Multiple -J argu-
ments can be supplied. Note that there is no
space between the -J flag and the jvm-option.
Examples:
analyzer -J-d64 -- run the 64-bit analyzer
analyzer -J-Xmx2G -- run with maximum JVM memory of 2 GB (Default, 1 GB)
analyzer -J-d64 -J-Xmx8G -- run the 64-bit analyzer with maximum JVM memory of 8 GB
-f|--fontsize size
Specify the font size to be used in the Analyzer.
-v|--verbose
Print version information and Java runtime argu-
ments before starting.
-V|--version
Print version information and exit.
-?|-h|--help
Print usage information and exit.
DESCRIPTION
The Performance Analyzer is a graphical data-analysis tool
that analyzes performance data collected by the Collector
using the collect command, or the IDE, or the collector com-
mands in dbx. The Collector gathers performance information
to create an experiment during the execution of a process.
The Performance Analyzer reads in such experiments, analyzes
the data, and displays the data in tabular and graphical
displays. A command-line version of the analyzer is avail-
able as the er_print utility.
To start the Performance Analyzer, type the following on the
command line:
analyzer[ experiment-list]
The experiment-list command argument is a blank-separated
list of experiment names, experiment group names, or both.
Multiple experiments or experiment groups can be specified
on the command line. If you specify an experiment that has
descendant experiments inside it, all descendant experiments
are automatically loaded, but the display of data for the
descendant experiments is disabled. To load individual des-
cendant experiments you must specify each experiment expli-
citly or create an experiment group. To create an experiment
group, create a plain text file whose first line is as fol-
lows:
#analyzer experiment group
Then add the names of the experiments on subsequent lines.
The file extension must be erg.
You can also use the File menu in the Analyzer window to add
experiments or experiment groups. To open experiments
recorded on descendant processes, you must type the file
name in the Open Experiment dialog box (or Add Experiment
dialog box) because the file chooser does not permit you to
open an experiment as a directory.
When the Analyzer displays multiple experiments, however
they were loaded, data from all the experiments is aggre-
gated.
You can preview an experiment or experiment group for load-
ing by single-clicking on its name in either the Open
Experiment dialog box or the Add Experiment dialog box.
You can also start the Performance Analyzer to record an
experiment, from the command line as follows:
analyzer target[target-arguments]
The Analyzer starts up with the Oracle Solaris Studio Col-
lect dialog box showing the named target and its arguments,
and settings for collecting an experiment. See "Recording
Experiments," below.
ANALYZER WINDOW -- Left hand tabs
The Analyzer window has a menu bar, a tool bar, and a split
pane that contains tabs for the various displays. The left
pane contains tabs for the principal Analyzer displays. The
tabs that are actually present in that pane are controlled
by a tabs directive in a .er.rc file, as well as the pres-
ence or absence of data to support the tab. The tabs that
can be shown, listed in the order they would appear, are:
o The MPI Timeline tab
o The MPI Charts tab
o The Races tab
o The Deadlocks tab
o The Dual Source tab
o The Functions tab
o The Callers-Callees tab,
o The CallTree tab,
o The Source tab,
o The Source/Disassembly
o The Lines tab,
o The Disassembly tab,
o The PCs tab,
o The OpenMP Parallel Region tab,
o The OpenMP Task tab,
o The DataObjects tab,
o The DataLayout tab,
o Various MemoryObjects tabs,
o Various IndexObjects tabs,
o The Timeline tab,
o The Leaklist tab,
o The Statistics tab,
o The Experiments tab.
By default, the first visible tab is selected. Only tabs
applicable to the data in the loaded experiments are shown.
The Set Data Presentation dialog box contains a Tabs tab
that shows all available regular tabs in one column, and all
defined MemoryObject tabs in a second column, with check-
boxes for all applicable tabs.
The right pane contains the MPI Timeline Control Tab, the
MPI Chart Control Tab, the Summary tab, the Event tab, the
Leak tab, the Deadlock Details tab, and the Race Details
tab. Only those right-hand tabs corresponding to visible
left-hand tabs are shown.
The toolbar contains a button for the Find tool, which you
can use to locate text or highlighted lines in the various
tabs (see Finding Text and Data, below).
To configure the split pane, you can drag the splitter bar
to resize the panes. You can also click the zoom buttons
(triangles) in the splitter bar to expand a pane to full
size or restore it to the default size. The triangles point
in the direction the splitter bar moves when you click them.
To select the splitter bar from the keyboard, press F8. The
arrow keys move the splitter bar. Home moves the splitter
bar all the way to the left. End moves the splitter bar all
the way to the right.
To reorder the columns in any table, drag the column header
to the desired location. To sort the tables in the Functions
and Callers-Callees tabs by the contents of any column,
click the column header.
The rightmost entry on the Menu bar is a Help menu. You can
use it to display help on the Analyzer, including a descrip-
tion of new features, a quick-reference guide, and lists of
keyboard shortcuts. In addition, the F1 key displays
context-sensitive help for the selected tab.
The MPI Timeline Tab
The MPI Timeline tab shows a set of horizontal bars,
one for each process in the MPI experiment, with diago-
nal lines connecting them indicating messages. Each
bar has regions colored according to the MPI function
they are in, or indicating that the process is not
within MPI (i.e., it is in elsewhere in the application
code). Selecting a region of a bar, or a message line
shows detailed information about the selection in the
MPI Timeline Controls tab.
Dragging the mouse causes the MPI Timeline to zoom in
on the horizontal (time) axis, or the vertical (pro-
cess) axis, depending on the predominant direction of
the drag.
The MPI Chart Tab
The MPI Chart tab shows charts of the MPI tracing data
seen in the MPI Timeline. It presents various plots of
data concerning MPI execution. Selecting an element
from a chart shows more detailed information in the MPI
Chart Controls tab. Dragging the mouse causes the MPI
Chart to zoom in on the horizontal axis, or the verti-
cal axis, depending on the predominant direction of the
drag.
The Races Tab
The Races tab shows a list of data-races in the pro-
gram, grouped by common callstack. It is visible only
if data-race data is recorded in a loaded experiment.
By default the first data-race in the list of data-
races is selected. For more information, see the
tha(1) man page.
The Deadlocks Tab
The Deadlocks tab shows a list of deadlocks and poten-
tial deadlocks in the program, grouped by common call
stack. It is visible only if deadlock data is recorded
in a loaded experiment. By default the first deadlock
in the list of deadlocks is selected. For more infor-
mation, see the tha(1) man page.
The Dual Source Tab
The Dual Source tab shows two panes, each corresponding
to a Source Tab, as described below. It shows the two
source locations, based on the selected Thread Analyzer
event. It is loaded by a selection in the Race Detail
or Deadlock Detail right-hand tabs only; it is not
affected by any other selection from any other tab.
For a selected data-race, it shows the source locations
for the two accesses of the data-race, as shown in the
Race Detail tab. For a selected deadlock, it shows
the two accesses corresponding to acquiring a first
lock, and deadlocking attempting to acquire a second
lock, from the thread selected in the Deadlock Detail
tab. It is visible only if Thread Analyzer data is
recorded in a loaded experiment. For more information,
see the tha(1) man page.
The Functions Tab
The Functions tab shows a list consisting of functions
and their metrics. The metrics are derived from the
data collected in the experiment. Metrics can be
either exclusive or inclusive. Exclusive metrics
represent usage within the function itself. Inclusive
metrics represent usage within the function and all the
functions it called. The list of available metrics for
each kind of data collected is given in the collect(1)
man page. Only the functions that have non-zero metrics
are listed. Time metrics are shown as seconds,
presented to millisecond precision. Percentages are
shown to a precision of 0.01 %. If a metric value is
precisely zero, its time and percentage is shown as
"0." If the value is not exactly zero, but is smaller
than the precision, its value is shown as "0.000" and
its percentage as "0.00". Because of rounding, percen-
tages might not sum to exactly 100%.
Count metrics are shown as an integer count.
The metrics initially shown are based on the data col-
lected and on the default settings read from various
.er.rc files (See DEFAULTS, below). For clock-based
profiling, the default set consists of inclusive and
exclusive User CPU time. For synchronization delay
tracing, the default set consists of inclusive syn-
chronization wait count and inclusive synchronization
time. For hardware counter overflow profiling, the
default set consists of inclusive and exclusive times
(for counters that count in cycles) or event counts
(for other counters). For heap tracing, the default
set consists of heap allocations and bytes allocated.
Calls to mmap are treated as memory allocations when
heap tracing. If more than one type of data has been
collected, the default metrics for each type are shown.
The metrics that are shown can be changed using the Set
Data Presentation dialog box.
To reorder the columns of metrics, drag the column
header to the place you want it to appear.
To select the sort metric, click the appropriate column
header. The metric name for the sort metric is
displayed in bold face, and a triangle graphic is
displayed in the header.
To search for a function, use the Find tool.
The Callers-Callees Tab
The Callers-Callees tab shows the selected function in
a pane in the center, with callers of that function in
a pane above, and callees of that function in a pane
below, showing the attributed metrics. For the
selected function, the attributed metric represents the
exclusive metric for that function. For the callees,
the attribute metric represents the portion of the
callee's inclusive metric that is attributable to calls
from the center function. The sum of attributed
metrics for the callees and the selected function
should add up to the inclusive metric for the selected
function. For the callers, the attributed metrics
represent the portion of the selected function's
inclusive metric that is attributable to calls from the
callers. The sum of the attributed metrics for all
callers should also add up to the inclusive metric for
the selected function.
The metrics shown in the Callers-Callees tab are chosen
in the Set Data Presentation dialog box. If either an
inclusive or an exclusive metric is chosen, the
corresponding attributed metric is shown in the
Callers-Callees tab.
To reorder the columns of metrics, drag the column
header to the place you want it to appear.
To select the sort metric, click the appropriate column
header. The metric name for the sort metric is
displayed in bold face, and a triangle graphic is
displayed in the header. Attributed metrics can be used
only for sorting in the Callers-Callees tab.
To search for a function, use the Find tool.
Selecting a different function in any tab updates the
Callers-Callees tab to center it on the selected func-
tion.
The center area of the Callers-Callees Tab contain but-
tons to construct a callstack fragment by prepending or
appending callers or callees to the existing center
function.
The center area also includes forward and back buttons
for navigating the Callers-Callees tab.
Double-clicking on a caller or callee will prepend or
append the function to the center.
Right-clicking in the caller-callee tab will bring up
an option menu to manage the callstack fragment, or set
a filter, or navigate forward or backwards through the
history.
The CallTree Tab
The CallTree Tab shows the dynamic callgraph of the
program as a tree, with hierarchical metrics on each
line. The dynamic callgraph consists of all paths from
the initial function (usually _start) to all other
functions. Nodes in the tree can be expanded or con-
tracted by clicking on the arrow next to them.
The metric shown in the CallTree Tab is the attributed
metric for each path to that function.
The Source Tab
If available, the Source tab shows the file containing
the source code of the selected function, annotated
with performance metrics for each source line. The full
names of the source file, the corresponding object file
and the load object are given in the column heading for
the source code. In the rare case where the same
source file is used to compile more than one object
file, the Source tab shows the performance data for the
object file containing the selected function.
The Analyzer looks for the file containing the selected
function under the absolute pathname as recorded in the
executable. If the file is not there, the Analyzer
tries to find a file of the same basename in the
current working directory. If you have moved the
sources, or the experiment was recorded in a different
file system, you can put a symbolic link from the
current directory to the real source location in order
to see the annotated source.
When a function is selected in the Functions tab and
the Source tab is opened, the source file displayed is
the default source context for that function. The
default source context of a function is the file con-
taining the function's first instruction, which for C
code is the function's opening brace. Immediately fol-
lowing the first instruction, the annotated source file
adds an index line for the function. The source window
displays index lines as text in red italics within
angle brackets in the form shown below:
<Function: f_name>
A function might have an alternate source context,
which is another file that contains instructions attri-
buted to the function. Such instructions can come from
include files or from other functions inlined into the
selected function. If there are any alternate source
contexts, the beginning of the default source context
includes a list of extended index lines that indicate
where the alternate source contexts are located.
<Function: f, instructions from source file src.h>
Double clicking on an index line that refers to another
source context opens the file containing that source
context, at the location associated with the indexed
function. To aid navigation, alternate source contexts
also start with a list of index lines that refer back
to functions defined in the default source context and
other alternate source contexts.
The source code is interleaved with any compiler com-
mentary that has been selected for display. The classes
of commentary shown can be set in the Set Data Presen-
tation dialog box. The default classes can be set in a
defaults file (see DEFAULTS, below).
The metrics displayed in the Source tab are chosen in
the Set Data Presentation dialog box.
Lines with metrics that are equal to or exceed a thres-
hold percentage of the maximum of that metric for any
line in the source file are highlighted to make it
easier to find the important lines. The threshold can
be set in the Set Data Presentation dialog box. The
default threshold can be set in a defaults file (see
DEFAULTS, below).
To search for text and for highlighted lines, use the
Find tool (see Finding Text and Data, below).
To reorder the columns of metrics, drag the column
header to the place you want it to appear.
The Lines Tab
The Lines tab shows a list consisting of source lines
and their metrics. Source lines are labeled with the
function from which they came and the line number and
source file name. If no line-number information is
available for a function, or the source file for the
function is not known, all of the function's PCs appear
aggregated into a single entry for the function in the
lines display. PCs from functions that are from load-
objects whose functions are hidden appear aggregated as
a single entry for the load-object in the lines
display. Selecting a line in the Lines tab shows all
the metrics for that line in the Summary tab. Select-
ing the Source or Disassembly tab after selecting a
line from the Lines tab positions the display at the
appropriate line.
The Disassembly Tab
The Disassembly tab shows a disassembly listing of the
object file containing the selected function, annotated
with performance metrics for each instruction.
Interleaved within the disassembly listing is the
source code, if available, and any compiler commentary
chosen for display. The algorithm for finding the
source file in the Disassembly tab is the same as the
algorithm used in the Source tab.
Just as with the Source tab, index lines are displayed
in Disassembly tab. But unlike the Source tab, index
lines for alternate source contexts cannot be used
directly for navigation purposes. Also, index lines for
alternate source contexts are displayed at the start of
where the #included or inlined code is inserted, rather
than just being listed at the beginning of the
Disassembly view. Code that is #included or inlined
from other files will show as raw disassembly instruc-
tions without interleaving the source code. However,
placing the cursor on one of these instructions and
selecting the Source tab, opens the source file con-
taining the #included or inlined code. Selecting the
Disassembly tab with this file displayed opens the
Disassembly view in the new context, thus displaying
the disassembly code with interleaved source code.
The classes of commentary shown can be set in the Set
Data Presentation dialog box. The default classes can
be set in a defaults file (see DEFAULTS, below).
The analyzer highlights lines with metrics that are
equal to or exceed a metric-specific threshold, to make
it easier to find the important lines. The threshold
can be set in the Set Data Presentation dialog box. The
default threshold can be set in a defaults file (see
DEFAULTS, below).
To search for text and for highlighted lines, use the
Find tool (see Finding Text and Data, below).
To reorder the columns of metrics, drag the column
header to the place you want it to appear.
The Source/Disassembly Tab
The Source/Disassembly tab shows two panes, one
corresponding to the Source Tab, and one corresponding
to the Disassembly tab. Both panes are loaded by any
selection, just as the individual tabs are loaded.
The PCs Tab
The PCs tab shows a list consisting of PCs and their
metrics. PCs are labeled with the function from which
they came and the offset within that function. PCs
from functions that are from load-objects whose func-
tions are hidden appear aggregated as a single entry
for the load-object in the PCs display. Selecting a
line in the PCs tab shows all the metrics for that PC
in the Summary tab. Selecting the Source or Disassem-
bly tab after selecting a line from the PCs tab posi-
tions the display at the appropriate line.
The OpenMP Parallel Region Tab
The OpenMP Parallel Region tab shows the list of OpenMP
parallel regions with their metrics. The tab is appli-
cable only to experiments recorded with the OpenMP 3.0
collector.
The OpenMP Task Tab
The OpenMP Task tab shows the list of OpenMP tasks with
their metrics. The tab is applicable only to experi-
ments recorded with the OpenMP 3.0 collector.
The DataObjects Tab
The DataObjects tab shows the list of data objects with
their metrics. The tab is applicable only to hardware
counter experiments where the aggressive backtracking
option was enabled, and for source files that were com-
piled with the -xhwcprof option in the C compiler. It
shows hardware counter memory operation metrics against
the various data structures and variables in the pro-
gram.
The DataObjects tab can be made visible only if one or
more of the loaded experiments contains a dataspace
profile.
The DataLayout Tab
The DataLayout tab shows the annotated dataobject lay-
outs for all program data objects with data-derived
metric data. The layouts appear in the tab sorted by
the data sort metrics values for the structure as a
whole. The tab shows each aggregate data object with
the total metrics attributed to it, followed by all of
its elements in offset order. Each element, in turn,
has its own metrics and an indicator of its size and
location in 32-byte blocks.
As with the DataObjects tab, the DataLayout tab can be
made visible only if one or more of the loaded experi-
ments contains a dataspace profile.
The MemoryObjects Tabs
Each MemoryObjects tab shows the metric values for
dataspace metrics, attributed to the memory objects
(cache-lines, pages, etc.) for that tab. Any number of
MemoryObjects Tabs can be made visible, but as with the
DataObjects tab, the MemoryObjects tabs can be made
visible only if one or more of the loaded experiments
contains a dataspace profile.
Various MemoryObjects tabs are predefined, and a button
in the Tabs tab of the Set Data Presentation dialog box
can be used to define a custom memory object, by
assigning it a name, and giving an index expression
used to map the recorded Physical or Virtual Address to
an object index. One or more memobj_define commands
can be included in a .er.rc file to predefine custom
memory objects. See the er_print(1) man page for more
information.
Each MemoryObjects tab has radio buttons allowing the
selection of either a Text display or a Graphical
display. The Text display is very much like the
DataObject Tab, and uses the same metric settings. The
Graphical display shows a graphical representation of
the relative values for each memory object, with a
separate histogram for each metric. The histogram is
sorted by the data sort metric.
The IndexObjects Tabs
Each IndexObjects tab shows the metric values for all
metrics, similar to the MemoryObjects tabs for
dataspace metrics.
Various IndexObjects tabs are predefined, and a button
in the Tabs tab of the Set Data Presentation dialog box
can be used to define a custom index object, by assign-
ing it a name, and giving an index expression used to
map the recorded parameters of an event to an object
index. One or more indxobj_define commands can be
included in a .er.rc file to predefine custom index
objects. See the er_print(1) man page for more infor-
mation.
Each IndexObjects tab has radio buttons allowing the
selection of either a Text display or a Graphical
display. The Text display is very much like the Func-
tions Tab, but shows only exclusive metric settings.
The Graphical display shows a graphical representation
of the relative values for each index object, with a
separate histogram for each metric. The histogram is
sorted by the data sort metric.
The Timeline Tab
The Timeline tab shows a chart of the events and the
sample points recorded by the Collector as a function
of time. Data is displayed in horizontal bars. For each
experiment there is a bar for sample data and a set of
bars for each LWP. The set for an LWP consists of one
bar for each data type recorded: clock-based profiling,
hardware counter overflow profiling, synchronization
tracing, heap tracing, and MPI tracing.
The bars that contain sample data show a color-coded
representation of the time spent in each microstate for
each sample. Samples are displayed as a period of time
because the data in a sample point represents time
spent between that point and the previous point. Click-
ing a sample displays the data for that sample in the
Event tab.
The profiling data or tracing data bars show an event
marker for each event recorded. The event markers con-
sist of a color-coded representation of the call stack
recorded with the event, as a stack of colored rectan-
gles. Clicking a colored rectangle in an event marker
selects the corresponding function and PC and displays
the data for that event and that function in the Event
tab. The selection is highlighted in both the Event tab
and the Legend tab, and selecting the Source or
Disassembly tab positions the tab display at the line
corresponding to that frame in the call stack.
For some kinds of data, events might overlap and not be
visible. Whenever there are two or more events at
exactly the same position, only one is drawn; if there
are two or more events within one or two pixels, all
are draw, although they might not be visually distin-
guishable. In either case, a small gray tickmark
appears below the drawn events indicating the overlap.
The Timeline tab of the Set Data Presentation dialog
box allows you to change the types of event-specific
data that are shown; to select the display of event-
specific data for threads, LWPs, or CPUs; to choose to
align the call stack representation at the root or at
the leaf; and to choose the number of levels of the
call stack that are displayed. You can use the Event
Tab toolbar to step horizontally between events and
vertically between bars, to zoom in or out on the time
axis or to reset the display to full width. You can
also zoom in by dragging over a region. You can change
the color that is mapped to the selected function using
the color chooser which is brought up by clicking on
the Color Chooser icon on the tool bar. In the color
chooser, you can also set a color for all functions, or
for those functions whose name matches a particular
string pattern. The color chooser also allows you to
set the color for clock-profiling events representing
microstates other than User CPU, or to hide such
events. The color chooser also has a legend giving the
color for each function.
Experiments are selected for display using the Filter
Data dialog box. The choice of LWPs, threads, and CPUs
in this dialog box does not affect the display of data
in the Timeline tab.
The LeakList Tab
The LeakList tab shows two lines, the upper one
representing leaks, and the lower one representing
allocations. Each contains a call stack, similar to
that shown in the Timeline tab, in the center with a
bar above proportional to the bytes leaked or allo-
cated, and a bar below proportional to the number of
leaks or allocations.
Selection of a leak or allocation displays the data for
the selected leak or allocation in the Leak tab, and
selects a frame in the call stack, just as it does in
the Timeline tab.
The LeakList Tab can be made visible only if one or
more of the loaded experiments contains heap trace
data. You can use the Leak Tab toolbar to step hor-
izontally between leaks or allocations, or vertically
to switch from leaks to allocations and vice-versa.
You can also change the color that is mapped to the
selected function using the color chooser which is
brought up by clicking on the Color Chooser icon in the
tool bar.
The Statistics Tab
The Statistics tab shows totals for various system
statistics summed over the selected experiments and
samples. The totals are followed by the statistics for
the selected samples of each experiment. For informa-
tion on the statistics presented, see the getrusage(3C)
and proc(4) man pages.
The Experiments Tab
The Experiments tab is divided into two panels. The top
panel contains a tree that contains nodes for the load
objects in all the experiments loaded, and for each
experiment load. When the Load Objects node is
expanded, it shows the list of all load objects, and
various messages about their processing.
When the node for an experiment is expanded, it shows
two areas: a Notes area and an Info area.
The Notes area displays the contents of any notes
file in the experiment. The notes can be edited by typ-
ing directly in the Notes area. The Notes area includes
its own toolbar with buttons for saving or discarding
the notes and for undoing or redoing any edits since
the last save.
The Info area contains information about the experi-
ments collected and the load objects accessed by the
collection target, including any error messages or
warning messages generated during the processing of the
experiment or the load objects.
The bottom panel lists error and warning messages from
the analyzer session.
ANALYZER WINDOW -- Right hand tabs
The right hand tabs are used to show detailed information
about an item selected from one of the left hand tabs.
The Summary Tab
The Summary tab shows all the recorded metrics for the
selected function or load object, both as values and
percentages, and information on the selected function
or load object. The Summary tab is updated whenever a
new function or load object is selected in any tab. It
is raised on any selection from the Functions, Caller-
callee, Lines or PCs tab. It is loaded, but not raised
on selection from the Source or Disassembly tabs.
The Event Tab
The Event tab shows detailed data for the event that is
selected in the Timeline tab, including the event type,
leaf function, LWP, thread IDs, and CPU IDs. Below the
data panel the call stack is displayed with the color
coding for each function in the stack. Clicking a func-
tion in the call stack makes it the selected function.
When a sample is selected in the Timeline tab, the
Event tab shows the sample number, the start and end
time of the sample, and the microstates with the amount
of time spent in each microstate and the color coding.
The Event tab has a toolbar, which is used to step
between events, to zoom the timeline, and to bring up
the color chooser.
This tab is visible only when the Timeline tab is visi-
ble in the left pane. It is raised whenever a selection
is made in the Timeline tab.
The Leak Tab
The Leak tab shows detailed data for the selected leak
or allocation in the Leaklist tab. Below the data
panel, the Leak tab shows the callstack at the time
when the selected leak or allocation was detected.
Clicking a function in the call stack makes it the
selected function.
The Leak tab has a toolbar, which is used to step
between events, and to bring up the color chooser.
This tab is visible only when the Leaklist tab is visi-
ble in the left pane. It is raised whenever a selection
is made in the Leaklist tab.
The MPI Timeline Controls Tab
The MPI Timeline Controls tab supports zoom, pan,
event-step, and filtering for the MPI Timeline tab.
Filtering causes data outside the current field of view
to be eliminated from the data set used in the MPI
Chart tab. A filter is applied by clicking the Filter
button. The back-filter button is used to undo the
last filter; the forward-filter button is used to reap-
ply a filter. Filters are shared between the MPI Time-
line tab and the MPI Chart tab, but are not currently
applied to other tabs.
The MPI Timeline Controls tab is also used to show the
details for a function or message selection from the
MPI Timeline tab.
The MPI Chart Controls Tab
The MPI Chart Controls tab has a set of drop-down lists
to control the type of chart, the parameters for the X
and Y axes, and for the Metric and Operator used to
aggregate the data to specify the chart.
The MPI Chart Controls Tab allows for presenting of X-
or Y-Histograms, or a 2-D chart. It allows showing
data either for functions or messages. The "Metric"
setting allows selection of Time, Duration, Process
(MPI Rank), and Byte counts. A Metric setting of "1"
is used to cound numbers of events. The Chart Controls
also allow setting an operator, governing how the
metric values are combined in the chart. It allows
selecting Sum, Minimum, Maximum, Average, or Fair. The
Fair operator selected a representative value.
See the On-line Help and Manual for further informa-
tion.
Filtering causes data outside the current field of view
to be eliminated from the data set shown in the MPI
Timeline tab. A filter is applied by clicking the
Filter button. The back-filter button is used to undo
the last filter; the forward-filter button is used to
reapply a filter.
The MPI Chart Controls tab is also used to show the
details for a selection from the MPI Chart tab.
The Race Details Tab
The Race Details Tab has a toolbar that can be used to
step through the Races while examining the Race Source
context for each race.
This tab is visible only when the Races tab is visible
in the left pane. It is raised whenever a selection is
made in the Races tab. For more information, see the
tha(1) man page.
The Deadlock Details Tab
The Deadlock Details tab shows detailed data for the
selected deadlock in the Deadlock tab.
The Deadlock Details Tab has a toolbar that can be used
to step through the Deadlocks while examining the Race
Source context for each deadlock.
This tab is visible only when the Deadlock tab is visi-
ble in the left pane. It is raised whenever a selection
is made in the Races tab. For more information, see
the tha(1) man page.
Selecting the Data Presentation Options
You can control the presentation of data from the Set Data
Presentation dialog box. To open this dialog box, click on
the Set Data Presentation button in the toolbar or choose
Set Data Presentation from the View menu. The Set Data
Presentation dialog box has a tabbed pane with eight tabs.
The Metrics tab shows all of the available metrics. Each
metric has check boxes in one or more of the columns labeled
Time, Value and %, depending on the type of metric.
Alternatively, instead of setting individual metrics, all
metrics can be set at once by selecting or deselecting the
check boxes in the bottom row of the dialog box and then
clicking on the Apply to all metrics button.
The Sort tab shows the order of the metrics presented, and
the choice of metric to sort by.
The Source/Disassembly tab presents a list of checkboxes
that you can use to select the information presented, as
follows:
o The compiler commentary that is shown in the source
listing and the disassembly listing
o The threshold for highlighting important lines in the
source listing and the disassembly listing
o The interleaving of source code in the disassembly
listing
o The metrics on the source lines in the disassembly
listing
o The display of instructions in hexadecimal in the
disassembly listing.
The Formats tab presents a choice for the long form, short
form, or mangled form of C++ function names and Java method
names. In addition, selecting the Append SO name to Func-
tion name checkbox adds the name of the shared object where
the function or method is located to the end of the function
or method name.
The Formats tab also presents a choice for View Mode of
User, Expert, or Machine. The View Mode setting controls
the processing of Java experiments and OpenMP experiments.
It also contains a setting for enabling or disabling com-
parison mode. See "COMPARISON MODE", below, for more infor-
mation.
The Timeline tab presents choices for the types of event-
specific data that are shown; the display of event-specific
data for threads, LWPs, or CPUs; the alignment of the call
stack representation at the root or at the leaf; and the
number of levels of the call stack that are displayed.
The Search Path tab allows you to manage a list of direc-
tories to be used for searching for source and object files.
The special name "$expts" refers to the experiments loaded;
all other names should be paths in the file system.
The Pathmap tab allows you to manage a list of pathmappings,
as an alternative to Search Path to find source and object
files. Each pathmap has a from-prefix and a to-prefix. If
the full path of a file begins with the from-prefix, a new
path replacing that prefix with the to-prefix will be tried.
Multiple mappings can be used, and they will be tried in
turn.
The Tabs tab allows you to select which of the available
tabs should be shown in the main display. It also has a
list of MemoryObjects and IndexObjects Tabs that are prede-
fined, and has a button to allow you to add custom MemoryOb-
jects or IndexObjects tabs.
The Set Data Presentation dialog box has a Save button with
which you can store the current settings, including any
custom-defined memory objects.
Note: Since the defaults for the Analyzer, er_print utility
and er_src utility are set by a common .er.rc file,
output from er_print utility and er_src utility is
affected as a result of saving changes in the
Analyzer's Set Data Preferences dialog box.
Finding Text and Data
The Analyzer has a Find tool available through the toolbar,
with two options for search targets that are given in a
drop-down list. You can search for text in the Name column
of the Function tab or Callers-Callees tab and in the code
column of the Source tab and Disassembly tab. You can search
for a high-metric item in the Source tab and Disassembly
tab. The metric values on the lines containing high-metric
items are highlighted in green. Use the arrow buttons next
to the Find field to search up or down.
Showing or Hiding Functions
By default, all functions in each load object are shown in
the Function tab and Callers-Callees tab. You can hide all
the functions in a load object or show only those functions
representing the API into the load object using the
Show/Hide Functions dialog box. The dialog box can be opened
from the toolbar or the View menu.
When the functions in a load object are hidden, the Func-
tions tab and Callers-Callees tab show a single entry
representing the aggregate of all functions from the load
object. Similarly, the Lines tab and PCs tab show a single
entry aggregating all PCs from all functions from the load
object.
When only the API functions in a load object are shown, only
those functions representing calls into the library are
shown, and all calls below those functions, whether within
that load object, or into other load objects, including
callbacks, are not shown. The Callers-Callees tab will never
show callees from such functions.
The settings for load objects can be preset with command in
a .er.rc file (See DEFAULTS, below).
In contrast to filtering, metrics corresponding to hidden
functions are still represented in some form in all
displays.
Filtering Data
By default, data is shown in each tab for all experiments,
all samples, all threads, all LWPs, and all CPUs. A subset
of data can be selected using the Filter Data dialog box,
which you open by clicking the Filter Data button in the
toolbar or choosing Filter Data from the View menu.
The Filter Data dialog box has two Tabs, labeled Simple and
Advanced. The Simple tab consists of an Experiment list and
sections for samples, CPUs, LWPs, and threads, each with a
text field used to enter a selection. You can select one or
more experiments from the Experiment list by clicking on the
experiments or using Select All, Clear All, or Reverse but-
tons. You can then use the text boxes to change the data
that is displayed for those experiments. All three filters
can be applied simultaneously, although you should take care
when you interpret data that is filtered by more than one of
CPUs, threads, and LWPs. Use the Enable All, Enable
Selected, Disable All, and Disable Selected buttons to
enable or disable data display for experiments.
The Advanced tab consists of a header and a filter-
specification text box. The header has a text read-only
field for entering a filter clause, and buttons to append
with AND, append with OR, or set the filter to that clause.
The contents of the field are loaded to reflect any single
selection or multiple selection from the Function tab,
DataObject tab, DataLayout tab, or any MemoryObject tabs.
When you click one of the buttons, the selection is
translated into a clause, which is then added to, or
replaces, the filter specification.
The Advanced tab is displayed by clicking the rightmost but-
ton on the button bar, or by switching tabs from the Simple
tab.
When you have composed the filter, either by text-entry into
the filter specification field, or by adding clauses, press
the OK button or the Apply button to set the filter.
If the filter is incorrectly specified, an error will be
posted, and the old filter setting will remain.
Experiment Selection
The Analyzer allows filtering by experiment when more
than one experiment is loaded. The experiments can be
loaded individually, or by naming an experiment group.
Sample Selection
Samples are numbered from 1 to N, and any set of sam-
ples can be selected. The selection consists of a
comma-separated list of sample numbers or ranges such
as 1-5.
Thread Selection
Threads are numbered from 1 to N, and any set of
threads can be selected. The selection consists of a
comma-separated list of thread numbers or ranges. Pro-
file data for threads covers only that part of the run
where the thread was actually scheduled on an LWP.
LWP Selection
LWPs are numbered from 1 to N, and any set of LWPs can
be selected. The selection consists of a comma-
separated list of LWP numbers or ranges. If synchroni-
zation data is recorded, the LWP reported is the LWP at
entry to a synchronization event, which might be dif-
ferent from the LWP at exit from the synchronization
event.
CPU Selection
Where CPU information is recorded (Solaris 9 and
later), any set of CPUs can be selected. The selection
consists of a comma-separated list of CPU numbers or
ranges.
The Advanced tab has a text entry field for entering a
filter expression, as described in the the er_print(1) man
page, under the filters command.
Recording Experiments
When the Analyzer is invoked with a target name and target
arguments, it starts up with the Oracle Solaris Studio Col-
lect dialog box open, allowing you to record an experiment
on the named target. When the Analyzer is invoked with no
arguments, or with an experiment list, you can also record a
new experiment by opening the Oracle Solaris Studio Collect
dialog box by clicking the Collect Experiment button in the
toolbar or choosing Collect Experiment from the File menu.
The Oracle Solaris Studio Collect dialog box has three tabs,
one to describe the experiment, a second to specify the data
to be collected, and a third for the output from collect and
the process.
The first tab is labeled "1. Collect Experiment", and has
fields to name the target, its arguments, the experiment and
its group and directory, as well as the current working
directory. It also has fields allowing you to specify
environment variables, and naming a launcher process, as
would be used for MPI runs. It also has options governing
the data size limit, a time limit for the run, and archive,
descendant process, and signal controls. These options
correspond to the options available in the collect command,
as described in the collect(1) man page. Immediately below
the panel is a Preview Command button, and a text field.
When the button is pressed, the text field is filled in with
the collect command that would be used when the Run button
is pushed. At the bottom of the tab is a set of buttons,
allowing you to launch the run; send Pause, Resume, and Sam-
ple signals to the process during the run (enabled if the
corresponding signals are specified); terminate the run; and
close the dialog box.
The second tab is labeled "2. Data to Collect", and contains
controls for clock and HW counter profiling, for synchroni-
zation and heap tracing, and various other data options. It
also has the same preview button and field, and run controls
as the first tab.
The third tab is labeled "3. Input/Output", and has two
panes, one for the output from collect itself, and a second
for output from the process. It also has the same preview
button and field, and run controls as the first tab.
If the panel is closed while an experiment is in progress,
the experiment continues. If the panel is reinvoked, it
shows the experiment in progress, as if it had been left
open during the run. If you attempt to exit the Analyzer
while an experiment is in progress, a dialog box opens ask-
ing whether you want the run terminated or allowed to con-
tinue.
Generating Mapfiles and Function Reordering
In addition to analyzing the data, the Analyzer provides a
function-reordering capability. Based on the data in an
experiment, the Analyzer can generate a mapfile which, when
used with the static linker (ld) to relink the application,
creates an executable with a smaller working set size, or
better I-cache behavior, or both.
The order of the functions that is recorded in the mapfile
and used to reorder the functions in the executable is
determined by the metric that is used for sorting the func-
tion list. Exclusive User CPU time or Exclusive CPU Cycle
time are normally used for producing a mapfile. Some
metrics, such as those from synchronization delay or heap
tracing, or name or address do not produce meaningful order-
ings for a mapfile.
Other Capabilities
The Analyzer provides in the File menu the ability to add
experiments or experiment groups to the current set, or to
drop experiments from the set.
The Analyzer provides an item in the File menu to create a
new window. When invoked, it opens a duplicate window with
the same settings as the original window. Once the window is
open, you can change settings in either window without
affecting the other.
A few settings are shared by all windows. They share the
set of experiments, so adding or dropping an experiment in
one window affects all windows. The search path setting is
common to all windows.
DEFAULTS
The Analyzer processes directives from a .er.rc file in the
current directory, if present; from a .er.rc file in your
home directory, if present; and from a system er.rc file
installed with the product.
These .er.rc files can contain default settings for which
tabs are visible (tabs), when the Analyzer is brought up.
The tabs are named by the er_print command for the
corresponding report, except for the Experiments Tab, named
headers, the Timeline Tab, named timeline, the Dual Source
Tab, named dsrc, and the Source/Disassembly tab, named
srcdis.
The .er.rc files can also contain default settings for
metrics, sorting, and for specifying compiler commentary
options and highlighting thresholds for source and disassem-
bly output. The files also specify a path for C++ name
demangling for other compilers, as well as default settings
for the Timeline tab, and for name formatting, and setting
View Mode (viewmode).
The .er.rc files can also contain a setting, en_desc
{on|off} to control whether or not descendant experiments
are selected and read when the founder experiment is read.
The .er.rc files can also contain directives to control the
search path for source and object files.
The .er.rc files can also contain directives to control
showing and hiding functions from load objects.
In the Analyzer, an .er.rc file can be saved by clicking on
the Save button in the Set Data Presentation dialog box,
which you can open from the View menu. Saving an .er.rc file
from the Set Data Presentation dialog box affects not only
subsequent invocations of the Analyzer, but also the
er_print utility and er_src utility. See the description of
these directives and files, and their processing, in the
er_print(1) man page.
The Analyzer puts a message into its Errors/Warning logs
areas naming the user .er.rc files it processed, including
any processing message generated when any tab is loaded.
COMPARISON MODE
When the Analyzer is invoked on more than one experiment or
experiment group, it normally will aggregate the data from
all the experiments. If you put compare on in a .er.rc
file it will come up in comparison mode. Comparison mode
may also be set or reset from a context menu in the Func-
tions tab, or from the Data Presentation Dialog.
In comparison mode, the function list will show separate
columns of metrics for each experiment or group, so that the
data may be compared. The columns will have color-coded
headers to distinguish the experiments. Comparison mode
works in the Function Tab, the Caller-Callee Tab, and the
Source and Disassembly Tabs. The Summary Tab will only get
data from the first experiment. The current implementation
is a prototype, and the functionality is expected to change
for the next release.
COMPATIBILITY
The Analyzer works only on experiments recorded with the
tools in one of the following software suites: Sun Studio
12 software, Sun Studio 12 update 1 software, and this ver-
sion of Oracle Solaris Studio software. software.
If invoked on experiments recorded by earlier versions of
the tools, a warning is displayed. In that case, use the
version of Analyzer from the release with which the experi-
ment was recorded.
SEE ALSO
collect(1), collector(1), dbx(1), er_archive(1), er_cp(1),
er_export(1), er_mv(1), er_print(1), er_rm(1), er_src(1),
tha(1), libcollector(3), and the Performance Analyzer
manual.