NAME
spot - run a tool chain on an executable, and generate a
website for browsing the data
SYNOPSIS
spot [ options ] [ target target-args | -p pid ]
DESCRIPTION
The spot command runs a set of performance tools on the tar-
get application and renders the output as a set of hyper-
linked webpages. There are two ways that spot can be used:
spot -P pid
spot attaches to a running process and gathers data
from the running process using a variety of probes.
spot app params
The application is run multiple times, each time under
a different probe. So it is necessary for the applica-
tion to be able to run multiple times without user
intervention.
The webpages that spot produces record the following infor-
mation (if it is available).
System information
Information about the system which the experiment was
collected on
Build information
Information about how the application was built
Performance counter data
Performance counter events recorded by the CPU during
the run of the application. This data can be used to
indicate the types of events which are causing signifi-
cant stall time.
Instruction frequency data
This indicates the mix of instructions executed by the
application (SPARC only).
Time spent in code
This data is from the collect command which returns the
amount of time spent in the various routines. This data
is rendered using er_html.
Stall time profiles
The collect command is used to profile the application
based on the performance counter events that contribute
the largest stall time. The resulting profiles indicate
where in the program the stall events are occurring.
This data is rendered using er_html.
Execution counts
This data indicates how often each routine is called,
and also how often each individual instruction in the
routine is called (SPARC only).
System-wide bandwidth utilization
Data on utilization of system-wide utilization of
bandwidth for all running processes. It is not possible
to attribute bandwidth to a particular process unless
that process is the only one active at the time. This
data can only be collected if the user has the
appropriate permissions to access the performance
counters on a system-wide basis. (SPARC only).
Trap information
Data on the number of traps encountered over the run of
the program. This information is only available if the
user has the appropriate permissions to access trapstat
data (SPARC only).
If gnuplot is available on the path, then additional graphs
will be available that show the various events over time.
OPTIONS
If invoked with no arguments, print a usage message. If
/bin/perl is not installed on the system, fail with the mes-
sage: "spot: Command not found", even though it is perl, not
spot that is missing. If the version of perl on the system
is not recent enough, spot may fail with a message about an
undefined variable.
-c path
Specify a path for the Oracle Solaris Studio components
used by spot. If both Oracle Solaris Studio and spot
are installed in their default locations, spot will
find the components it needs. However, if either of
them is installed in a different location, then this
option can be used to specify the path. This option is
also useful if the user wants to override the default
compiler and use a compiler installed in a location
different from the default one.
-D n Set the level of debug information to be printed. The
default is 1. A setting of 0 means no output from spot,
a setting of 2 means full debug information. The debug
output will be available in debug.log in the completed
report.
-d directory
Place output from spot in a subdirectory of the speci-
fied directory. If not specified, the default is to
place the data in the current directory.
-h Print help information.
-o name
Place the output from spot in the named subdirectory
named name<n> where n is the first name not in use. If
the name is specified, it may have any form, as long as
the directory does not exist at the time spot is
invoked. If the name is not specified then spot will
default to using spot_run<n>
-P pid
Attach spot to a running process and produce report.
-q Suppress all spot output. (Equivanlent to -D 0)
-T seconds
This option is only valid when spot is attaching to a
running process. It sets the number of seconds for
which each of the probes should be attached to the pro-
cess. The default is 300 seconds (5 minutes).
-V Print the current version. Do not examine further
arguments and perform no further processing.
-v Print the current version and further detailed debug-
ging information about the conversion being run.
(Equivalent to -D 2)
-X This option will cause spot to try to collect extended
information about the performance of the application.
It will collect hardware counter profiles of the appli-
cation using those performance counters that have been
identified by ripc as large contributors to the overall
stall time. If possible, bandwidth and trap data will
also be collected; the user needs the appropriate per-
missions for bandwidth and trap data to be collected.
SEE ALSO
analyzer(1), collect(1), er_archive(1), er_cp(1),
er_export(1), er_html(1), er_mv(1), er_print(1), er_rm(1),
er_src(1), and the Performance Analyzer manual.