psrun is a
PerfSuite
command-line utility that can be used to
gather hardware performance information on an unmodified
executable. It's a convenient and flexible way to do quick performance
monitoring/measurement.
psrun operates in one of
two modes: "counting" mode or "profiling"
mode. In counting mode, psrun reports overall
performance information on your program, while in profiling
mode, psrun relates hardware performance
event occurrences to your program's source code in much the same way as
time-based profilers like gprof.
Optionally, psrun can also monitor other resource
usage of an application independent of hardware performance
counters (e.g, maximum memory usage, faults,
swaps, user/system time, exit information, etc).
Here are examples of the type of information that psrun
provides in each mode of operation:
These examples were generated by post-processing the XML output
of psrun with the tool psprocess.
Like several of the other components of PerfSuite, psrun
makes use of the
XML standard for data representation to enhance the flexibility
and cross-platform compatibility of the data collected. Here
is an example XML document created
by psrun.
psrun uses
libperfsuite
and libpshwpc as the
underlying libraries to support hardware performance counting.
By default, libpshwpc uses the PAPI library
(from the Innovative Computing
Laboratory at the University of Tennessee-Knoxville) as the
performance counter support layer, but the software has been
designed to accept alternate support layers as needed.
psrun is available on x86, x86-64, and ia64 platforms and
requires no modifications to your source code or relinking of
your application (you can use it on unmodified binary executables).
psrun supports
both single-threaded and multi-threaded programs using the POSIX
threads standard (pthreads).
psrun is only effective with progams that have been
linked dynamically. If you want to do performance counting with
a statically-linked program, please refer to the section
Troubleshooting and Important Notes/Reminders
for more information.
psrun - PerfSuite performance data collection tool
SYNOPSIS
psrun
[option] command [args]
DESCRIPTION
psrun is a command-line utility that allows you to take
performance measurements of unmodified executables. psrun
takes as input a configuration XML document that describes the desired
measurement. If no XML document is specified through the
command-line option -c, psrun will use a default
configuration. You can determine the default configuration file
that will be used on your system by entering the command psrun -h.
psrun can be used to perform aggregate data collection
("counting mode") or to do statistical profiling ("profiling mode").
By default, psrun operates in counting mode. See the
FILES section below for more information.
psrun uses library preloading to initialize performance
measurement and therefore can only be used with executables that
have been linked dynamically. If you would like to measure the
performance of a statically-linked application, you can insert
calls to the routines in the PerfSuite library libpshwpc
to achieve similar results.
OUTPUT
The output of psrun is an XML document with the root
element <hwpcreport> that contains the resulting
performance data as well as information about other characteristics
of the computer on which the performance data was collected.
By default, the output XML document will be written to a file with
the name command.[threadID].PID.xml, where
command will be replaced with the name of the program
being measured, PID will be replaced with the process ID of
command, and threadID will be replaced with a unique
integer thread identifier ranging from 0 to the number of additional
threads created by command (threadID
will only be present in the file name when support for POSIX
threads is enabled with the option -p).
You can specify a different output document prefix than psrun by
using the option -o.
If the option
-r
is used,
psrun
will gather additional resource usage information and write it
to a separate XML document using the same name template as the
performance data but with the extension
.res.xml.
The root element of the resource usage XML document will be of
type
<resourcereport>.
Typical use of psrun involves measuring the performance
of a program and then post-processing the output with the
utility psprocess. However, customized post-processing
of the output XML document is another option using XML-aware
software of your choice.
You can request output in a plain text (rather than XML) format
by using the option -F text. This can be helpful if you
do not wish to use psprocess to post-process your performance
data.
OPTIONS
-a, --annotate TEXT
Include annotation TEXT in output
-c, --config FILE
Specify configuration file
-d, --domain DOMAIN
Specify counting domain (default user)
-f, --fork
Monitor child processes (default no)
-F, --format FORMAT
Select output format (default XML)
-h, --help
Provide brief help on usage
-o, --output PREFIX
Specify alternate output XML document prefix.
The keywords "stdout" and "stderr" are recognized
(default "psrun")
-p, --pthreads
Enable POSIX thread support
-r, --resource
Collect resource usage information
-t, --threshold INTEGER
Specify the overflow threshold to be used for profiling
-V, --version
Report psrun version
ENVIRONMENT
PS_HWPC_ANNOTATION
Specify annotation text for output
PS_HWPC_CONFIG
Specify configuration file
PS_HWPC_DOMAIN
Select alternate domain (user|kernel|all)
PS_HWPC_EXCLUDEDB
Specify the name of an exclusion database (a flat file containing
full path names of programs that should be excluded from monitoring)
PS_HWPC_FILE
Specify alternate prefix
PS_HWPC_FORMAT
Select output format (text|xml)
PS_HWPC_NOPID
Do not use process ID in output name
PS_HWPC_THRESHOLD
Specify overflow threshold (for profiling)
PS_HWPC_TIME
Specify minimum CPU seconds for output
PSRUN_DOFORK
Monitor child processes
PSRUN_PTHREADLIB
Specify alternate POSIX threads library
LD_PRELOAD
psrun alters the value of this environment variable
before executing command
FILES
The following files are listed relative to the top-level PerfSuite
installation path.
Document Type Definition (DTD) for the output XML document
share/perfsuite/dtds/pshwpc/ps_hwpc_eventlist.dtd
DTD for the input XML document (counting mode)
share/perfsuite/dtds/pshwpc/ps_hwpc_profile.dtd
DTD for the input XML document (profiling mode)
BUGS
Please refer to the file share/perfsuite/doc/BUGS for
information about current known bugs in psrun.
NOTE
This manual page is a brief synopsis of the use of psrun
and may not contain the most current information.
Please refer to the documentation for psrun available
at the PerfSuite web site or in the source code distribution for
complete information about psrun.
Here are some suggestions for troubleshooting use of psrun
when things go wrong, as well as a few notes and reminders regarding
the proper use of psrun:
If you experience run-time errors when you run your program
with psrun, it's a good idea to first double-check that
your application runs properly on its own (this is easy to
forget!)
Because psrun relies on the LD_PRELOAD mechanism
for configuring and starting performance counting, it cannot be
used with executables that are linked statically (-static).
Your application will run as normal, but you will not receive any
XML documents containing the hardware performance counter data.
However, you can easily obtain the same information by directly using
the libpshwpc library with
your application.
psrun should not be used with any programs that already
contain support for accessing the hardware performance counters, as
a conflict will result when the program attempts to access the
counters.
Keep in mind that if your selection of performance counters results
in a multiplexed run,
the numbers reported will be approximate and therefore will be
sensitive to very short-running applications. In general though,
for applications that run a reasonable amount of time (for example,
a minute or longer), you should get meaningful output that may
help you in understanding (and hopefully improving!) the performance
of your application.
PAPI 2's "rate events" (PAPI_FLOPS and PAPI_IPS)
are not supported by libpshwpc (and therefore
psrun) because they are not true event counts, but
derived metrics (which can be derived separately).
If your program
terminates abnormally, you may not receive any performance
data.
You may experience problems if you run a highly-parallel program
and a large number of output files are created all at once, especially
over remote filesystems such as NFS. This may cause failure
of I/O operations with the result being either lost or truncated
XML result documents. To be safe, try to arrange for the XML
to be written to a filesystem local to the computer on which each
process is executing (e.g., use the PS_HWPC_FILE environment
variable, supplying an absolute pathname if necessary).
Note that psrun is meant to be used with compiled executables,
not shell scripts (of course, nothing prevents you from including the
psrun command within your script to measure the performance
of individual commands).
Initialization of libpshwpc, which includes processing
of the event configuration file, occurs prior to the execution of your
application. This means that any modifications to environment
variables such as PS_HWPC_CONFIG from within your program will have no
effect on the run.