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 in the loaded experiments 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 Call Tree tab
o The Source tab
o The Source/Disassembly tab
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.
Most of the left-hand tabs have a context menu, which you
open by right-clicking on an item in the tab. You can use
the context menu to set filters or to set various options.
The Set Data Presentation dialog box contains a Tabs tab
that shows all available regular tabs in one column, tabs
for IndexObject tabs in the center, and all defined
MemoryObject tabs in a third column, with checkboxes for all
applicable tabs.
The right pane contains the MPI Timeline Control Tab, the
MPI Chart Control Tab, the Summary tab, the Timeline Details
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 context menu for the Functions Tab can be used to
set filters either for a specific function, or for a
pattern matching the name of the selected function. In
addition, double-clicking on any line in the Functions
Tab will bring up the Source Tab for that function.
The Callers-Callees Tab
The Callers-Callees tab enables you to examine metrics
for a particular sequence of function calls by select-
ing a function and incrementally choosing which of its
callers and callees you want to examine. Select a func-
tion of interest in another data tab such as the Func-
tions tab, then click 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 por-
tion of the callee's inclusive metric that is attribut-
able 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 func-
tion.
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 data tab updates
the Callers-Callees tab to center it on the selected
function.
The center area of the Callers-Callees Tab contains
buttons 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 Callers-Callees tab will bring up
an option menu to manage the callstack fragment, or add
a filter, or navigate forward or backwards through the
history.
The Call Tree Tab
The Call Tree 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 Call Tree 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
threshold 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.
Double-clicking on any line in the Source Tab will
bring up the Disassembly Tab at or near the first
instruction from that source line
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.
Double clicking on a line in the Lines Tab will bring
up the source display at or near that 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.
Double clicking on a PC in the PCs Tab will bring up
the Disassembly Tab at or near that PC.
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.
Several IndexObjects tabs are predefined: Threads,
CPUs, Samples, and Seconds. A button in the Tabs tab
of the Set Data Presentation dialog box can be used to
define a custom index object, by assigning 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 information.
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.
One of the Index Object Tabs, the Threads tab, has an
additional radio button option specifying a chart view
of the data. By default, a chart of "Load Imbalance"
will be shown. Other charts can be selected from the
Threads Chart Controls tab on the right side.
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, thread, or CPU, or one set for the
entire experiment. Each such set 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
Timeline Details 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 an event marker selects the correspond-
ing event and displays the data for that event and its
call stack in the Timeline Details tab. Double-clicking
a frame in the call stack opens the Function Color
Chooser dialog box, which enables you to change the
colors for any function displayed in the timeline.
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 drawn, 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, or aggregated
for the entire experiment; 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 buttons in the Timeline
Details tab 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.
The Timeline preferences also allow the selection of
either a thread-state or event-count graph underneath
each bar.
Experiments are selected for display using the Manage
Filters dialog box.
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 Timeline Details Tab
The Timeline Details 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 function in the call stack makes it the
selected function.
When a sample is selected in the Timeline tab, the
Timeline Details 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 Timeline Details 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 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.
MPI 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. MPI Filters are shared between the MPI
Timeline 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 Help menu and the Performance Analyzer MPI
Tutorial for further information.
MPI 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; an event-state or event-count
graph; the display of event-specific data for threads, LWPs,
CPUs, or experiments; 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.
You must click OK or Apply to apply your changes to the
current session. The Set Data Presentation dialog box has a
Save button with which you can store the current settings,
including any custom-defined memory objects. The settings
will then be used in future sessions.
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 yellow. 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 data tab for all functions
in all experiments, all samples, all threads, and all CPUs.
You can select a subset of data by using predefined context
filters in the following data tabs: Functions, Callers-
Callees, Call Tree, Timeline, Experiments, Threads, CPUs,
Samples, and Seconds. Select an item of interest in one of
these tabs, then right-click with the mouse to select a con-
text filter. The filter is immediately applied across the
data tabs that support filtering. Context filters are ANDed
together so that each context filter selected further nar-
rows down the displayed data. The data must match all the
filters in order to be shown.
You can also filter data by using the Manage Filters dialog
box, which you open by clicking the Manage Filters button in
the toolbar, or choosing Manage Filters from the View menu,
or by selecting Manage Filters from the context menu.
The Manage Filters dialog box has three tabs:
Experiments, General, and Custom. The Experiments and Gen-
eral tab operate together, but independently of the Custom
tab.
Experiments tab
The Experiments tab of the Manage Filters dialog box
shows a list of loaded experiments. You can select
experiments whose data you want to see by clicking the
check boxes next to their names. Select or deselect all
the experiments at once by clicking the Enable check
box at the top of the list.
General tab
The General tab of the Manage Filters dialog box
enables you to select samples, threads, and CPUs whose
data you want to include in the Analyzer data tabs. The
items are identified by numbers that are also shown in
the Samples, Threads, and CPUs tabs, and in the Time-
line tab. To add tabs to the Analyzer display, use the
Set Data Presentation dialog box.
The General tab works together with the Experiments
tab. The experiments selected in the Experiments tab
determine the numbers of samples, threads, and CPUs
shown in the General tab. Each of the items are num-
bered from 1 to N, where N is dynamically determined,
based on the selected experiment.
You can specify any set of each item (samples, threads,
and CPUs) by typing in each text box a list of item
numbers separated by spaces or commas, or ranges such
as 1-5. To include all the items from a set, select
"all" in the combo-box menu for that set.
The selections made in the Experiments and General tabs
are combined for filtering; data must match all the
selections made in these tabs to be included in the
data tabs.
Custom tab
The Custom tab of the Manage Filters dialog box shows a
Filter Specification that contains the filter expres-
sions that are created by the Analyzer in response to
predefined filter selections made in data tabs. The
predefined filters and Custom filters are separate from
the filters applied through the Experiments and General
tabs.
The text of the Filter Specification box is editable;
you can customize it as you like and click "Apply" or
"OK" to filter the data according to the filter expres-
sions displayed.
If the filter is incorrectly specified, an error will
be posted, and the old filter setting will remain.
The syntax for filter expressions shown in the Filter
Expression box is the same as that used for filtering
with the er_print command and is described in the
er_print(1) man page, under the filters command.
All changes within the Custom tab, including undo and
redo, take effect only after "Apply" or "OK" is
pressed.
The Custom tab has a button "Show Keywords", which will
bring up a popup window that shows all the keywords
that can be used in composing filters for the experi-
ments as loaded. That popup also includes any labels
set by er_label.
The Custom tab also has undo and redo buttons for undo-
ing or redoing changes to the filters, whether made by
hand, or by context menu operations. Those buttons do
not immediately undo or redo filters. You must click
on "OK" or "Apply" to have the changes take effect.
Setting filters from a context menu
When a context menu item for filtering is selected, the
filter is immediately ANDed with any existing filter
and applied. An event must satisfy all filters to be
counted.
The context menu also supports undoing the last filter
applied. The undo operation takes place immediately.
For further managing the filters, you can use the Cus-
tom filter tab, and edit the filter expression as you
like.
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
Mapfile generation is obsolete and no longer supported.
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 Set 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
Analyzer will only work on experiments recorded with the
current version of the tools. It will report an error for
experiments recorded with any other version. You should use
the version of Analyzer from the release with which the
experiment 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), the Performance Analyzer manual,
and the Performance Analyzer MPI Tutorial.