spot - run a tool chain on an executable and generate a web site for browsing the data
spot [ options ] [ target target-args | -p pid ]
spot [-aca args] [-c path] [-cpa args] [-d dir] [-D n] [-di] [-h]
[-ndi] [-nsi] [-o name] [-P pid] [-q] [-si] [-T seconds]
[-v] [-V] [-X] app params
The spot command runs a set of performance tools on the target application and renders the output as a set of linked web pages. You can use spot in the following ways:
spot attaches to a running process and gathers data from the running process using a variety of probes.
The application is run multiple times, each time under a different probe. The application must be able to run multiple times without user intervention.
The web pages that spot produces record the following information (if it is available).
Information about the system on which the experiment was collected
Information about how the application was built
Performance counter events recorded by the CPU during the run of the application. This data can be used to indicate the types of events that are causing significant stall time.
This indicates the mix of instructions executed by the application (SPARC only).
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.
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.
This data indicates how often each routine is called, and also how often each individual instruction in the routine is called (SPARC only).
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).
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 your path, then additional graphs will be available that show the various events over time.
If invoked with no arguments, print a usage message. If /bin/perl is not installed on the system, fail with the message: "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 might fail with a message about an undefined variable.
Certain options can be set in a $HOME/.er_html.rc file (see at the end of this section).
Inserts args into all collect calls. For example:
-aca "-A src"
Specify a path for the Oracle Developer Studio components to be used by spot. If both Oracle Developer 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, you can use this option to specify the path. This option is also useful if you want to override the default compiler and use a compiler installed in a location different from the default one.
Inserts args into the collect profile call. By default, this is "–h on" if the platform supports hardware counter profiling.
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 is in debug.log in the completed report.
Place output from spot in a subdirectory of the specified directory. If not specified, the default is to place the data in the current directory.
Produce DWARF info (default).
Print help information.
Do not produce any DWARF info.
Do not produce any stabs info.
Place the output from spot in the subdirectory subdir-name. By default if the subdirectory name is not specified spot uses spot_runn where n is a unique number. If you specify a name it can have any form as long as the directory does not exist at the time spot is invoked.
Attach spot to a running process and produce report.
Suppress all spot output. Equivanlent to –D 0.
Produce stabs info (default).
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 process. The default is 300 seconds (5 minutes).
Print the current version. Do not examine further arguments and perform no further processing.
Print the current version and further detailed debugging information about the conversion being run. Equivalent to –D 2.
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 application 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. Your user account must have appropriate permissions for bandwidth and trap data to be collected.
The –di and –si command line options above are only really of any use if you have a $HOME/.er_spot.rc file with ndi and nsi and you want to reverse their effect without changing the file.
Options that can be set in a $HOME/.er_spot.rc file:
There are a few equivalent options command line .er_spot.rc file -aca aca -cpa cpa -ndi ndi -nsi nsi For example aca -A src cpa -h hi ndi nsi
The environment variables ER_HTML_DIR, SPOT_CMDS and SPOT_DIR can be used.
Set to the path of er_html if you have a local copy of er_html to test or use.
Set to 1 if you want a record of the spot commands and their timing. This will produce two files named SPOT_CMDS and SPOT_CMDS_TIMING file in the spot_runn subdirectory or the –o specified spot results directory. Use the spot_cmds and spot_cmds_timing commands in that directory to see a list of commands spot issued and command timings.
Set to the path of spot if you are using a local copy of spot, in which case you would invoke spot as follows:
$PATH/bin/spot
analyzer(1), collect(1), er_archive(1), er_cp(1), er_export(1), er_html(1), er_html_cols(1), er_html_columnsD(1), er_html_columnsI(1), er_mv(1), er_print(1), er_rm(1), er_src(1), spot_cmds(1), spot_cmds_timing(1), spot_diff(1)